-
-Follow the instructions to install the cs launcher then run:
$ ./cs setup
-
-
-
-Along with managing JVMs, it also installs useful command line tools:
-[Ammonite](https://ammonite.io/),
-[coursier](https://get-coursier.io/),
-scala (the Scala REPL and script runner),
-scalac (the Scala compiler),
-[sbt](https://www.scala-sbt.org/), and
-[scalafmt](https://scalameta.org/scalafmt/).
-
-For more information, read [coursier-cli documentation](https://get-coursier.io/docs/cli-overview).
-
-### ...Or manually
-1. if you don't have Java 8 or 11 installed, download
-Java from [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html),
-or [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Refer to [JDK Compatibility](/overviews/jdk-compatibility/overview.html) for Scala/Java compatibility detail.
-1. Install [sbt](https://www.scala-sbt.org/download.html)
-
-## Create a Hello-world project with sbt
-To create a project, you can either use a command-line tool or an IDE.
-If you are familiar with the command line, we recommend that approach.
-
-### Using command-line
-sbt is a build tool for Scala. sbt compiles, runs,
-and tests your Scala code. (It can also publish libraries and do many other tasks.)
-
-1. `cd` to an empty folder.
-1. Run the following command `sbt new scala/hello-world.g8`.
-This pulls the 'hello-world' template from GitHub.
-It will also create a `target` folder, which you can ignore.
-1. When prompted, name the application `hello-world`. This will
-create a project called "hello-world".
-1. Let's take a look at what just got generated:
-
-```
-- hello-world
- - project (sbt uses this for its own files)
- - build.properties
- - build.sbt (sbt's build definition file)
- - src
- - main
- - scala (all of your Scala code goes here)
- - Main.scala (Entry point of program) <-- this is all we need for now
-```
-
-More documentation about sbt can be found in the [Scala Book](/overviews/scala-book/scala-build-tool-sbt.html)
-and in the official sbt [documentation](https://www.scala-sbt.org/1.x/docs/index.html)
-
-### With an IDE
-You can skip the rest of this page and go directly to [Building a Scala Project with IntelliJ and sbt](/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html#next-steps)
-
-
-## Open hello-world project
-Let's use an IDE to open the project. The most popular ones are IntelliJ and VSCode.
-They both offer rich IDE features, but you can still use [many other editors.](https://scalameta.org/metals/docs/editors/overview.html)
-### Using IntelliJ
-1. Download and install [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
-1. Install the Scala plugin by following [the instructions on how to install IntelliJ plugins](https://www.jetbrains.com/help/idea/managing-plugins.html)
-1. Open the `build.sbt` file then choose *Open as a project*
-
-### Using VSCode with metals
-1. Download [VSCode](https://code.visualstudio.com/Download)
-1. Install the Metals extension from [the Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals)
-1. Next, open the directory containing a `build.sbt` file. When prompted to do so, select *Import build*.
-
-## Run Hello World
-Open a terminal
-1. `cd` into `hello-world`.
-1. Run `sbt`. This will open up the sbt console.
-1. Type `~run`. The `~` is optional and causes sbt to re-run on every file save,
-allowing for a fast edit/run/debug cycle. sbt will also generate a `target` directory
-which you can ignore.
-
-
-## Next Steps
-Once you've finished the above tutorials, consider checking out:
-
-* [The Scala Book](/overviews/scala-book/introduction.html), which provides a set of short lessons introducing Scala’s main features.
-* [The Tour of Scala](/tour/tour-of-scala.html) for bite-sized introductions to Scala's features.
-* [Learning Resources](/learn.html), which includes online interactive tutorials and courses.
-* [Our list of some popular Scala books](/books.html).
-
-## Getting Help
-There are a multitude of mailing lists and real-time chat rooms in case you want to quickly connect with other Scala users. Check out our [community](https://scala-lang.org/community/) page for a list of these resources, and for where to reach out for help.
-
-
-
-
-
-
-
-
-
diff --git a/_glossary/index.md b/_glossary/index.md
index 3eba952f88..9d4d490c65 100644
--- a/_glossary/index.md
+++ b/_glossary/index.md
@@ -16,380 +16,380 @@ languages: [zh-cn]
-* #### algebraic data type
+* ### algebraic data type
A type defined by providing several alternatives, each of which comes with its own constructor. It usually comes with a way to decompose the type through pattern matching. The concept is found in specification languages and functional programming languages. Algebraic data types can be emulated in Scala with case classes.
-* #### alternative
+* ### alternative
A branch of a match expression. It has the form “`case` _pattern_ => _expression_.” Another name for alternative is _case_.
-* #### annotation
+* ### annotation
An annotation appears in source code and is attached to some part of the syntax. Annotations are computer processable, so you can use them to effectively add an extension to Scala.
-* #### anonymous class
+* ### anonymous class
An anonymous class is a synthetic subclass generated by the Scala compiler from a new expression in which the class or trait name is followed by curly braces. The curly braces contains the body of the anonymous subclass, which may be empty. However, if the name following new refers to a trait or class that contains abstract members, these must be made concrete inside the curly braces that define the body of the anonymous subclass.
-* #### anonymous function
+* ### anonymous function
Another name for [function literal](#function-literal).
-* #### apply
+* ### apply
You can apply a method, function, or closure to arguments, which means you invoke it on those arguments.
-* #### argument
+* ### argument
When a function is invoked, an argument is passed for each parameter of that function. The parameter is the variable that refers to the argument. The argument is the object passed at invocation time. In addition, applications can take (command line) arguments that show up in the `Array[String]` passed to main methods of singleton objects.
-* #### assign
+* ### assign
You can assign an object to a variable. Afterwards, the variable will refer to the object.
-* #### auxiliary constructor
+* ### auxiliary constructor
Extra constructors defined inside the curly braces of the class definition, which look like method definitions named `this`, but with no result type.
-* #### block
-One or more expressions and declarations surrounded by curly braces. When the block evaluates, all of its expressions and declarations are processed in order, and then the block returns the value of the last expression as its own value. Blocks are commonly used as the bodies of functions, [for expressions](#for-expression), `while` loops, and any other place where you want to group a number of statements together. More formally, a block is an encapsulation construct for which you can only see side effects and a result value. The curly braces in which you define a class or object do not, therefore, form a block, because fields and methods (which are defined inside those curly braces) are visible from the out- side. Such curly braces form a template.
+* ### block
+One or more expressions and declarations surrounded by curly braces. When the block evaluates, all of its expressions and declarations are processed in order, and then the block returns the value of the last expression as its own value. Blocks are commonly used as the bodies of functions, [for expressions](#for-expression), `while` loops, and any other place where you want to group a number of statements together. More formally, a block is an encapsulation construct for which you can only see side effects and a result value. The curly braces in which you define a class or object do not, therefore, form a block, because fields and methods (which are defined inside those curly braces) are visible from the outside. Such curly braces form a template.
-* #### bound variable
+* ### bound variable
A bound variable of an expression is a variable that’s both used and defined inside the expression. For instance, in the function literal expression `(x: Int) => (x, y)`, both variables `x` and `y` are used, but only `x` is bound, because it is defined in the expression as an `Int` and the sole argument to the function described by the expression.
-* #### by-name parameter
+* ### by-name parameter
A parameter that is marked with a `=>` in front of the parameter type, e.g., `(x: => Int)`. The argument corresponding to a by-name parameter is evaluated not before the method is invoked, but each time the parameter is referenced by name inside the method. If a parameter is not by-name, it is by-value.
-* #### by-value parameter
+* ### by-value parameter
A parameter that is not marked with a `=>` in front of the parameter type, e.g., `(x: Int)`. The argument corresponding to a by-value parameter is evaluated before the method is invoked. By-value parameters contrast with by-name parameters.
-* #### class
+* ### class
Defined with the `class` keyword, a _class_ may either be abstract or concrete, and may be parameterized with types and values when instantiated. In `new Array[String](2)`, the class being instantiated is `Array` and the type of the value that results is `Array[String]`. A class that takes type parameters is called a _type constructor_. A type can be said to have a class as well, as in: the class of type `Array[String]` is `Array`.
-* #### closure
+* ### closure
A function object that captures free variables, and is said to be “closed” over the variables visible at the time it is created.
-* #### companion class
+* ### companion class
A class that shares the same name with a singleton object defined in the same source file. The class is the singleton object’s companion class.
-* #### companion object
+* ### companion object
A singleton object that shares the same name with a class defined in the same source file. Companion objects and classes have access to each other’s private members. In addition, any implicit conversions defined in the companion object will be in scope anywhere the class is used.
-* #### contravariant
+* ### contravariant
A _contravariant_ annotation can be applied to a type parameter of a class or trait by putting a minus sign (-) before the type parameter. The class or trait then subtypes contravariantly with—in the opposite direction as—the type annotated parameter. For example, `Function1` is contravariant in its first type parameter, and so `Function1[Any, Any]` is a subtype of `Function1[String, Any]`.
-* #### covariant
+* ### covariant
A _covariant_ annotation can be applied to a type parameter of a class or trait by putting a plus sign (+) before the type parameter. The class or trait then subtypes covariantly with—in the same direction as—the type annotated parameter. For example, `List` is covariant in its type parameter, so `List[String]` is a subtype of `List[Any]`.
-* #### currying
+* ### currying
A way to write functions with multiple parameter lists. For instance `def f(x: Int)(y: Int)` is a curried function with two parameter lists. A curried function is applied by passing several arguments lists, as in: `f(3)(4)`. However, it is also possible to write a _partial application_ of a curried function, such as `f(3)`.
-* #### declare
+* ### declare
You can _declare_ an abstract field, method, or type, which gives an entity a name but not an implementation. The key difference between declarations and definitions is that definitions establish an implementation for the named entity, declarations do not.
-* #### define
+* ### define
To _define_ something in a Scala program is to give it a name and an implementation. You can define classes, traits, singleton objects, fields, methods, local functions, local variables, _etc_. Because definitions always involve some kind of implementation, abstract members are declared not defined.
-* #### direct subclass
+* ### direct subclass
A class is a _direct subclass_ of its direct superclass.
-* #### direct superclass
+* ### direct superclass
The class from which a class or trait is immediately derived, the nearest class above it in its inheritance hierarchy. If a class `Parent` is mentioned in a class `Child`’s optional extends clause, then `Parent` is the direct superclass of `Child`. If a trait is mentioned in `Child`’s extends clause, the trait’s direct superclass is the `Child`’s direct superclass. If `Child` has no extends clause, then `AnyRef` is the direct superclass of `Child`. If a class’s direct superclass takes type parameters, for example class `Child` extends `Parent[String]`, the direct superclass of `Child` is still `Parent`, not `Parent[String]`. On the other hand, `Parent[String]` would be the direct supertype of `Child`. See [supertype](#supertype) for more discussion of the distinction between class and type.
-* #### equality
+* ### equality
When used without qualification, _equality_ is the relation between values expressed by `==`. See also [reference equality](#reference-equality).
-* #### existential type
+* ### existential type
An existential type includes references to type variables that are unknown. For example, `Array[T] forSome { type T }` is an existential type. It is an array of `T`, where `T` is some completely unknown type. All that is assumed about `T` is that it exists at all. This assumption is weak, but it means at least that an `Array[T] forSome { type T }` is indeed an array and not a banana.
-* #### expression
+* ### expression
Any bit of Scala code that yields a result. You can also say that an expression _evaluates_ to a result or _results_ in a value.
-* #### filter
+* ### filter
An `if` followed by a boolean expression in a [for expression](#for-expression). In `for(i <- 1 to 10; if i % 2 == 0)`, the filter is “`if i % 2 == 0`”. The value to the right of the `if` is the [filter expression](#filter-expression). Also known as a guard.
-* #### filter expression
+* ### filter expression
A _filter expression_ is the boolean expression following an `if` in a [for expression](#for-expression). In `for( i <- 1 to 10 ; if i % 2 == 0)`,the filter expression is “`i % 2 == 0`”.
-* #### first-class function
+* ### first-class function
Scala supports _first-class functions_, which means you can express functions in function literal syntax, i.e., `(x: Int) => x + 1`, and that functions can be represented by objects, which are called [function values](#function-value).
-* #### for comprehension
+* ### for comprehension
A _for comprehension_ is a type of [for expression](#for-expression) that creates a new collection. For each iteration of the `for` comprehension, the [yield](#yield) clause defines an element of the new collection. For example, `for (i <- (0 until 2); j <- (2 until 4)) yield (i, j)` returns the collection `Vector((0,2), (0,3), (1,2), (1,3))`.
-* #### for expression
+* ### for expression
A _for expression_ is either a [for loop](#for-loop), which iterates over one or more collections, or a [for comprehension](#for-comprehension), which builds a new collection from the elements of one or more collections. A `for` expression is built up of [generators](#generator), [filters](#filter), variable definitions, and (in the case of [for comprehensions](#for-comprehension)) a [yield](#yield) clause.
-* #### for loop
+* ### for loop
A _for loop_ is a type of [for expression](#for-expression) that loops over one or more collections. Since `for` loops return unit, they usually produce side-effects. For example, `for (i <- 0 until 100) println(i)` prints the numbers 0 through 99.
-* #### free variable
+* ### free variable
A _free variable_ of an expression is a variable that’s used inside the expression but not defined inside the expression. For instance, in the function literal expression `(x: Int) => (x, y)`, both variables `x` and `y` are used, but only `y` is a free variable, because it is not defined inside the expression.
-* #### function
+* ### function
A _function_ can be [invoked](#invoke) with a list of arguments to produce a result. A function has a parameter list, a body, and a result type. Functions that are members of a class, trait, or singleton object are called [methods](#method). Functions defined inside other functions are called [local functions](#local-function). Functions with the result type of `Unit` are called [procedures](#procedure). Anonymous functions in source code are called [function literals](#function-literal). At run time, function literals are instantiated into objects called [function values](#function-value).
-* #### function literal
+* ### function literal
A function with no name in Scala source code, specified with _function literal_ syntax. For example, `(x: Int, y: Int) => x + y`.
-* #### function value
+* ### function value
A function object that can be invoked just like any other function. A _function value_’s class extends one of the `FunctionN` traits (e.g., `Function0`, `Function1`) from package `scala`, and is usually expressed in source code via [function literal](#function-literal) syntax. A function value is “invoked” when its apply method is called. A function value that captures free variables is a [closure](#closure).
-* #### functional style
+* ### functional style
The _functional style_ of programming emphasizes functions and evaluation results and deemphasizes the order in which operations occur. The style is characterized by passing function values into looping methods, immutable data, methods with no side effects. It is the dominant paradigm of languages such as Haskell and Erlang, and contrasts with the [imperative style](#imperative-style).
-* #### generator
+* ### generator
A _generator_ defines a named val and assigns to it a series of values in a [for expression](#for-expression). For example, in `for(i <- 1 to 10)`, the generator is “`i <- 1 to 10`”. The value to the right of the `<-` is the [generator expression](#generator-expression).
-* #### generator expression
+* ### generator expression
A _generator expression_ generates a series of values in a [for expression](#for-expression). For example, in `for(i <- 1 to 10)`, the generator expression is “`1 to 10`”.
-* #### generic class
+* ### generic class
A class that takes type parameters. For example, because `scala.List` takes a type parameter, `scala.List` is a _generic class_.
-* #### generic trait
+* ### generic trait
A trait that takes type parameters. For example, because trait `scala.collection.Set` takes a type parameter, it is a _generic trait_.
-* #### guard
+* ### guard
See [filter](#filter).
-* #### helper function
+* ### helper function
A function whose purpose is to provide a service to one or more other functions nearby. Helper functions are often implemented as local functions.
-* #### helper method
+* ### helper method
A [helper function](#helper-function) that’s a member of a class. Helper methods are often private.
-* #### immutable
+* ### immutable
An object is _immutable_ if its value cannot be changed after it is created in any way visible to clients. Objects may or may not be immutable.
-* #### imperative style
+* ### imperative style
The _imperative style_ of programming emphasizes careful sequencing of operations so that their effects happen in the right order. The style is characterized by iteration with loops, mutating data in place, and methods with side effects. It is the dominant paradigm of languages such as C, C++, C# and Java, and contrasts with the [functional style](#functional-style).
-* #### initialize
+* ### initialize
When a variable is defined in Scala source code, you must _initialize_ it with an object.
-* #### instance
+* ### instance
An _instance_, or class instance, is an object, a concept that exists only at run time.
-* #### instantiate
+* ### instantiate
To _instantiate_ a class is to make a new object from the class, an action that happens only at run time.
-* #### invariant
+* ### invariant
_Invariant_ is used in two ways. It can mean a property that always holds true when a data structure is well-formed. For example, it is an invariant of a sorted binary tree that each node is ordered before its right subnode, if it has a right subnode. Invariant is also sometimes used as a synonym for nonvariant: “class `Array` is invariant in its type parameter.”
-* #### invoke
+* ### invoke
You can _invoke_ a method, function, or closure _on_ arguments, meaning its body will be executed with the specified arguments.
-* #### JVM
+* ### JVM
The _JVM_ is the Java Virtual Machine, or [runtime](#runtime), that hosts a running Scala program.
-* #### literal
+* ### literal
`1`, `"One"`, and `(x: Int) => x + 1` are examples of _literals_. A literal is a shorthand way to describe an object, where the shorthand exactly mirrors the structure of the created object.
-* #### local function
+* ### local function
A _local function_ is a `def` defined inside a block. To contrast, a `def` defined as a member of a class, trait, or singleton object is called a [method](#method).
-* #### local variable
+* ### local variable
A _local variable_ is a `val` or `var` defined inside a block. Although similar to [local variables](#local-variable), parameters to functions are not referred to as local variables, but simply as parameters or “variables” without the “local.”
-* #### member
+* ### member
A _member_ is any named element of the template of a class, trait, or singleton object. A member may be accessed with the name of its owner, a dot, and its simple name. For example, top-level fields and methods defined in a class are members of that class. A trait defined inside a class is a member of its enclosing class. A type defined with the type keyword in a class is a member of that class. A class is a member of the package in which is it defined. By contrast, a local variable or local function is not a member of its surrounding block.
-* #### message
+* ### message
Actors communicate with each other by sending each other _messages_. Sending a message does not interrupt what the receiver is doing. The receiver can wait until it has finished its current activity and its invariants have been reestablished.
-* #### meta-programming
+* ### meta-programming
Meta-programming software is software whose input is itself software. Compilers are meta-programs, as are tools like `scaladoc`. Meta-programming software is required in order to do anything with an annotation.
-* #### method
+* ### method
A _method_ is a function that is a member of some class, trait, or singleton object.
-* #### mixin
+* ### mixin
_Mixin_ is what a trait is called when it is being used in a mixin composition. In other words, in “`trait Hat`,” `Hat` is just a trait, but in “`new Cat extends AnyRef with Hat`,” `Hat` can be called a mixin. When used as a verb, “mix in” is two words. For example, you can _mix_ traits _in_ to classes or other traits.
-* #### mixin composition
+* ### mixin composition
The process of mixing traits into classes or other traits. _Mixin composition_ differs from traditional multiple inheritance in that the type of the super reference is not known at the point the trait is defined, but rather is determined anew each time the trait is mixed into a class or other trait.
-* #### modifier
+* ### modifier
A keyword that qualifies a class, trait, field, or method definition in some way. For example, the `private` modifier indicates that a class, trait, field, or method being defined is private.
-* #### multiple definitions
+* ### multiple definitions
The same expression can be assigned in _multiple definitions_ if you use the syntax `val v1, v2, v3 = exp`.
-* #### nonvariant
+* ### nonvariant
A type parameter of a class or trait is by default _nonvariant_. The class or trait then does not subtype when that parameter changes. For example, because class `Array` is nonvariant in its type parameter, `Array[String]` is neither a subtype nor a supertype of `Array[Any]`.
-* #### operation
+* ### operation
In Scala, every _operation_ is a method call. Methods may be invoked in _operator notation_, such as `b + 2`, and when in that notation, `+` is an _operator_.
-* #### parameter
+* ### parameter
Functions may take zero to many _parameters_. Each parameter has a name and a type. The distinction between parameters and arguments is that arguments refer to the actual objects passed when a function is invoked. Parameters are the variables that refer to those passed arguments.
-* #### parameterless function
+* ### parameterless function
A function that takes no parameters, which is defined without any empty parentheses. Invocations of parameterless functions may not supply parentheses. This supports the [uniform access principle](#uniform-access-principle), which enables the `def` to be changed into a `val` without requiring a change to client code.
-* #### parameterless method
+* ### parameterless method
A _parameterless method_ is a parameterless function that is a member of a class, trait, or singleton object.
-* #### parametric field
+* ### parametric field
A field defined as a class parameter.
-* #### partially applied function
+* ### partially applied function
A function that’s used in an expression and that misses some of its arguments. For instance, if function `f` has type `Int => Int => Int`, then `f` and `f(1)` are _partially applied functions_.
-* #### path-dependent type
+* ### path-dependent type
A type like `swiss.cow.Food`. The `swiss.cow` part is a path that forms a reference to an object. The meaning of the type is sensitive to the path you use to access it. The types `swiss.cow.Food` and `fish.Food`, for example, are different types.
-* #### pattern
+* ### pattern
In a `match` expression alternative, a _pattern_ follows each `case` keyword and precedes either a _pattern guard_ or the `=>` symbol.
-* #### pattern guard
+* ### pattern guard
In a `match` expression alternative, a _pattern guard_ can follow a [pattern](#pattern). For example, in “`case x if x % 2 == 0 => x + 1`”, the pattern guard is “`if x % 2 == 0`”. A case with a pattern guard will only be selected if the pattern matches and the pattern guard yields true.
-* #### predicate
+* ### predicate
A _predicate_ is a function with a `Boolean` result type.
-* #### primary constructor
+* ### primary constructor
The main constructor of a class, which invokes a superclass constructor, if necessary, initializes fields to passed values, and executes any top-level code defined between the curly braces of the class. Fields are initialized only for value parameters not passed to the superclass constructor, except for any that are not used in the body of the class and can therefore be optimized away.
-* #### procedure
+* ### procedure
A _procedure_ is a function with result type of `Unit`, which is therefore executed solely for its side effects.
-* #### reassignable
+* ### reassignable
A variable may or may not be _reassignable_. A `var` is reassignable while a `val` is not.
-* #### recursive
+* ### recursive
A function is _recursive_ if it calls itself. If the only place the function calls itself is the last expression of the function, then the function is [tail recursive](#tail-recursive).
-* #### reference
+* ### reference
A _reference_ is the Java abstraction of a pointer, which uniquely identifies an object that resides on the JVM’s heap. Reference type variables hold references to objects, because reference types (instances of `AnyRef`) are implemented as Java objects that reside on the JVM’s heap. Value type variables, by contrast, may sometimes hold a reference (to a boxed wrapper type) and sometimes not (when the object is being represented as a primitive value). Speaking generally, a Scala variable [refers](#refers) to an object. The term “refers” is more abstract than “holds a reference.” If a variable of type `scala.Int` is currently represented as a primitive Java `int` value, then that variable still refers to the `Int` object, but no reference is involved.
-* #### reference equality
+* ### reference equality
_Reference equality_ means that two references identify the very same Java object. Reference equality can be determined, for reference types only, by calling `eq` in `AnyRef`. (In Java programs, reference equality can be determined using `==` on Java [reference types](#reference-type).)
-* #### reference type
+* ### reference type
A _reference type_ is a subclass of `AnyRef`. Instances of reference types always reside on the JVM’s heap at run time.
-* #### referential transparency
+* ### referential transparency
A property of functions that are independent of temporal context and have no side effects. For a particular input, an invocation of a referentially transparent function can be replaced by its result without changing the program semantics.
-* #### refers
+* ### refers
A variable in a running Scala program always _refers_ to some object. Even if that variable is assigned to `null`, it conceptually refers to the `Null` object. At runtime, an object may be implemented by a Java object or a value of a primitive type, but Scala allows programmers to think at a higher level of abstraction about their code as they imagine it running. See also [reference](#reference).
-* #### refinement type
+* ### refinement type
A type formed by supplying a base type with a number of members inside curly braces. The members in the curly braces refine the types that are present in the base type. For example, the type of “animal that eats grass” is `Animal { type SuitableFood = Grass }`.
-* #### result
+* ### result
An expression in a Scala program yields a _result_. The result of every expression in Scala is an object.
-* #### result type
+* ### result type
A method’s _result type_ is the type of the value that results from calling the method. (In Java, this concept is called the return type.)
-* #### return
+* ### return
A function in a Scala program _returns_ a value. You can call this value the [result](#result) of the function. You can also say the function _results in_ the value. The result of every function in Scala is an object.
-* #### runtime
+* ### runtime
The Java Virtual Machine, or [JVM](#jvm), that hosts a running Scala program. Runtime encompasses both the virtual machine, as defined by the Java Virtual Machine Specification, and the runtime libraries of the Java API and the standard Scala API. The phrase at run time (with a space between run and time) means when the program is running, and contrasts with compile time.
-* #### runtime type
+* ### runtime type
The type of an object at run time. To contrast, a [static type](#static-type) is the type of an expression at compile time. Most runtime types are simply bare classes with no type parameters. For example, the runtime type of `"Hi"` is `String`, and the runtime type of `(x: Int) => x + 1` is `Function1`. Runtime types can be tested with `isInstanceOf`.
-* #### script
+* ### script
A file containing top level definitions and statements, which can be run directly with `scala` without explicitly compiling. A script must end in an expression, not a definition.
-* #### selector
+* ### selector
The value being matched on in a `match` expression. For example, in “`s match { case _ => }`”, the selector is `s`.
-* #### self type
+* ### self type
A _self type_ of a trait is the assumed type of `this`, the receiver, to be used within the trait. Any concrete class that mixes in the trait must ensure that its type conforms to the trait’s self type. The most common use of self types is for dividing a large class into several traits (as described in Chapter 29 of [Programming in Scala](https://www.artima.com/shop/programming_in_scala)).
-* #### semi-structured data
+* ### semi-structured data
XML data is semi-structured. It is more structured than a flat binary file or text file, but it does not have the full structure of a programming language’s data structures.
-* #### serialization
-You can _serialize_ an object into a byte stream which can then be saved to files or transmitted over the network. You can later _deserialize_ the byte stream, even on different computer, and obtain an object that is the same as the original serialized object.
+* ### serialization
+You can _serialize_ an object into a byte stream which can then be saved to a file or transmitted over the network. You can later _deserialize_ the byte stream, even on different computer, and obtain an object that is the same as the original serialized object.
-* #### shadow
+* ### shadow
A new declaration of a local variable _shadows_ one of the same name in an enclosing scope.
-* #### signature
+* ### signature
_Signature_ is short for [type signature](#type-signature).
-* #### singleton object
+* ### singleton object
An object defined with the object keyword. Each singleton object has one and only one instance. A singleton object that shares its name with a class, and is defined in the same source file as that class, is that class’s [companion object](#companion-object). The class is its [companion class](#companion-class). A singleton object that doesn’t have a companion class is a [standalone object](#standalone-object).
-* #### standalone object
+* ### standalone object
A [singleton object](#singleton-object) that has no [companion class](#companion-class).
-* #### statement
+* ### statement
An expression, definition, or import, _i.e._, things that can go into a template or a block in Scala source code.
-* #### static type
+* ### static type
See [type](#type).
-* #### structural type
+* ### structural type
A [refinement type](#refinement-type) where the refinements are for members not in the base type. For example, `{ def close(): Unit }` is a structural type, because the base type is `AnyRef`, and `AnyRef` does not have a member named `close`.
-* #### subclass
+* ### subclass
A class is a _subclass_ of all of its [superclasses](#superclass) and [supertraits](#supertrait).
-* #### subtrait
+* ### subtrait
A trait is a _subtrait_ of all of its [supertraits](#supertrait).
-* #### subtype
+* ### subtype
The Scala compiler will allow any of a type’s _subtypes_ to be used as a substitute wherever that type is required. For classes and traits that take no type parameters, the subtype relationship mirrors the subclass relationship. For example, if class `Cat` is a subclass of abstract class `Animal`, and neither takes type parameters, type `Cat` is a subtype of type `Animal`. Likewise, if trait `Apple` is a subtrait of trait `Fruit`, and neither takes type parameters, type `Apple` is a subtype of type `Fruit`. For classes and traits that take type parameters, however, variance comes into play. For example, because abstract class `List` is declared to be covariant in its lone type parameter (i.e., `List` is declared `List[+A]`), `List[Cat]` is a subtype of `List[Animal]`, and `List[Apple]` a subtype of `List[Fruit]`. These subtype relationships exist even though the class of each of these types is `List`. By contrast, because `Set` is not declared to be covariant in its type parameter (i.e., `Set` is declared `Set[A]` with no plus sign), `Set[Cat]` is not a subtype of `Set[Animal]`. A subtype should correctly implement the contracts of its supertypes, so that the Liskov Substitution Principle applies, but the compiler only verifies this property at the level of type checking.
-* #### superclass
+* ### superclass
A class’s _superclasses_ include its direct superclass, its direct superclass’s direct superclass, and so on, all the way up to `Any`.
-* #### supertrait
+* ### supertrait
A class’s or trait’s _supertraits_, if any, include all traits directly mixed into the class or trait or any of its superclasses, plus any supertraits of those traits.
-* #### supertype
+* ### supertype
A type is a _supertype_ of all of its subtypes.
-* #### synthetic class
+* ### synthetic class
A synthetic class is generated automatically by the compiler rather than being written by hand by the programmer.
-* #### tail recursive
+* ### tail recursive
A function is _tail recursive_ if the only place the function calls itself is the last operation of the function.
-* #### target typing
+* ### target typing
_Target typing_ is a form of type inference that takes into account the type that’s expected. In `nums.filter((x) => x > 0)`, for example, the Scala compiler infers type of `x` to be the element type of `nums`, because the `filter` method invokes the function on each element of `nums`.
-* #### template
+* ### template
A _template_ is the body of a class, trait, or singleton object definition. It defines the type signature, behavior and initial state of the class, trait, or object.
-* #### trait
+* ### trait
A _trait_, which is defined with the `trait` keyword, is like an abstract class that cannot take any value parameters and can be “mixed into” classes or other traits via the process known as [mixin composition](#mixin-composition). When a trait is being mixed into a class or trait, it is called a [mixin](#mixin). A trait may be parameterized with one or more types. When parameterized with types, the trait constructs a type. For example, `Set` is a trait that takes a single type parameter, whereas `Set[Int]` is a type. Also, `Set` is said to be “the trait of” type `Set[Int]`.
-* #### type
+* ### type
Every variable and expression in a Scala program has a _type_ that is known at compile time. A type restricts the possible values to which a variable can refer, or an expression can produce, at run time. A variable or expression’s type can also be referred to as a _static type_ if necessary to differentiate it from an object’s [runtime type](#runtime-type). In other words, “type” by itself means static type. Type is distinct from class because a class that takes type parameters can construct many types. For example, `List` is a class, but not a type. `List[T]` is a type with a free type parameter. `List[Int]` and `List[String]` are also types (called ground types because they have no free type parameters). A type can have a “[class](#class)” or “[trait](#trait).” For example, the class of type `List[Int]` is `List`. The trait of type `Set[String]` is `Set`.
-* #### type constraint
+* ### type constraint
Some [annotations](#annotation) are _type constraints_, meaning that they add additional limits, or constraints, on what values the type includes. For example, `@positive` could be a type constraint on the type `Int`, limiting the type of 32-bit integers down to those that are positive. Type constraints are not checked by the standard Scala compiler, but must instead be checked by an extra tool or by a compiler plugin.
-* #### type constructor
+* ### type constructor
A class or trait that takes type parameters.
-* #### type parameter
+* ### type parameter
A parameter to a generic class or generic method that must be filled in by a type. For example, class `List` is defined as “`class List[T] { . . . `”, and method `identity`, a member of object `Predef`, is defined as “`def identity[T](x:T) = x`”. The `T` in both cases is a type parameter.
-* #### type signature
+* ### type signature
A method’s _type signature_ comprises its name, the number, order, and types of its parameters, if any, and its result type. The type signature of a class, trait, or singleton object comprises its name, the type signatures of all of its members and constructors, and its declared inheritance and mixin relations.
-* #### uniform access principle
+* ### uniform access principle
The _uniform access principle_ states that variables and parameterless functions should be accessed using the same syntax. Scala supports this principle by not allowing parentheses to be placed at call sites of parameterless functions. As a result, a parameterless function definition can be changed to a `val`, or _vice versa_, without affecting client code.
-* #### unreachable
+* ### unreachable
At the Scala level, objects can become _unreachable_, at which point the memory they occupy may be reclaimed by the runtime. Unreachable does not necessarily mean unreferenced. Reference types (instances of `AnyRef`) are implemented as objects that reside on the JVM’s heap. When an instance of a reference type becomes unreachable, it indeed becomes unreferenced, and is available for garbage collection. Value types (instances of `AnyVal`) are implemented as both primitive type values and as instances of Java wrapper types (such as `java.lang.Integer`), which reside on the heap. Value type instances can be boxed (converted from a primitive value to a wrapper object) and unboxed (converted from a wrapper object to a primitive value) throughout the lifetime of the variables that refer to them. If a value type instance currently represented as a wrapper object on the JVM’s heap becomes unreachable, it indeed becomes unreferenced, and is available for garbage collection. But if a value type currently represented as a primitive value becomes unreachable, then it does not become unreferenced, because it does not exist as an object on the JVM’s heap at that point of time. The runtime may reclaim memory occupied by unreachable objects, but if an Int, for example, is implemented at run time by a primitive Java int that occupies some memory in the stack frame of an executing method, then the memory for that object is “reclaimed” when the stack frame is popped as the method completes. Memory for reference types, such as `Strings`, may be reclaimed by the JVM’s garbage collector after they become unreachable.
-* #### unreferenced
+* ### unreferenced
See [unreachable](#unreachable).
-* #### value
+* ### value
The result of any computation or expression in Scala is a _value_, and in Scala, every value is an object. The term value essentially means the image of an object in memory (on the JVM’s heap or stack).
-* #### value type
+* ### value type
A _value type_ is any subclass of `AnyVal`, such as `Int`, `Double`, or `Unit`. This term has meaning at the level of Scala source code. At runtime, instances of value types that correspond to Java primitive types may be implemented in terms of primitive type values or instances of wrapper types, such as `java.lang.Integer`. Over the lifetime of a value type instance, the runtime may transform it back and forth between primitive and wrapper types (_i.e._, to box and unbox it).
-* #### variable
+* ### variable
A named entity that refers to an object. A variable is either a `val` or a `var`. Both `val`s and `var`s must be initialized when defined, but only `var`s can be later reassigned to refer to a different object.
-* #### variance
+* ### variance
A type parameter of a class or trait can be marked with a _variance_ annotation, either [covariant](#covariant) (+) or [contravariant](#contravariant) (-). Such variance annotations indicate how subtyping works for a generic class or trait. For example, the generic class `List` is covariant in its type parameter, and thus `List[String]` is a subtype of `List[Any]`. By default, _i.e._, absent a `+` or `-` annotation, type parameters are [nonvariant](#nonvariant).
-* #### yield
+* ### yield
An expression can _yield_ a result. The `yield` keyword designates the result of a [for comprehension](#for-comprehension).
diff --git a/_includes/_markdown/_ru/install-cask.md b/_includes/_markdown/_ru/install-cask.md
new file mode 100644
index 0000000000..1cac104c20
--- /dev/null
+++ b/_includes/_markdown/_ru/install-cask.md
@@ -0,0 +1,45 @@
+{% altDetails require-info-box 'Установка Cask' %}
+
+{% tabs cask-install class=tabs-build-tool %}
+
+{% tab 'Scala CLI' %}
+
+Вы можете объявить зависимость от Cask с помощью следующей директивы `using`:
+
+```scala
+//> using dep com.lihaoyi::cask::0.10.2
+```
+
+{% endtab %}
+
+{% tab 'sbt' %}
+
+В файле `build.sbt` вы можете добавить зависимость от Cask:
+
+```scala
+lazy val example = project.in(file("example"))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "com.lihaoyi" %% "cask" % "0.10.2",
+ fork := true
+ )
+```
+
+{% endtab %}
+
+{% tab 'Mill' %}
+
+В файле `build.sc` вы можете добавить зависимость от Cask:
+
+```scala
+object example extends RootModule with ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps = Agg(
+ ivy"com.lihaoyi::cask::0.10.2"
+ )
+}
+```
+{% endtab %}
+
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/_markdown/_ru/install-munit.md b/_includes/_markdown/_ru/install-munit.md
new file mode 100644
index 0000000000..aa15142558
--- /dev/null
+++ b/_includes/_markdown/_ru/install-munit.md
@@ -0,0 +1,68 @@
+{% altDetails install-info-box 'Установка MUnit' %}
+
+{% tabs munit-unit-test-1 class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+
+Вы можете запросить весь набор инструментов одной командой:
+
+```scala
+//> using toolkit latest
+```
+
+MUnit, будучи тестовым фреймворком, доступен только в тестовых файлах:
+файлах в каталоге `test` или тех, которые имеют расширение `.test.scala`.
+Подробнее о тестовой области (test scope) см. [в документации Scala CLI](https://scala-cli.virtuslab.org/docs/commands/test/).
+
+В качестве альтернативы вы можете запросить только определенную версию MUnit:
+
+```scala
+//> using dep org.scalameta::munit:1.1.0
+```
+
+{% endtab %}
+
+{% tab 'sbt' %}
+
+В файле `build.sbt` вы можете добавить зависимость от toolkit-test:
+
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit-test" % "0.7.0" % Test
+ )
+```
+
+Здесь конфигурация `Test` означает, что зависимость используется только исходными файлами в `src/test`.
+
+В качестве альтернативы вы можете запросить только определенную версию MUnit:
+
+```scala
+libraryDependencies += "org.scalameta" %% "munit" % "1.1.0" % Test
+```
+{% endtab %}
+
+{% tab 'Mill' %}
+
+В файле `build.sc` вы можете добавить объект `test`, расширяющий `Tests` и `TestModule.Munit`:
+
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ object test extends Tests with TestModule.Munit {
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit-test:0.7.0"
+ )
+ }
+}
+```
+
+В качестве альтернативы вы можете запросить только определенную версию MUnit:
+
+```scala
+ivy"org.scalameta::munit:1.1.0"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}
\ No newline at end of file
diff --git a/_includes/_markdown/_ru/install-os-lib.md b/_includes/_markdown/_ru/install-os-lib.md
new file mode 100644
index 0000000000..f010d1f7fd
--- /dev/null
+++ b/_includes/_markdown/_ru/install-os-lib.md
@@ -0,0 +1,64 @@
+{% altDetails require-info-box 'Установка OS-Lib' %}
+
+{% tabs oslib-install class=tabs-build-tool %}
+
+{% tab 'Scala CLI' %}
+
+Вы можете запросить весь набор инструментов одной командой:
+
+```scala
+//> using toolkit latest
+```
+
+В качестве альтернативы вы можете запросить только определенную версию OS-Lib:
+
+```scala
+//> using dep com.lihaoyi::os-lib:0.11.3
+```
+
+{% endtab %}
+
+{% tab 'sbt' %}
+
+В файле `build.sbt` вы можете добавить зависимость от `toolkit`:
+
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0"
+ )
+```
+
+В качестве альтернативы вы можете запросить только определенную версию OS-Lib:
+
+```scala
+libraryDependencies += "com.lihaoyi" %% "os-lib" % "0.11.3"
+```
+
+{% endtab %}
+
+{% tab 'Mill' %}
+
+В файле `build.sc` вы можете добавить зависимость от `toolkit`:
+
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit:0.7.0"
+ )
+}
+```
+
+В качестве альтернативы вы можете запросить только определенную версию OS-Lib:
+
+```scala
+ivy"com.lihaoyi::os-lib:0.11.3"
+```
+
+{% endtab %}
+
+{% endtabs %}
+{% endaltDetails %}
\ No newline at end of file
diff --git a/_includes/_markdown/_ru/install-sttp.md b/_includes/_markdown/_ru/install-sttp.md
new file mode 100644
index 0000000000..fec7938cea
--- /dev/null
+++ b/_includes/_markdown/_ru/install-sttp.md
@@ -0,0 +1,64 @@
+
+{% altDetails install-info-box 'Установка sttp' %}
+
+{% tabs sttp-install-methods class=tabs-build-tool%}
+
+{% tab 'Scala CLI' %}
+
+Вы можете запросить весь набор инструментов одной командой:
+
+```scala
+//> using toolkit latest
+```
+
+В качестве альтернативы вы можете запросить только определенную версию sttp:
+
+```scala
+//> using dep com.softwaremill.sttp.client4::core:4.0.0-RC1
+```
+
+{% endtab %}
+
+{% tab 'sbt' %}
+
+В файле `build.sbt` вы можете добавить зависимость от `toolkit`:
+
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0"
+ )
+```
+
+В качестве альтернативы вы можете запросить только определенную версию sttp:
+
+```scala
+libraryDependencies += "com.softwaremill.sttp.client4" %% "core" % "4.0.0-RC1"
+```
+
+{% endtab %}
+
+{% tab 'Mill' %}
+
+В файле `build.sc` вы можете добавить зависимость от `toolkit`:
+
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit:0.7.0"
+ )
+}
+```
+
+В качестве альтернативы вы можете запросить только определенную версию sttp:
+
+```scala
+ivy"com.softwaremill.sttp.client4::core:4.0.0-RC1"
+```
+
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/_markdown/_ru/install-upickle.md b/_includes/_markdown/_ru/install-upickle.md
new file mode 100644
index 0000000000..83880a91a8
--- /dev/null
+++ b/_includes/_markdown/_ru/install-upickle.md
@@ -0,0 +1,64 @@
+
+{% altDetails install-info-box 'Установка upickle' %}
+
+{% tabs upickle-install-methods class=tabs-build-tool %}
+
+{% tab 'Scala CLI' %}
+
+Вы можете запросить весь набор инструментов одной командой:
+
+```scala
+//> using toolkit latest
+```
+
+В качестве альтернативы вы можете запросить только определенную версию UPickle:
+
+```scala
+//> using dep com.lihaoyi::upickle:4.1.0
+```
+
+{% endtab %}
+
+{% tab 'sbt' %}
+
+В файле `build.sbt` вы можете добавить зависимость от `toolkit`:
+
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0"
+ )
+```
+
+В качестве альтернативы вы можете запросить только определенную версию UPickle:
+
+```scala
+libraryDependencies += "com.lihaoyi" %% "upickle" % "4.1.0"
+```
+
+{% endtab %}
+
+{% tab 'Mill' %}
+
+В файле `build.sc` вы можете добавить зависимость от `toolkit`:
+
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit:0.7.0"
+ )
+}
+```
+
+В качестве альтернативы вы можете запросить только определенную версию UPickle:
+
+```scala
+ivy"com.lihaoyi::upickle:4.1.0"
+```
+
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/_markdown/courses-coursera.md b/_includes/_markdown/courses-coursera.md
new file mode 100644
index 0000000000..403c5e3100
--- /dev/null
+++ b/_includes/_markdown/courses-coursera.md
@@ -0,0 +1,18 @@
+## Scala Courses on Coursera by EPFL
+
+The [Scala Center](https://scala.epfl.ch) at EPFL offers free online courses of various levels, from beginner to advanced.
+
+For beginners:
+
+- [Effective Programming in Scala](https://www.coursera.org/learn/effective-scala): a practical introduction to Scala for professional developers
+- [Functional Programming Principles in Scala](https://www.coursera.org/learn/scala-functional-programming): the foundational course by Martin Odersky, Scala's creator
+
+More advanced topics:
+
+- [Functional Program Design in Scala](https://www.coursera.org/learn/scala-functional-program-design): builds on functional principles with more advanced concepts
+- [Parallel Programming](https://www.coursera.org/learn/scala-parallel-programming)
+- [Big Data Analysis with Scala and Spark](https://www.coursera.org/learn/scala-spark-big-data)
+- [Programming Reactive Systems](https://www.coursera.org/learn/scala-akka-reactive): introduces Akka, actors and reactive streams
+
+All courses are free to audit, with an option to pay for a certificate, to showcase your skills on your resume or LinkedIn.
+For more on Scala Center's online courses, visit [this page](https://docs.scala-lang.org/online-courses.html#learning-platforms).
diff --git a/_includes/_markdown/courses-extension-school.md b/_includes/_markdown/courses-extension-school.md
new file mode 100644
index 0000000000..003c42a4f2
--- /dev/null
+++ b/_includes/_markdown/courses-extension-school.md
@@ -0,0 +1,9 @@
+## EPFL Extension School: Effective Programming in Scala
+
+Subscribing to [Effective programming in Scala](https://www.epfl.ch/education/continuing-education/effective-programming-in-scala/) on the EPFL Extension School offers:
+
+- Regular Q&A sessions and code reviews with experts from the Scala team
+- An [Extension School certificate](https://www.epfl.ch/education/continuing-education/certifications/) upon completion
+
+This course combines video lessons, written content and hands-on exercise focused on practical aspects, including business domain modeling, error handling, data manipulation, and task parallelization.
+For more on Scala Center's online courses, visit [this page](https://docs.scala-lang.org/online-courses.html#learning-platforms).
diff --git a/_includes/_markdown/courses-rock-the-jvm.md b/_includes/_markdown/courses-rock-the-jvm.md
new file mode 100644
index 0000000000..0b0db4f9f1
--- /dev/null
+++ b/_includes/_markdown/courses-rock-the-jvm.md
@@ -0,0 +1,17 @@
+## Rock the JVM Courses
+
+_As part of a partnership with the Scala Center, Rock the JVM donates 30% of the revenue from any courses purchased through the links in this section to support the Scala Center._
+
+[Rock the JVM](https://rockthejvm.com?affcode=256201_r93i1xuv) is a learning platform with free and premium courses on the Scala language, and all major libraries and tools in the Scala ecosystem: Typelevel, Zio, Akka/Pekko, Spark, and others.
+Its main Scala courses are:
+
+- [Scala at Light Speed](https://rockthejvm.com/courses/scala-at-light-speed?affcode=256201_r93i1xuv) (free)
+- [Scala & Functional Programming Essentials](https://rockthejvm.com/courses/scala-essentials?affcode=256201_r93i1xuv) (premium)
+- [Advanced Scala and Functional Programming](https://rockthejvm.com/courses/advanced-scala?affcode=256201_r93i1xuv) (premium)
+- [Scala Macros & Metaprogramming](https://rockthejvm.com/courses/scala-macros-and-metaprogramming?affcode=256201_r93i1xuv) (premium)
+
+Other courses teach how to build full-stack Scala applications, using [Typelevel](https://rockthejvm.com/courses/typelevel-rite-of-passage?affcode=256201_r93i1xuv) or [ZIO](https://rockthejvm.com/courses/zio-rite-of-passage?affcode=256201_r93i1xuv) ecosystems.
+
+
+
+Explore more premium [courses](https://rockthejvm.com/courses?affcode=256201_r93i1xuv) or check out [free video tutorials](https://youtube.com/rockthejvm?affcode=256201_r93i1xuv) and [free articles](https://rockthejvm.com/articles?affcode=256201_r93i1xuv).
diff --git a/_includes/_markdown/install-cask.md b/_includes/_markdown/install-cask.md
new file mode 100644
index 0000000000..3637ddfac9
--- /dev/null
+++ b/_includes/_markdown/install-cask.md
@@ -0,0 +1,37 @@
+{% altDetails require-info-box 'Getting Cask' %}
+
+{% tabs cask-install class=tabs-build-tool %}
+
+{% tab 'Scala CLI' %}
+You can declare a dependency on Cask with the following `using` directive:
+```scala
+//> using dep com.lihaoyi::cask::0.10.2
+```
+{% endtab %}
+
+{% tab 'sbt' %}
+In your `build.sbt`, you can add a dependency on Cask:
+```scala
+lazy val example = project.in(file("example"))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "com.lihaoyi" %% "cask" % "0.10.2",
+ fork := true
+ )
+```
+{% endtab %}
+
+{% tab 'Mill' %}
+In your `build.sc`, you can add a dependency on Cask:
+```scala
+object example extends RootModule with ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps = Agg(
+ ivy"com.lihaoyi::cask::0.10.2"
+ )
+}
+```
+{% endtab %}
+
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/_markdown/install-munit.md b/_includes/_markdown/install-munit.md
new file mode 100644
index 0000000000..47eeb1509f
--- /dev/null
+++ b/_includes/_markdown/install-munit.md
@@ -0,0 +1,53 @@
+{% altDetails install-info-box 'Getting MUnit' %}
+
+{% tabs munit-unit-test-1 class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//> using toolkit latest
+```
+MUnit, being a testing framework, is only available in test files: files in a `test` directory or ones that have the `.test.scala` extension. Refer to the [Scala CLI documentation](https://scala-cli.virtuslab.org/docs/commands/test/) to learn more about the test scope.
+
+Alternatively, you can require just a specific version of MUnit:
+```scala
+//> using dep org.scalameta::munit:1.1.0
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency on toolkit-test:
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit-test" % "0.7.0" % Test
+ )
+```
+
+Here the `Test` configuration means that the dependency is only used by the source files in `src/test`.
+
+Alternatively, you can require just a specific version of MUnit:
+```scala
+libraryDependencies += "org.scalameta" %% "munit" % "1.1.0" % Test
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add a `test` object extending `Tests` and `TestModule.Munit`:
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ object test extends Tests with TestModule.Munit {
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit-test:0.7.0"
+ )
+ }
+}
+```
+
+Alternatively, you can require just a specific version of MUnit:
+```scala
+ivy"org.scalameta::munit:1.1.0"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/_markdown/install-os-lib.md b/_includes/_markdown/install-os-lib.md
new file mode 100644
index 0000000000..ae254d9d71
--- /dev/null
+++ b/_includes/_markdown/install-os-lib.md
@@ -0,0 +1,46 @@
+{% altDetails require-info-box 'Getting OS-Lib' %}
+
+{% tabs oslib-install class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//> using toolkit latest
+```
+
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+//> using dep com.lihaoyi::os-lib:0.11.3
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your `build.sbt`, you can add a dependency on the toolkit:
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0"
+ )
+```
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+libraryDependencies += "com.lihaoyi" %% "os-lib" % "0.11.3"
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your `build.sc` file, you can add a dependency on the Toolkit:
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit:0.7.0"
+ )
+}
+```
+Alternatively, you can require just a specific version of OS-Lib:
+```scala
+ivy"com.lihaoyi::os-lib:0.11.3"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/_markdown/install-sttp.md b/_includes/_markdown/install-sttp.md
new file mode 100644
index 0000000000..0173ec47e1
--- /dev/null
+++ b/_includes/_markdown/install-sttp.md
@@ -0,0 +1,47 @@
+{% altDetails install-info-box 'Getting sttp' %}
+
+{% tabs sttp-install-methods class=tabs-build-tool%}
+{% tab 'Scala CLI' %}
+You can require the entire toolkit in a single line:
+```scala
+//> using toolkit latest
+```
+
+Alternatively, you can require just a specific version of sttp:
+```scala
+//> using dep com.softwaremill.sttp.client4::core:4.0.0-RC1
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add a dependency on the Toolkit:
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0"
+ )
+```
+
+Alternatively, you can require just a specific version of sttp:
+```scala
+libraryDependencies += "com.softwaremill.sttp.client4" %% "core" % "4.0.0-RC1"
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add a dependency on the Toolkit:
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit:0.7.0"
+ )
+}
+```
+Alternatively, you can require just a specific version of sttp:
+```scala
+ivy"com.softwaremill.sttp.client4::core:4.0.0-RC1"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/_markdown/install-upickle.md b/_includes/_markdown/install-upickle.md
new file mode 100644
index 0000000000..9f9cff8a62
--- /dev/null
+++ b/_includes/_markdown/install-upickle.md
@@ -0,0 +1,46 @@
+{% altDetails install-info-box 'Getting upickle' %}
+
+{% tabs upickle-install-methods class=tabs-build-tool %}
+{% tab 'Scala CLI' %}
+Using Scala CLI, you can require the entire toolkit in a single line:
+```scala
+//> using toolkit latest
+```
+
+Alternatively, you can require just a specific version of UPickle:
+```scala
+//> using dep com.lihaoyi::upickle:4.1.0
+```
+{% endtab %}
+{% tab 'sbt' %}
+In your build.sbt file, you can add the dependency on the Toolkit:
+```scala
+lazy val example = project.in(file("."))
+ .settings(
+ scalaVersion := "3.4.2",
+ libraryDependencies += "org.scala-lang" %% "toolkit" % "0.7.0"
+ )
+```
+Alternatively, you can require just a specific version of UPickle:
+```scala
+libraryDependencies += "com.lihaoyi" %% "upickle" % "4.1.0"
+```
+{% endtab %}
+{% tab 'Mill' %}
+In your build.sc file, you can add the dependency to the upickle library:
+```scala
+object example extends ScalaModule {
+ def scalaVersion = "3.4.2"
+ def ivyDeps =
+ Agg(
+ ivy"org.scala-lang::toolkit:0.7.0"
+ )
+}
+```
+Alternatively, you can require just a specific version of UPickle:
+```scala
+ivy"com.lihaoyi::upickle:4.1.0"
+```
+{% endtab %}
+{% endtabs %}
+{% endaltDetails %}
diff --git a/_includes/alert-banner.html b/_includes/alert-banner.html
new file mode 100644
index 0000000000..94c5ac1273
--- /dev/null
+++ b/_includes/alert-banner.html
@@ -0,0 +1,10 @@
+{% comment %}use the variable 'message' to include markdown text to display in the alert.{% endcomment %}
+
+{% unless include.message_id == 'disabled' %}
+
+
+{{include.message|markdownify}}
+ +
+
+
+
+
+
diff --git a/_includes/code-snippet.html b/_includes/code-snippet.html
new file mode 100644
index 0000000000..3af87d0f97
--- /dev/null
+++ b/_includes/code-snippet.html
@@ -0,0 +1,8 @@
+
+ {% for item in include.images %}
+
+ {% endfor %}
+ {% for item in include.images %}
+ {% if forloop.index == forloop.length %}
+ {% assign nextindex = 0 %}
+ {% else %}
+ {% assign nextindex = forloop.index0 | plus: 1 %}
+ {% endif %}
+ {% assign nextletter = letters[nextindex] %}
+ {% if forloop.index0 == 0 %}
+ {% assign previndex = forloop.length | minus: 1 %}
+ {% else %}
+ {% assign previndex = forloop.index0 | minus: 1 %}
+ {% endif %}
+ {% assign prevletter = letters[previndex] %}
+
+
+
+
+
+ {% endfor %}
+
+
+ -
+ {% for item in include.images %}
+
+ {% endfor %}
+
+ {% for item in include.images %}
+
+ {% endfor %}
+
+
+ {% unless include.nocopy %}
+
+ {% endunless %}
+
diff --git a/_includes/column-list-of-items.html b/_includes/column-list-of-items.html
deleted file mode 100644
index eb9e1600be..0000000000
--- a/_includes/column-list-of-items.html
+++ /dev/null
@@ -1,18 +0,0 @@
-{% comment %}
- Layouts using this include should pass an include variable called 'collection' referencing a collection carrying the data (i.e.: contribute_community_tickets, contribute_resources...)
-{% endcomment %}
-{{include.codeSnippet}}
- {% for item in include.collection %}
-
\ No newline at end of file
diff --git a/_includes/documentation-sections.html b/_includes/documentation-sections.html
index 4ca75f459d..cac3c2d21b 100644
--- a/_includes/documentation-sections.html
+++ b/_includes/documentation-sections.html
@@ -3,7 +3,7 @@
-
- {% endfor %}
-
-
-
-
- {{item.title}}
- -
- {{item.content}}
-
- {{ section.title }}
{% for link in section.links %} - +{{link.title}}
@@ -14,15 +14,5 @@{{link.title}}
{% endfor %}
- {% if section.more-resources %}
- {{ page.more-resources-label }}:
-
{% endfor %}
-
- {% for resource in section.more-resources %}
-
- {{ resource.title }} - {% endfor %} -
Hello world!
` from +the `index.html` file. +{% endraw %} + +Layouts must be placed in a `_layouts` directory in the site root: + +``` +├── _layouts +│ └── main.html +└── _docs + ├── getting-started.md + └── index.html +``` + +## Assets + +In order to render assets along with static site, they need to be placed in the `_assets` directory in the site root: + +``` +├── _assets +│ └── images +│ └── myimage.png +└── _docs + └── getting-started.md +``` + +To reference the asset on a page, one needs to create a link relative to the `_assets` directory + +``` +Take a look at the following image: [My image](images/myimage.png) +``` + +## Sidebar + +By default, Scaladoc reflects the directory structure from `_docs` directory in the rendered site. There is also the ability to override it by providing a `sidebar.yml` file in the site root directory. The YAML configuration file describes the structure of the rendered static site and the table of content: + +```yaml +index: index.html +subsection: + - title: Usage + index: usage/index.html + directory: usage + subsection: + - title: Dottydoc + page: usage/dottydoc.html + hidden: false + - title: sbt-projects + page: usage/sbt-projects.html + hidden: false +``` + +The root element needs to be a `subsection`. +Nesting subsections will result in a tree-like structure of navigation. + +`subsection` properties are: + +- `title` - Optional string - A default title of the subsection. + Front-matter titles have higher priorities. +- `index` - Optional string - A path to index page of a subsection. The path is relative to the `_docs` directory. +- `directory` - Optional string - A name of the directory that will contain the subsection in the generated site. + By default, the directory name is the subsection name converted to kebab case. +- `subsection` - Array of `subsection` or `page`. + + Either `index` or `subsection` must be defined. The subsection defined with `index` and without `subsection` will contain pages and directories loaded recursively from the directory of the index page. + +`page` properties are: + +- `title` - Optional string - A default title of the page. + Front-matter titles have higher priorities. +- `page` - String - A path to the page, relative to the `_docs` directory. +- `hidden` - Optional boolean - A flag that indicates whether the page should be visible in the navigation sidebar. By default, it is set to `false`. + +**Note**: All the paths in the YAML configuration file are relative to `Hello world
+ + +``` + +Place it in the `resources` directory. + +{% tabs web-server-static-1 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +``` +example +├── Example.scala +└── resources + └── hello.html +``` +{% endtab %} +{% tab 'sbt' %} +``` +example +└──src + └── main + ├── resources + │ └── hello.html + └── scala + └── Example.scala +``` +{% endtab %} +{% tab 'Mill' %} +``` +example +├── src +│ └── Example.scala +└── resources + └── hello.html +``` +{% endtab %} +{% endtabs %} + +The `@cask.staticFiles` annotation specifies at which path the webpage will be available. The endpoint function returns +the location of the file. + +{% tabs web-server-static-2 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object Example extends cask.MainRoutes { + @cask.staticFiles("/static") + def staticEndpoint(): String = "src/main/resources" // or "resources" if not using SBT + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object Example extends cask.MainRoutes: + @cask.staticFiles("/static") + def staticEndpoint(): String = "src/main/resources" // or "resources" if not using SBT + + initialize() +``` +{% endtab %} +{% endtabs %} + +In the example above, `@cask.staticFiles` instructs the server to look for files accessed at the `/static` path in the +`src/main/resources` directory. Cask will match any subpath coming after `/static` and append it to the directory path. +If you access the `/static/hello.html` file, it will serve the file available at `src/main/resources/hello.html`. +The directory path can be any path available to the server, relative or not. If the requested file cannot be found in the +specified location, the server will return a 404 response with an error message. + +The `Example` object inherits from the `cask.MainRoutes` class. It provides the main function that starts the server. The `initialize()` +method call initializes the server routes, i.e., the association between URL paths and the code that handles them. + +### Using the resources directory + +The `@cask.staticResources` annotation works in the same way as the `@cask.staticFiles` used above, with the difference that +the path returned by the endpoint method describes the location of files _inside_ the resources directory. Since the +previous example conveniently used the resources directory, it can be simplified with `@cask.staticResources`. + +{% tabs web-server-static-3 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object Example extends cask.MainRoutes { + @cask.staticResources("/static") + def staticEndpoint(): String = "." + + initialize() +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object Example extends cask.MainRoutes: + @cask.staticResources("/static") + def staticEndpoint(): String = "." + + initialize() +``` +{% endtab %} +{% endtabs %} + +In the endpoint method, the location is set to `"."`, telling the server that the files are available directly in the +resources directory. In general, you can use any nested location within the resources directory. For instance, you could opt +for placing your HTML files in the `static` directory inside the resources directory or using different directories to sort out +files used by different endpoints. + +## Running the example + +Run the example with the build tool of your choice. + +{% tabs munit-unit-test-4 class=tabs-build-tool %} +{% tab 'Scala CLI' %} +In the terminal, the following command will start the server: +``` +scala run Example.scala +``` +{% endtab %} +{% tab 'sbt' %} +In the terminal, the following command will start the server: +``` +sbt example/run +``` +{% endtab %} +{% tab 'Mill' %} +In the terminal, the following command will start the server: +``` +./mill run +``` +{% endtab %} +{% endtabs %} + +The example page will be available at [http://localhost:8080/static/hello.html](http://localhost:8080/static/hello.html). diff --git a/_overviews/toolkit/web-server-websockets.md b/_overviews/toolkit/web-server-websockets.md new file mode 100644 index 0000000000..653bd7f154 --- /dev/null +++ b/_overviews/toolkit/web-server-websockets.md @@ -0,0 +1,118 @@ +--- +title: How to use websockets? +type: section +description: Using websockets with Cask +num: 35 +previous-page: web-server-input +next-page: web-server-cookies-and-decorators +--- + +{% include markdown.html path="_markdown/install-cask.md" %} + +You can create a WebSocket endpoint with the `@cask.websocket` annotation. The endpoint method should return a +`cask.WsHandler` instance defining how the communication should take place. It can also return a `cask.Response`, which rejects the +attempt at forming a WebSocket connection. + +The connection can also be closed by sending a `cask.Ws.close()` message through the WebSocket channel. + +Create an HTML file named `websockets.html` with the following content and place it in the `resources ` directory. + +```html + + + +
+
+
+
+
+
+
+
+```
+
+The JavaScript code opens a WebSocket connection using the `ws://localhost:8080/websocket` endpoint. The `ws.onmessage`
+event handler is executed when the server pushes a message to the browser and `ws.onclose` when the connection is closed.
+
+Create an endpoint for serving static files using the `@cask.staticResources` annotation and an endpoint for handling
+the WebSocket connection.
+
+{% tabs web-server-websocket-1 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+@cask.staticResources("/static")
+def static() = "."
+
+private def getZoneIdForCity(city: String): Option[ZoneId] = {
+ import scala.jdk.CollectionConverters._
+ ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of)
+}
+
+@cask.websocket("/websocket")
+def websocket(): cask.WsHandler = {
+ cask.WsHandler { channel =>
+ cask.WsActor {
+ case cask.Ws.Text("") => channel.send(cask.Ws.Close())
+ case cask.Ws.Text(city) =>
+ val text = getZoneIdForCity(city) match {
+ case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}"
+ case None => s"Couldn't find time zone for city $city"
+ }
+ channel.send(cask.Ws.Text(text))
+ }
+ }
+}
+
+initialize()
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+@cask.staticResources("/static")
+def static() = "."
+
+private def getZoneIdForCity(city: String): Option[ZoneId] =
+ import scala.jdk.CollectionConverters.*
+ ZoneId.getAvailableZoneIds.asScala.find(_.endsWith("/" + city)).map(ZoneId.of)
+
+@cask.websocket("/websocket")
+def websocket(): cask.WsHandler =
+ cask.WsHandler { channel =>
+ cask.WsActor {
+ case cask.Ws.Text("") => channel.send(cask.Ws.Close())
+ case cask.Ws.Text(city) =>
+ val text = getZoneIdForCity(city) match
+ case Some(zoneId) => s"Current date is: ${ZonedDateTime.now().withZoneSameInstant(zoneId)}"
+ case None => s"Couldn't find time zone for city $city"
+ channel.send(cask.Ws.Text(text))
+ }
+ }
+
+initialize()
+```
+{% endtab %}
+{% endtabs %}
+
+In the `cask.WsHandler` we define a `cask.WsActor`. It reacts to events (of type `cask.util.Ws.Event`) and uses the
+WebSocket channel to send messages. In this example, we receive the name of a city and return the current time there. If the server
+receives an empty message, the connection is closed.
\ No newline at end of file
diff --git a/_overviews/tutorials/binary-compatibility-for-library-authors.md b/_overviews/tutorials/binary-compatibility-for-library-authors.md
index 92b993ca24..c3fd5467a9 100644
--- a/_overviews/tutorials/binary-compatibility-for-library-authors.md
+++ b/_overviews/tutorials/binary-compatibility-for-library-authors.md
@@ -52,7 +52,7 @@ Similarly to the JVM, Scala.js and Scala Native have their respective equivalent
However, contrary to the JVM, Scala.js and Scala Native link their respective IR files at link time, so eagerly, instead of lazily at run-time. Failure to correctly link the entire program results in linking errors reported while trying to invoke `fastOptJS`/`fullOptJS` or `nativeLink`.
-Besides that difference in the timing of linkage errors, the models are extremely similar. **Unless otherwise noted, the contents of this guide apply equally to the JVM, Scala.js and Scala Native.**
+Besides, that difference in the timing of linkage errors, the models are extremely similar. **Unless otherwise noted, the contents of this guide apply equally to the JVM, Scala.js and Scala Native.**
Before we look at how to avoid binary incompatibility errors, let us first
establish some key terminologies we will be using for the rest of the guide.
@@ -67,7 +67,7 @@ Because of this, having multiple versions of the same library in the classpath i
* Unexpected runtime behavior if the order of class files changes
Therefore, build tools like sbt and Gradle will pick one version and **evict** the rest when resolving JARs to use for compilation and packaging.
-By default they pick the latest version of each library, but it is possible to specify another version if required.
+By default, they pick the latest version of each library, but it is possible to specify another version if required.
### Source Compatibility
Two library versions are **Source Compatible** with each other if switching one for the other does not incur any compile errors or unintended behavioral changes (semantic errors).
@@ -115,7 +115,7 @@ Our application `App` depends on library `A` and `B`. Both `A` and `B` depends o
{: style="width: 50%; margin: auto; display: block;"}
-Sometime later, we see `B v1.1.0` is available and upgrade its version in our build. Our code compiles and seems to work so we push it to production and go home for dinner.
+Sometime later, we see `B v1.1.0` is available and upgrade its version in our build. Our code compiles and seems to work, so we push it to production and go home for dinner.
Unfortunately at 2am, we get frantic calls from customers saying that our application is broken! Looking at the logs, you find lots of `NoSuchMethodError` are being thrown by some code in `A`!
@@ -147,7 +147,7 @@ How can we, as library authors, spare our users of runtime errors and dependency
It works by comparing the class files of two provided JARs and report any binary incompatibilities found.
Both backwards and forwards binary incompatibility can be detected by swapping input order of the JARs.
-By incorporating MiMa's [sbt plugin](https://github.com/lightbend/mima/wiki/sbt-plugin) into your sbt build, you can easily check whether
+By incorporating MiMa's [sbt plugin](https://github.com/lightbend/mima#sbt) into your sbt build, you can easily check whether
you have accidentally introduced binary incompatible changes. Detailed instruction on how to use the sbt plugin can be found in the link.
We strongly encourage every library author to incorporate MiMa into their continuous integration and release workflow.
@@ -171,7 +171,184 @@ in library releases:
You can find detailed explanations, runnable examples and tips to maintain binary compatibility in [Binary Compatibility Code Examples & Explanation](https://github.com/jatcwang/binary-compatibility-guide).
-Again, we recommend using MiMa to double check that you have not broken binary compatibility after making changes.
+Again, we recommend using MiMa to double-check that you have not broken binary compatibility after making changes.
+
+### Changing a case class definition in a backwards-compatible manner
+
+Sometimes, it is desirable to change the definition of a case class (adding and/or removing fields) while still staying backwards-compatible with the existing usage of the case class, i.e. not breaking the so-called _binary compatibility_. The first question you should ask yourself is “do you need a _case_ class?” (as opposed to a regular class, which can be easier to evolve in a binary compatible way). A good reason for using a case class is when you need a structural implementation of `equals` and `hashCode`.
+
+To achieve that, follow this pattern:
+ * make the primary constructor private (this makes the `copy` method of the class private as well)
+ * define a private `unapply` function in the companion object (note that by doing that the case class loses the ability to be used as an extractor in match expressions)
+ * for all the fields, define `withXXX` methods on the case class that create a new instance with the respective field changed (you can use the private `copy` method to implement them)
+ * create a public constructor by defining an `apply` method in the companion object (it can use the private constructor)
+ * in Scala 2, you have to add the compiler option `-Xsource:3`
+
+Example:
+
+{% tabs case_class_compat_1 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+~~~ scala
+// Mark the primary constructor as private
+case class Person private (name: String, age: Int) {
+ // Create withXxx methods for every field, implemented by using the (private) copy method
+ def withName(name: String): Person = copy(name = name)
+ def withAge(age: Int): Person = copy(age = age)
+}
+
+object Person {
+ // Create a public constructor (which uses the private primary constructor)
+ def apply(name: String, age: Int) = new Person(name, age)
+ // Make the extractor private
+ private def unapply(p: Person): Some[Person] = Some(p)
+}
+~~~
+{% endtab %}
+{% tab 'Scala 3' %}
+
+```scala
+// Mark the primary constructor as private
+case class Person private (name: String, age: Int):
+ // Create withXxx methods for every field, implemented by using the (private) copy method
+ def withName(name: String): Person = copy(name = name)
+ def withAge(age: Int): Person = copy(age = age)
+
+object Person:
+ // Create a public constructor (which uses the private primary constructor)
+ def apply(name: String, age: Int): Person = new Person(name, age)
+ // Make the extractor private
+ private def unapply(p: Person) = p
+```
+{% endtab %}
+{% endtabs %}
+This class can be published in a library and used as follows:
+
+{% tabs case_class_compat_2 %}
+{% tab 'Scala 2 and 3' %}
+~~~ scala
+// Create a new instance
+val alice = Person("Alice", 42)
+// Transform an instance
+println(alice.withAge(alice.age + 1)) // Person(Alice, 43)
+~~~
+{% endtab %}
+{% endtabs %}
+
+If you try to use `Person` as an extractor in a match expression, it will fail with a message like “method unapply cannot be accessed as a member of Person.type”. Instead, you can use it as a typed pattern:
+
+{% tabs case_class_compat_3 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+~~~ scala
+alice match {
+ case person: Person => person.name
+}
+~~~
+{% endtab %}
+{% tab 'Scala 3' %}
+~~~ scala
+alice match
+ case person: Person => person.name
+~~~
+{% endtab %}
+{% endtabs %}
+
+Later in time, you can amend the original case class definition to, say, add an optional `address` field. You
+ * add a new field `address` and a custom `withAddress` method,
+ * update the public `apply` method in the companion object to initialize all the fields,
+ * tell MiMa to [ignore](https://github.com/lightbend/mima#filtering-binary-incompatibilities) changes to the class constructor. This step is necessary because MiMa does not yet ignore changes in private class constructor signatures (see [#738](https://github.com/lightbend/mima/issues/738)).
+
+{% tabs case_class_compat_4 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+~~~ scala
+case class Person private (name: String, age: Int, address: Option[String]) {
+ ...
+ def withAddress(address: Option[String]) = copy(address = address)
+}
+
+object Person {
+ // Update the public constructor to also initialize the address field
+ def apply(name: String, age: Int): Person = new Person(name, age, None)
+}
+~~~
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+case class Person private (name: String, age: Int, address: Option[String]):
+ ...
+ def withAddress(address: Option[String]) = copy(address = address)
+
+object Person:
+ // Update the public constructor to also initialize the address field
+ def apply(name: String, age: Int): Person = new Person(name, age, None)
+```
+{% endtab %}
+{% endtabs %}
+
+And, in your build definition:
+
+{% tabs case_class_compat_5 %}
+{% tab 'sbt' %}
+~~~ scala
+import com.typesafe.tools.mima.core._
+mimaBinaryIssueFilters += ProblemFilters.exclude[DirectMissingMethodProblem]("Person.this")
+~~~
+{% endtab %}
+{% endtabs %}
+
+Otherwise, MiMa would fail with an error like “method this(java.lang.String,Int)Unit in class Person does not have a correspondent in current version”.
+
+> Note that an alternative solution, instead of adding a MiMa exclusion filter, consists of adding back the previous
+> constructor signatures as secondary constructors:
+> ~~~ scala
+> case class Person private (name: String, age: Int, address: Option[String]):
+> ...
+> // Add back the former primary constructor signature
+> private[Person] def this(name: String, age: Int) = this(name, age, None)
+> ~~~
+
+The original users can use the case class `Person` as before, all the methods that existed before are present unmodified after this change, thus the compatibility with the existing usage is maintained.
+
+The new field `address` can be used as follows:
+
+{% tabs case_class_compat_6 %}
+{% tab 'Scala 2 and 3' %}
+~~~ scala
+// The public constructor sets the address to None by default.
+// To set the address, we call withAddress:
+val bob = Person("Bob", 21).withAddress(Some("Atlantic ocean"))
+println(bob.address)
+~~~
+{% endtab %}
+{% endtabs %}
+
+A regular case class not following this pattern would break its usage, because by adding a new field changes some methods (which could be used by somebody else), for example `copy` or the constructor itself.
+
+Optionally, you can also add overloads of the `apply` method in the companion object to initialize more fields
+in one call. In our example, we can add an overload that also initializes the `address` field:
+
+{% tabs case_class_compat_7 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+~~~ scala
+object Person {
+ // Original public constructor
+ def apply(name: String, age: Int): Person = new Person(name, age, None)
+ // Additional constructor that also sets the address
+ def apply(name: String, age: Int, address: String): Person =
+ new Person(name, age, Some(address))
+}
+~~~
+{% endtab %}
+{% tab 'Scala 3' %}
+~~~ scala
+object Person:
+ // Original public constructor
+ def apply(name: String, age: Int): Person = new Person(name, age, None)
+ // Additional constructor that also sets the address
+ def apply(name: String, age: Int, address: String): Person =
+ new Person(name, age, Some(address))
+~~~
+{% endtab %}
+{% endtabs %}
## Versioning Scheme - Communicating compatibility breakages
diff --git a/_overviews/tutorials/partest-guide.md b/_overviews/tutorials/partest-guide.md
index 36fa8c74c7..a5542ad9a4 100644
--- a/_overviews/tutorials/partest-guide.md
+++ b/_overviews/tutorials/partest-guide.md
@@ -1,5 +1,4 @@
---
-layout: inner-page-no-masthead
sitemap: false
permalink: /tutorials/partest-guide.html
redirect_to: https://github.com/scala/scala-partest
diff --git a/_overviews/tutorials/scala-for-csharp-programmers.disabled.html b/_overviews/tutorials/scala-for-csharp-programmers.disabled.html
index 7641a4ec65..6dfc4969ec 100644
--- a/_overviews/tutorials/scala-for-csharp-programmers.disabled.html
+++ b/_overviews/tutorials/scala-for-csharp-programmers.disabled.html
@@ -1,5 +1,5 @@
---
-layout: overview
+layout: singlepage-overview
title: A Scala Tutorial for C# Programmers
---
@@ -7,10 +7,10 @@
## Introduction
-Scala is a hybrid of functional and object-oriented languages.
-Its functional aspects make it very expressive when writing algorithmic
-code, and play nicely with the brave new world of concurrency; its
-object-oriented aspects keep it familiar and convenient when creating
+Scala is a hybrid of functional and object-oriented languages.
+Its functional aspects make it very expressive when writing algorithmic
+code, and play nicely with the brave new world of concurrency; its
+object-oriented aspects keep it familiar and convenient when creating
business objects or other stateful models.
## The same concepts
@@ -109,9 +109,9 @@
You can see the same principle in action for the return type of the
function. `reticulate` returns a `String`.
-Finally, the body of the method has been placed after an equals sign,
-rather than inside braces. (Braces are only necessary when the method
-body consists of multiple expressions/statements.) What's more,
+Finally, the body of the method has been placed after an equals sign,
+rather than inside braces. (Braces are only necessary when the method
+body consists of multiple expressions/statements.) What's more,
the body of the method is an expression -- that
is, something with a value -- rather than a set of statements amongst which
is a `return`. I'll come back to this when we look at a more realistic
@@ -139,7 +139,7 @@
### Base Types
Scala's base types are pretty much the same as C#'s, except that they
-are named with initial capitals, e.g. `Int` instead of `int`. (In fact
+are named with initial capitals, e.g. `Int` instead of `int`. (In fact
every type in Scala starts with an uppercase letter.) There are
no unsigned variants, and booleans are called `Boolean` instead of `bool`.
@@ -154,8 +154,8 @@
Scala has the same concept, but the function types are built into the
language, rather than being library types. Function types are
-spelled `(T1, T2, ...) => TR`. For example, a predicate of integers
-would be type `(Int) => Boolean`. If there is only one input type,
+spelled `(T1, T2, ...) => TR`. For example, a predicate of integers
+would be type `(Int) => Boolean`. If there is only one input type,
the parens can be left out like this: `Int => Boolean`.
Effectively, Scala gets rid of all those weird custom delegate types
@@ -220,7 +220,7 @@
### Tuples
-Everybody hates out parameters. We all know that code like this just
+Everybody hates out parameters. We all know that code like this just
isn't nice:
Widget widget;
@@ -229,21 +229,21 @@
widget.ReticulateSplines();
}
-And once you start composing higher-level functions into the mix, it gets
-positively nasty. Suppose I want to make a HTTP request. Well, that's
-going to produce two outputs in itself, the success code and the response
-data. But now suppose I want to time it. Writing the timing code isn't a
-problem, but now I have *three* outputs, and to paraphrase *Was Not Was*,
+And once you start composing higher-level functions into the mix, it gets
+positively nasty. Suppose I want to make a HTTP request. Well, that's
+going to produce two outputs in itself, the success code and the response
+data. But now suppose I want to time it. Writing the timing code isn't a
+problem, but now I have *three* outputs, and to paraphrase *Was Not Was*,
I feel worse than Jamie Zawinski.
-You can get around this in specific situations by creating custom types
-like `DictionaryLookupResult` or `TimedHttpRequestResult`, but eventually
+You can get around this in specific situations by creating custom types
+like `DictionaryLookupResult` or `TimedHttpRequestResult`, but eventually
the terrible allure wears off, and you just want it to work.
-Enter tuples. A tuple is just a small number of values -- a single value,
-a pair of values, a triplet of values, that sort of thing. You can tell
-that tuples were named by mathematicians because the name only makes sense
-when you look at the cases you hardly ever use (quadruple, quintuple,
+Enter tuples. A tuple is just a small number of values -- a single value,
+a pair of values, a triplet of values, that sort of thing. You can tell
+that tuples were named by mathematicians because the name only makes sense
+when you look at the cases you hardly ever use (quadruple, quintuple,
sextuple, etc.). Using tuples, our timed HTTP request might look like this:
public Tuple
+
diff --git a/_plugins/alt_details.rb b/_plugins/alt_details.rb
new file mode 100644
index 0000000000..57d2420105
--- /dev/null
+++ b/_plugins/alt_details.rb
@@ -0,0 +1 @@
+require_relative "alt-details-lib/alt-details"
diff --git a/_plugins/jekyll-tabs-lib/LICENCE b/_plugins/jekyll-tabs-lib/LICENCE
new file mode 100644
index 0000000000..43ae840e30
--- /dev/null
+++ b/_plugins/jekyll-tabs-lib/LICENCE
@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2022 Baptiste Bouchereau
+Copyright (c) 2022 LAMP/EPFL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/_plugins/jekyll-tabs-lib/README.md b/_plugins/jekyll-tabs-lib/README.md
new file mode 100644
index 0000000000..4e84712723
--- /dev/null
+++ b/_plugins/jekyll-tabs-lib/README.md
@@ -0,0 +1,8 @@
+originally sourced from https://github.com/Ovski4/jekyll-tabs.
+
+changes:
+- template.erb adapted to match the pre-existing tab html structure for docs.scala-lang.org
+- `tabs` do not use secure random uuid as the id, the `tabs` name parameter is used instead.
+- for the `tabs` block, add an optional second `class='foo bar'` parameter to allow custom classes for the tabs.
+- for the `tab` block, reorder the parameters: the tab label comes first, followed by the name of the parent `tabs`.
+- addition of a third `defaultTab` attribute for `tab`, which defaults to the final tab if not set.
diff --git a/_plugins/jekyll-tabs-lib/jekyll-tabs-4scala.rb b/_plugins/jekyll-tabs-lib/jekyll-tabs-4scala.rb
new file mode 100644
index 0000000000..b592fcc7f9
--- /dev/null
+++ b/_plugins/jekyll-tabs-lib/jekyll-tabs-4scala.rb
@@ -0,0 +1,189 @@
+require 'erb'
+
+module Jekyll
+ module Tabs
+
+ ScalaVersions = ['Scala 2', 'Scala 3']
+ BuildTools = ['Scala CLI', 'sbt', 'Mill']
+
+ def self.unquote(string)
+ string.gsub(/^['"]|['"]$/, '')
+ end
+
+ def self.asAnchor(title)
+ title.gsub(/[^a-zA-Z0-9\-_]/, '-').gsub(/-{2,}/, '-').downcase
+ end
+
+ TabDetails = Struct.new(:label, :anchor, :defaultTab, :content, keyword_init: true)
+
+ class TabsBlock < Liquid::Block
+ SYNTAX = /^\s*(#{Liquid::QuotedFragment})(?=\s+class=(#{Liquid::QuotedFragment}))?/o
+ Syntax = SYNTAX
+
+ def initialize(block_name, markup, tokens)
+ super
+
+ if markup =~ SYNTAX
+ @name = Tabs::unquote($1)
+ @css_classes = ""
+ @tab_class = ""
+ if $2
+ css_class = Tabs::unquote($2)
+ css_class.strip!
+ @tab_class = css_class
+ # append $2 to @css_classes
+ @css_classes = " #{css_class}"
+ end
+ else
+ raise SyntaxError.new("Block #{block_name} requires 1 attribute")
+ end
+ end
+
+ def render(context)
+ environment = context.environments.first
+ environment["tabs-#{@name}"] = [] # reset every time (so page translations can use the same name)
+ if environment["CURRENT_TABS_ENV"].nil?
+ environment["CURRENT_TABS_ENV"] = @name
+ else
+ raise SyntaxError.new("Nested tabs are not supported")
+ end
+ super # super call renders the internal content
+ environment["CURRENT_TABS_ENV"] = nil # reset after rendering
+ foundDefault = false
+
+ allTabs = environment["tabs-#{@name}"]
+
+ seenTabs = []
+
+ def joinTabs(tabs)
+ tabs.to_a.map{|item| "'#{item}'"}.join(", ")
+ end
+
+ def errorInvalidTab(tab, expectedTabs)
+ SyntaxError.new(
+ "Tab label '#{tab.label}' is not valid for tabs '#{@name}' with " +
+ "class=#{@tab_class}. Valid tab labels are: #{joinTabs(expectedTabs)}")
+ end
+
+ def errorTabWithoutClass(tab, tabClass)
+ SyntaxError.new(
+ "Tab label '#{tab.label}' is not valid for tabs '#{@name}' without " +
+ "class=#{tabClass}")
+ end
+
+ def errorMissingTab(expectedTabs)
+ SyntaxError.new(
+ "Tabs '#{@name}' with class=#{@tab_class} must have exactly the following " +
+ "tab labels: #{joinTabs(expectedTabs)}")
+ end
+
+ def errorDuplicateTab(tab)
+ SyntaxError.new("Duplicate tab label '#{tab.label}' in tabs '#{@name}'")
+ end
+
+ def errorTabDefault(tab)
+ SyntaxError.new(
+ "Tab label '#{tab.label}' should not be default for tabs '#{@name}' " +
+ "with class=#{@tab_class}")
+ end
+
+ allTabs.each do | tab |
+ if seenTabs.include? tab.label
+ raise errorDuplicateTab(tab)
+ end
+ seenTabs.push tab.label
+ if tab.defaultTab
+ foundDefault = true
+ end
+
+ def checkTab(tab, tabClass, expectedTabs, raiseIfMissingClass)
+ isValid = expectedTabs.include? tab.label
+ if @tab_class == tabClass
+ if !isValid
+ raise errorInvalidTab(tab, expectedTabs)
+ elsif tab.defaultTab
+ raise errorTabDefault(tab)
+ end
+ elsif raiseIfMissingClass and isValid
+ raise errorTabWithoutClass(tab, tabClass)
+ end
+ end
+
+ checkTab(tab, "tabs-scala-version", Tabs::ScalaVersions, true)
+ checkTab(tab, "tabs-build-tool", Tabs::BuildTools, false)
+ end
+
+ def checkExhaustivity(seenTabs, tabClass, expectedTabs)
+ if @tab_class == tabClass and seenTabs != expectedTabs
+ raise errorMissingTab(expectedTabs)
+ end
+ end
+
+ checkExhaustivity(seenTabs, "tabs-scala-version", Tabs::ScalaVersions)
+ checkExhaustivity(seenTabs, "tabs-build-tool", Tabs::BuildTools)
+
+ if !foundDefault and allTabs.length > 0
+ if @tab_class == "tabs-scala-version"
+ # set last tab to default ('Scala 3')
+ allTabs[-1].defaultTab = true
+ else
+ # set first tab to default
+ allTabs[0].defaultTab = true
+ end
+ end
+
+ currentDirectory = File.dirname(__FILE__)
+ templateFile = File.read(currentDirectory + '/template.erb')
+ template = ERB.new(templateFile)
+ template.result(binding)
+ end
+ end
+
+ class TabBlock < Liquid::Block
+ alias_method :render_block, :render
+
+ SYNTAX = /^\s*(#{Liquid::QuotedFragment})\s+(?:for=(#{Liquid::QuotedFragment}))?(?:\s+(defaultTab))?/o
+ Syntax = SYNTAX
+
+ def initialize(block_name, markup, tokens)
+ super
+
+ if markup =~ SYNTAX
+ @tab = Tabs::unquote($1)
+ if $2
+ @name = Tabs::unquote($2)
+ end
+ @anchor = Tabs::asAnchor(@tab)
+ if $3
+ @defaultTab = true
+ end
+ else
+ raise SyntaxError.new("Block #{block_name} requires at least 2 attributes")
+ end
+ end
+
+ def render(context)
+ site = context.registers[:site]
+ mdoc_converter = site.find_converter_instance(::Jekyll::MdocConverter)
+ converter = site.find_converter_instance(::Jekyll::Converters::Markdown)
+ pre_content = mdoc_converter.convert(render_block(context))
+ content = converter.convert(pre_content)
+ tabcontent = TabDetails.new(label: @tab, anchor: @anchor, defaultTab: @defaultTab, content: content)
+ environment = context.environments.first
+ tab_env = environment["CURRENT_TABS_ENV"]
+ if tab_env.nil?
+ raise SyntaxError.new("Tab block '#{tabcontent.label}' must be inside a tabs block")
+ end
+ if !@name.nil? && tab_env != @name
+ raise SyntaxError.new(
+ "Tab block '#{@tab}' for=#{@name} does not match its enclosing tabs block #{tab_env}")
+ end
+ environment["tabs-#{tab_env}"] ||= []
+ environment["tabs-#{tab_env}"] << tabcontent
+ end
+ end
+ end
+end
+
+Liquid::Template.register_tag('tab', Jekyll::Tabs::TabBlock)
+Liquid::Template.register_tag('tabs', Jekyll::Tabs::TabsBlock)
diff --git a/_plugins/jekyll-tabs-lib/jekyll-tabs/version.rb b/_plugins/jekyll-tabs-lib/jekyll-tabs/version.rb
new file mode 100644
index 0000000000..498949a13d
--- /dev/null
+++ b/_plugins/jekyll-tabs-lib/jekyll-tabs/version.rb
@@ -0,0 +1,5 @@
+module Jekyll
+ module Tabs
+ VERSION = "1.1.1"
+ end
+end
diff --git a/_plugins/jekyll-tabs-lib/template.erb b/_plugins/jekyll-tabs-lib/template.erb
new file mode 100644
index 0000000000..e9d7867102
--- /dev/null
+++ b/_plugins/jekyll-tabs-lib/template.erb
@@ -0,0 +1,29 @@
+
+
+
+
+
+
+
+ <%= altDetailsContent %>
+
+
+
diff --git a/_plugins/jekyll_tabs_4scala.rb b/_plugins/jekyll_tabs_4scala.rb
new file mode 100644
index 0000000000..7470d622a7
--- /dev/null
+++ b/_plugins/jekyll_tabs_4scala.rb
@@ -0,0 +1 @@
+require_relative "jekyll-tabs-lib/jekyll-tabs-4scala"
diff --git a/_plugins/mdoc_replace.rb b/_plugins/mdoc_replace.rb
index 0b62828227..7cecf73aa6 100644
--- a/_plugins/mdoc_replace.rb
+++ b/_plugins/mdoc_replace.rb
@@ -12,9 +12,11 @@ def output_ext(ext)
end
def convert(content)
+ content = content.gsub("```scala mdoc:compile-only\n", "```scala\n")
content = content.gsub("```scala mdoc:fail\n", "```scala\n")
content = content.gsub("```scala mdoc:crash\n", "```scala\n")
content = content.gsub("```scala mdoc:nest\n", "```scala\n")
+ content = content.gsub("```scala mdoc:reset:crash\n", "```scala\n")
content = content.gsub("```scala mdoc:reset\n", "```scala\n")
content.gsub("```scala mdoc\n", "```scala\n")
end
diff --git a/_pt-br/tour/abstract-type-members.md b/_pt-br/tour/abstract-type-members.md
index 8a798f4468..e8dba1011c 100644
--- a/_pt-br/tour/abstract-type-members.md
+++ b/_pt-br/tour/abstract-type-members.md
@@ -39,16 +39,14 @@ abstract class IntSeqBuffer extends SeqBuffer {
type U = Int
}
-object AbstractTypeTest1 extends App {
- def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer =
- new IntSeqBuffer {
- type T = List[U]
- val element = List(elem1, elem2)
- }
- val buf = newIntSeqBuf(7, 8)
- println("length = " + buf.length)
- println("content = " + buf.element)
-}
+def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer =
+ new IntSeqBuffer {
+ type T = List[U]
+ val element = List(elem1, elem2)
+ }
+val buf = newIntSeqBuf(7, 8)
+println("length = " + buf.length)
+println("content = " + buf.element)
```
O tipo de retorno do método `newIntSeqBuf` refere-se a uma especialização da trait `Buffer` no qual o tipo `U` é agora equivalente a `Int`. Declaramos um tipo *alias* semelhante ao que temos na instanciação da classe anônima dentro do corpo do método `newIntSeqBuf`. Criamos uma nova instância de `IntSeqBuffer` na qual o tipo `T` refere-se a `List[Int]`.
diff --git a/_pt-br/tour/annotations.md b/_pt-br/tour/annotations.md
index 5d0842e42c..55d49cc441 100644
--- a/_pt-br/tour/annotations.md
+++ b/_pt-br/tour/annotations.md
@@ -5,7 +5,7 @@ partof: scala-tour
num: 31
next-page: packages-and-imports
-previous-page: automatic-closures
+previous-page: operators
language: pt-br
---
diff --git a/_pt-br/tour/automatic-closures.md b/_pt-br/tour/automatic-closures.md
deleted file mode 100644
index 2f9072a59d..0000000000
--- a/_pt-br/tour/automatic-closures.md
+++ /dev/null
@@ -1,72 +0,0 @@
----
-layout: tour
-title: Construção Automática de Closures de Tipo-Dependente
-partof: scala-tour
-
-num: 30
-next-page: annotations
-previous-page: operators
-language: pt-br
----
-
-_Nota de tradução: A palavra `closure` em pode ser traduzida como encerramento/fechamento, porém é preferível utilizar a notação original_
-
-Scala permite funções sem parâmetros como parâmetros de métodos. Quando um tal método é chamado, os parâmetros reais para nomes de função sem parâmetros não são avaliados e uma função nula é passada em vez disso, tal função encapsula a computação do parâmetro correspondente (isso é conhecido por avaliação *call-by-name*).
-
-O código a seguir demonstra esse mecanismo:
-
-```scala mdoc
-object TargetTest1 extends App {
- def whileLoop(cond: => Boolean)(body: => Unit): Unit =
- if (cond) {
- body
- whileLoop(cond)(body)
- }
- var i = 10
- whileLoop (i > 0) {
- println(i)
- i -= 1
- }
-}
-```
-
-A função `whileLoop` recebe dois parâmetros: `cond` e `body`. Quando a função é aplicada, os parâmetros reais não são avaliados. Mas sempre que os parâmetros formais são usados no corpo de `whileLoop`, as funções nulas criadas implicitamente serão avaliadas em seu lugar. Assim, o nosso método `whileLoop` implementa um while-loop Java-like com um esquema de implementação recursiva.
-
-Podemos combinar o uso de [operadores infix/postfix](operators.html) com este mecanismo para criar declarações mais complexas (com uma sintaxe agradável).
-
-Aqui está a implementação de uma instrução que executa loop a menos que uma condição seja satisfeita:
-
-```scala mdoc
-object TargetTest2 extends App {
- def loop(body: => Unit): LoopUnlessCond =
- new LoopUnlessCond(body)
- protected class LoopUnlessCond(body: => Unit) {
- def unless(cond: => Boolean) {
- body
- if (!cond) unless(cond)
- }
- }
- var i = 10
- loop {
- println("i = " + i)
- i -= 1
- } unless (i == 0)
-}
-```
-
-A função `loop` aceita apenas um corpo e retorna uma instância da classe` LoopUnlessCond` (que encapsula este objeto de corpo). Note que o corpo ainda não foi avaliado. A classe `LoopUnlessCond` tem um método `unless` que podemos usar como um *operador infix*. Dessa forma, obtemos uma sintaxe bastante natural para nosso novo loop: `loop {
+ <% environment["tabs-#{@name}"].each do | tab | %>
+ >
+ <% end %>
+
+
+
+ <% environment["tabs-#{@name}"].each do | tab | %>
+
+
+ <% end %>
+
+
+ <%= tab.content %>
+
+
+{% altDetails need-help-info-box 'Нужна помощь?' class=help-info %}
+*Если у вас возникли проблемы с настройкой Scala, смело обращайтесь за помощью в канал `#scala-users`
+[нашего Discord](https://discord.com/invite/scala).*
+{% endaltDetails %}
+
+
+## Ресурсы для новичков
+
+{% include inner-documentation-sections.html links=page.newcomer_resources %}
+
+## Установка Scala на компьютер
+
+Установка Scala означает установку различных инструментов командной строки,
+таких как компилятор Scala и инструменты сборки.
+Мы рекомендуем использовать инструмент установки "Coursier",
+который автоматически устанавливает все зависимости.
+Также возможно установить по отдельности каждый инструмент вручную.
+
+### Использование Scala Installer (рекомендованный путь)
+
+Установщик Scala — это инструмент [Coursier](https://get-coursier.io/docs/cli-overview),
+основная команда которого называется `cs`.
+Он гарантирует, что в системе установлены JVM и стандартные инструменты Scala.
+Установите его в своей системе, следуя следующим инструкциям.
+
+
+{% tabs install-cs-setup-tabs class=platform-os-options %}
+
+
+{% tab macOS for=install-cs-setup-tabs %}
+Запустите в терминале следующую команду, следуя инструкциям на экране:
+{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-brew %}
+{% altDetails cs-setup-macos-nobrew "В качестве альтернативы, если вы не используете Homebrew:" %}
+ {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-x86-64 %}
+{% endaltDetails %}
+{% endtab %}
+
+
+
+{% tab Linux for=install-cs-setup-tabs %}
+ Запустите в терминале следующую команду, следуя инструкциям на экране:
+ {% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.linux-x86-64 %}
+{% endtab %}
+
+
+
+{% tab Windows for=install-cs-setup-tabs %}
+ Загрузите и запустите [установщик Scala для Windows]({{site.data.setup-scala.windows-link}})
+ на базе Coursier и следуйте инструкциям на экране.
+{% endtab %}
+
+
+
+{% tab Иное for=install-cs-setup-tabs defaultTab %}
+
+ Следуйте документации Coursier о том,
+ [как установить и запустить `cs setup`](https://get-coursier.io/docs/cli-installation).
+{% endtab %}
+
+
+{% endtabs %}
+
+
+
+{% altDetails testing-your-setup 'Тестирование установки' %}
+Проверьте корректность установки с помощью команды `scala -version`, которая должна вывести:
+```bash
+$ scala -version
+Scala code runner version: 1.4.3
+Scala version (default): {{site.scala-3-version}}
+```
+Если сообщение не выдано, возможно, необходимо перезайти в терминал (или перезагрузиться),
+чтобы изменения вступили в силу.
+{% endaltDetails %}
+
+
+Наряду с JVM `cs setup` также устанавливает полезные инструменты командной строки:
+
+| Commands | Description |
+|---------------|--------------------------------------------------------------------------------------|
+| `scalac` | компилятор Scala |
+| `scala` | Scala REPL и средство запуска сценариев |
+| `scala-cli` | [Scala CLI](https://scala-cli.virtuslab.org), интерактивный инструментарий для Scala |
+| `sbt`, `sbtn` | Инструмент сборки [sbt](https://www.scala-sbt.org/) |
+| `amm` | [Ammonite](https://ammonite.io/) — улучшенный REPL |
+| `scalafmt` | [Scalafmt](https://scalameta.org/scalafmt/) - средство форматирования кода Scala |
+
+Дополнительная информация о cs [доступна по ссылке](https://get-coursier.io/docs/cli-overview).
+
+> `cs setup` по умолчанию устанавливает компилятор и исполняющую программу Scala 3
+> (команды `scalac` и `scala` соответственно). Независимо от того, собираетесь ли вы использовать Scala 2 или 3,
+> обычно это не проблема, потому что в большинстве проектов используется инструмент сборки,
+> который будет использовать правильную версию Scala независимо от того, какая версия установлена "глобально".
+> Тем не менее, вы всегда можете запустить конкретную версию Scala, используя
+> ```
+> $ cs launch scala:{{ site.scala-version }}
+> $ cs launch scalac:{{ site.scala-version }}
+> ```
+> Если предпочтительно, чтобы по умолчанию запускалась Scala 2, вы можете принудительно установить эту версию с помощью:
+> ```
+> $ cs install scala:{{ site.scala-version }} scalac:{{ site.scala-version }}
+> ```
+
+### ...или вручную
+
+Для компиляции, запуска, тестирования и упаковки проекта Scala нужны только два инструмента:
+Java 8 или 11 и sbt.
+Чтобы установить их вручную:
+
+1. если не установлена Java 8 или 11, загрузите Java из
+ [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html),
+ или [AdoptOpenJDK 8/11](https://adoptopenjdk.net/).
+ Подробную информацию о совместимости Scala/Java см. в разделе [Совместимость с JDK](/overviews/jdk-compatibility/overview.html).
+1. установить [sbt](https://www.scala-sbt.org/download.html)
+
+## Создание проекта "Hello World" с помощью sbt
+
+В следующих разделах объясняется как создавать проект Scala после того, как установлен sbt.
+
+Для создания проекта можно использовать командную строку или IDE.
+Мы рекомендуем командную строку, если вы с ней знакомы.
+
+### Использование командной строки
+
+sbt — это инструмент сборки для Scala. sbt компилирует, запускает и тестирует Scala код
+(он также может публиковать библиотеки и выполнять множество других задач).
+
+Чтобы создать новый проект Scala с помощью sbt:
+
+1. `cd` в пустую папку.
+1. Запустите команду `sbt new scala/scala3.g8`, чтобы создать проект на Scala 3,
+ или `sbt new scala/hello-world.g8` для создания проекта на Scala 2.
+ Она извлекает шаблон проекта из GitHub.
+ Эта команда также создает папку `target`, которую вы можете игнорировать.
+1. При появлении запроса назовите приложение `hello-world`.
+ Это создаст проект под названием "hello-world".
+1. Будет сгенерировано следующее:
+
+```
+- hello-world
+ - project (sbt использует эту папку для собственных файлов)
+ - build.properties
+ - build.sbt (файл определения сборки sbt)
+ - src
+ - main
+ - scala (здесь весь Scala code)
+ - Main.scala (точка входа в программу) <-- это все, что сейчас нужно
+```
+
+Дополнительную документацию по sbt можно найти в [Scala Book](/scala3/book/tools-sbt.html)
+(см. [здесь](/overviews/scala-book/scala-build-tool-sbt.html) для версии Scala 2)
+и в официальной [документации sbt](https://www.scala-sbt.org/1.x/docs/index.html).
+
+### С интегрированной средой разработки (IDE)
+
+Вы можете пропустить оставшуюся часть страницы и сразу перейти к [созданию проекта Scala с помощью IntelliJ и sbt](/ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html).
+
+
+## Открыть проект hello-world
+
+Давайте используем IDE, чтобы открыть проект. Самые популярные из них — IntelliJ и VSCode.
+Оба предлагают обширные возможности, но вы по-прежнему можете использовать [множество других редакторов](https://scalameta.org/metals/docs/editors/overview.html).
+
+
+### Использование IntelliJ
+
+1. Загрузите и установите [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
+1. Установите Scala plugin, следуя [инструкциям по установке плагинов IntelliJ](https://www.jetbrains.com/help/idea/managing-plugins.html)
+1. Откройте файл `build.sbt`, затем выберете *Open as a project*
+
+### Использование VSCode с metals
+
+1. Загрузите [VSCode](https://code.visualstudio.com/Download)
+1. Установите расширение Metals из [Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals)
+1. Затем откройте каталог, содержащий файл `build.sbt` (это должен быть каталог `hello-world`, если вы следовали предыдущим инструкциям). Когда будет предложено, выберите *Import build*.
+
+> [Metals](https://scalameta.org/metals) — это “языковой сервер Scala”, обеспечивающий поддержку написания кода Scala в VS Code и других редакторах,
+> таких как [Atom, Sublime Text и других](https://scalameta.org/metals/docs/editors/overview.html), использующих Language Server Protocol.
+>
+> Под капотом Metals взаимодействует со средством сборки с помощью
+> [Build Server Protocol (BSP)](https://build-server-protocol.github.io/).
+> Подробнее о том, как работает Metals, см. [“Написание Scala в VS Code, Vim, Emacs, Atom и Sublime Text с помощью Metals”](https://www.scala-lang.org/2019/04/16/metals.html).
+
+### Знакомство с исходным кодом
+
+Просмотрите эти два файла в своей IDE:
+
+- _build.sbt_
+- _src/main/scala/Main.scala_
+
+При запуске проекта на следующем шаге, конфигурация в _build.sbt_ будет использована для запуска кода в _src/main/scala/Main.scala_.
+
+## Запуск Hello World
+
+Код в _Main.scala_ можно запускать из IDE, если удобно.
+
+Но вы также можете запустить приложение из терминала, выполнив следующие действия:
+
+1. `cd` в `hello-world`.
+1. Запустить `sbt`. Эта команда открывает sbt-консоль.
+1. В консоле введите `~run`. `~` является необязательным, но заставляет sbt повторно запускаться при каждом сохранении файла,
+ обеспечивая быстрый цикл редактирования/запуска/отладки. sbt также создаст директорию `target`, которую пока можно игнорировать.
+
+После окончания экспериментирования с проектом, нажмите `[Enter]`, чтобы прервать команду `run`.
+Затем введите `exit` или нажмите `[Ctrl+D]`, чтобы выйти из sbt и вернуться в командную строку.
+
+## Следующие шаги
+
+После того как пройдете приведенные выше обучающие материалы, подумайте о том, чтобы проверить:
+
+* [The Scala Book](/scala3/book/introduction.html) (см. версию для Scala 2 [здесь](/overviews/scala-book/introduction.html)), которая содержит набор коротких уроков, знакомящих с основными функциями Scala.
+* [The Tour of Scala](/ru/tour/tour-of-scala.html) для краткого ознакомления с функциями Scala.
+* [Обучающие ресурсы](/online-courses.html), которые включают в себя интерактивные онлайн-учебники и курсы.
+* [Наш список некоторых популярных книг по Scala](/books.html).
+* [Руководство по миграции](/scala3/guides/migration/compatibility-intro.html) поможет перенести существующую кодовую базу Scala 2 на Scala 3.
+
+## Получение помощи
+
+Существует множество рассылок и real-time чатов на случай, если вы хотите быстро связаться с другими пользователями Scala.
+Посетите страницу [нашего сообщества](https://scala-lang.org/community/), чтобы ознакомиться со списком этих ресурсов и узнать, куда можно обратиться за помощью.
diff --git a/_ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md b/_ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md
new file mode 100644
index 0000000000..dd13a44443
--- /dev/null
+++ b/_ru/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md
@@ -0,0 +1,104 @@
+---
+title: Создание проекта Scala с IntelliJ и sbt
+layout: singlepage-overview
+partof: building-a-scala-project-with-intellij-and-sbt
+language: ru
+disqus: true
+previous-page: /ru/getting-started/intellij-track/getting-started-with-scala-in-intellij
+next-page: /ru/testing-scala-in-intellij-with-scalatest
+---
+
+В этом руководстве мы увидим, как создать проект Scala с помощью [sbt](https://www.scala-sbt.org/1.x/docs/index.html).
+sbt — популярный инструмент для компиляции, запуска и тестирования проектов Scala любой сложности.
+Использование инструмента сборки, такого как sbt (или Maven/Gradle), становится необходимым,
+если вы создаете проекты с зависимостями или несколькими файлами кода.
+Мы предполагаем, что вы прочитали [первое руководство](getting-started-with-scala-in-intellij.html).
+
+## Создание проекта
+В этом разделе мы покажем вам, как создать проект в IntelliJ.
+Однако, если вы знакомы с командной строкой, мы рекомендуем вам попробовать
+[Начало работы со Scala и sbt в командной строке]({{site.baseurl}}/ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html)
+а затем вернуться к разделу "Написание Scala кода".
+
+1. Если вы не создавали проект из командной строки, откройте IntelliJ и выберите "Create New Project"
+ * На левой панели выберите Scala, а на правой панели - sbt
+ * Нажмите **Next**
+ * Назовите проект "SbtExampleProject"
+1. Если вы уже создали проект в командной строке, откройте IntelliJ, выберите *Import Project* и откройте `build.sbt` файл вашего проекта
+1. Убедитесь, что ваша **JDK version** - это 1.8, а **sbt version** не ниже 0.13.13
+1. Выберите **Use auto-import**, чтобы доступные зависимости загружались автоматически.
+1. Выберите **Finish**
+
+## Разбор структуры каталогов
+sbt создает множество каталогов, которые могут быть полезны, когда вы начнете создавать более сложные проекты.
+На данный момент вы можете игнорировать большинство из них, но вот объяснение, для чего все это:
+
+```
+- .idea (файлы IntelliJ)
+- project (плагины и дополнительные настройки sbt)
+- src (исходные файлы)
+ - main (код приложения)
+ - java (исходные файлы Java)
+ - scala (исходные файлы Scala) <-- это все, что вам сейчас нужно
+ - scala-2.12 (файлы, специфичные для Scala 2.12)
+ - test (модульные тесты)
+- target (сгенерированные файлы)
+- build.sbt (файл определения сборки для sbt)
+```
+
+
+## Написание Scala-кода
+1. На панели слева **Project**, разверните `SbtExampleProject` => `src` => `main`
+1. Щелкните правой кнопкой мыши на `scala` и выберете **New** => **Package**
+1. Назовите пакет `example` и нажмите **OK** (или просто нажмите клавишу **Enter** или **Return**).
+1. Щелкните правой кнопкой мыши на пакете `example` и выберите **New** => **Scala class**
+(если вы не видите эту опцию, щелкните правой кнопкой мыши на `SbtExampleProject`, кликните на **Add Frameworks Support**, выберете **Scala** и продолжите)
+1. Назовите класс `Main` и измените **Kind** на `Object`.
+1. Вставьте следующий код:
+
+```
+@main def run() =
+ val ages = Seq(42, 75, 29, 64)
+ println(s"The oldest person is ${ages.max}")
+```
+
+Примечание: IntelliJ имеет собственную реализацию компилятора Scala,
+и иногда ваш код верен, даже если IntelliJ указывает обратное.
+Вы всегда можете проверить, может ли sbt запустить ваш проект в командной строке.
+
+## Запуск проекта
+1. В меню **Run**, выберите **Edit configurations**
+1. Нажмите кнопку **+** и выберите **sbt Task**.
+1. Назовите задачу `Run the program`.
+1. В поле **Tasks**, введите `~run`. `~` заставляет sbt перекомпилировать
+и повторно запускать проект при каждом сохранении изменений в файле проекта.
+1. Нажмите **OK**.
+1. В меню **Run** нажмите **Run 'Run the program'**.
+1. В коде измените `75` на `61` и посмотрите на обновленные результаты в консоли.
+
+## Добавление зависимости
+Немного меняя тему, давайте посмотрим, как использовать опубликованные библиотеки
+для добавления дополнительных функций в наши приложения.
+1. Откройте `build.sbt` и добавьте следующую строку:
+
+```
+libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2"
+```
+Здесь `libraryDependencies` представляет набор зависимостей,
+и с помощью `+=` мы добавляем зависимость [scala-parser-combinators](https://github.com/scala/scala-parser-combinators)
+к набору зависимостей, которые sbt будет загружать при запуске.
+Теперь в любом файле Scala можно импортировать классы, объекты и т.д. из `scala-parser-combinators` с помощью обычного импорта.
+
+Вы можете найти больше опубликованных библиотек на [Scaladex](https://index.scala-lang.org/), каталоге библиотек Scala,
+где вы также можете скопировать указанную выше информацию о зависимостях для вставки в свой файл `build.sbt`.
+
+## Следующие шаги
+
+Перейдите к следующему руководству из серии _getting started with IntelliJ_ и узнайте, как [тестировать Scala в IntelliJ с помощью ScalaTest](testing-scala-in-intellij-with-scalatest.html).
+
+**или**
+
+* [The Scala Book](/scala3/book/introduction.html), содержащая набор коротких уроков, знакомящих с основными функциями Scala.
+* [Тур по Scala](/ru/tour/tour-of-scala.html) для краткого ознакомления с возможностями Scala.
+- Продолжайте изучать Scala в интерактивном режиме на
+ [Scala Exercises](https://www.scala-exercises.org/scala_tutorial).
diff --git a/_ru/getting-started/intellij-track/getting-started-with-scala-in-intellij.md b/_ru/getting-started/intellij-track/getting-started-with-scala-in-intellij.md
new file mode 100644
index 0000000000..65337bc058
--- /dev/null
+++ b/_ru/getting-started/intellij-track/getting-started-with-scala-in-intellij.md
@@ -0,0 +1,124 @@
+---
+title: Начало работы со Scala в IntelliJ
+layout: singlepage-overview
+partof: getting-started-with-scala-in-intellij
+language: ru
+disqus: true
+next-page: /ru/building-a-scala-project-with-intellij-and-sbt
+---
+
+В этом руководстве мы увидим, как создать минимальный проект Scala с помощью IntelliJ IDE со Scala плагином.
+В этом руководстве IntelliJ загрузит Scala за вас.
+
+## Установка
+
+1. Убедитесь, что у вас установлена Java 8 JDK (также известная как 1.8)
+ * Запустите `javac -version` в командной строке и убедитесь, что выдается
+ `javac 1.8.___`
+ * Если у вас нет версии 1.8 или выше, [установите JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
+1. Затем загрузите и установите [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
+1. Затем, после запуска IntelliJ, вы можете загрузить и установить Scala плагин, следуя
+ [инструкции по установке плагинов IntelliJ](https://www.jetbrains.com/help/idea/installing-updating-and-uninstalling-repository-plugins.html) (найдите "Scala" в меню плагинов).
+
+Когда мы создадим проект, то установим последнюю версию Scala.
+Примечание: Если вы хотите открыть существующий проект Scala, вы можете нажать **Open**
+при запуске IntelliJ.
+
+## Создание проекта
+
+1. Откройте IntelliJ и нажмите **File** => **New** => **Project**
+1. На левой панели выберите Scala. На правой панели - IDEA.
+1. Назовите проект **HelloWorld**
+1. Если вы впервые создаете Scala проект с помощью IntelliJ, вам необходимо установить Scala SDK.
+ Справа от поля Scala SDK нажмите кнопку **Create**.
+1. Выберите последний номер версии (например, {{ site.scala-version }}) и нажмите **Download**.
+Это может занять несколько минут, но тот же пакет SDK могут использовать последующие проекты.
+1. Когда SDK будет установлен и вы вернетесь в окно "New Project", нажмите **Finish**.
+
+## Написание кода
+
+1. На левой панели **Project** щелкните правой кнопкой мыши на папке `src` и выберите
+**New** => **Scala class**. Если вы не видите **Scala class**, щелкните правой кнопкой мыши на **HelloWorld**
+и выберите **Add Framework Support...**, затем - **Scala** и продолжить.
+Если вы видите ошибку **Error: library is not specified**, вы можете либо нажать кнопку загрузки,
+либо выбрать путь к библиотеке вручную. Если вы видите только **Scala Worksheet** попробуйте развернуть папку `src`
+и её подпапку `main`, а затем правой кнопкой мыши на папке `scala`.
+1. Назовите класс `Hello` и измените **Kind** на `object`.
+1. Вставьте следующий код:
+
+{% tabs hello-world-entry-point class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=hello-world-entry-point %}
+
+```
+object Hello extends App {
+ println("Hello, World!")
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=hello-world-entry-point %}
+
+```
+@main def hello(): Unit =
+ println("Hello, World!")
+```
+
+В Scala 3 вы можете удалить объект `Hello` и вместо него определить метод верхнего уровня `hello`
+с аннотацией `@main`.
+
+{% endtab %}
+
+{% endtabs %}
+
+## Запуск
+
+{% tabs hello-world-run class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=hello-world-run %}
+
+* Щелкните правой кнопкой мыши на `Hello` в своем коде и выберите **Run 'Hello'**.
+* Готово!
+
+{% endtab %}
+
+{% tab 'Scala 3' for=hello-world-run %}
+
+* Щелкните правой кнопкой мыши на `hello` в своем коде и выберите **Run 'hello'**.
+* Готово!
+
+{% endtab %}
+
+{% endtabs %}
+
+## Эксперименты со Скалой
+
+Хороший способ попробовать примеры кода — использовать Scala Worksheets.
+
+1. В левой панели проекта щелкните правой кнопкой мыши на
+`src` и выберите **New** => **Scala Worksheet**.
+2. Назовите новый Scala worksheet "Mathematician".
+3. Введите следующий код в worksheet:
+
+{% tabs square %}
+{% tab 'Scala 2 and 3' for=square %}
+```
+def square(x: Int): Int = x * x
+
+square(2)
+```
+{% endtab %}
+{% endtabs %}
+
+После запуска кода вы заметите, что результаты его выполнения выводятся на правой панели.
+Если вы не видите правую панель, щелкните правой кнопкой мыши на вашем Scala worksheet на панели "Проект"
+и выберите "Evaluate Worksheet".
+
+## Следующие шаги
+
+Теперь вы знаете, как создать простой Scala проект, который можно использовать для изучения языка.
+В следующем уроке мы представим важный инструмент сборки под названием sbt,
+который можно использовать для простых проектов и рабочих приложений.
+
+Далее: [Создание проекта Scala с IntelliJ и sbt](building-a-scala-project-with-intellij-and-sbt.html)
diff --git a/_ru/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md b/_ru/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md
new file mode 100644
index 0000000000..7a2ffef8fe
--- /dev/null
+++ b/_ru/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md
@@ -0,0 +1,73 @@
+---
+title: Тестирование Scala в IntelliJ с помощью ScalaTest
+layout: singlepage-overview
+partof: testing-scala-in-intellij-with-scalatest
+language: ru
+disqus: true
+previous-page: /ru/building-a-scala-project-with-intellij-and-sbt
+---
+
+Для Scala существует множество библиотек и методологий тестирования,
+но в этом руководстве мы продемонстрируем один популярный вариант из фреймворка ScalaTest
+под названием [AnyFunSuite](https://www.scalatest.org/getting_started_with_fun_suite).
+
+Это предполагает, что вы знаете, [как создать проект в IntelliJ](building-a-scala-project-with-intellij-and-sbt.html).
+
+## Настройка
+1. Создайте sbt проект в IntelliJ.
+1. Добавьте зависимость ScalaTest:
+ 1. Добавьте зависимость ScalaTest в свой файл `build.sbt`:
+ ```
+ libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test
+ ```
+ 1. Если вы получили уведомление "build.sbt was changed", выберите **auto-import**.
+ 1. Эти два действия заставят `sbt` подгрузить библиотеки ScalaTest.
+ 1. Дождитесь окончания синхронизации `sbt`; в противном случае, `AnyFunSuite` и `test()` не будет распознаны.
+1. На панели проекта слева разверните `src` => `main`.
+1. Щелкните правой кнопкой мыши на `scala` и выберите **New** => **Scala class**.
+1. Назовите новый класс `CubeCalculator`, измените **Kind** на `object`, или дважды щелкните на `object`.
+1. Вставьте следующий код:
+ ```
+ object CubeCalculator:
+ def cube(x: Int) =
+ x * x * x
+ ```
+
+## Создание теста
+1. На панели проекта слева разверните `src` => `test`.
+1. Щелкните правой кнопкой мыши на `scala` и выберите **New** => **Scala class**.
+1. Назовите новый класс `CubeCalculatorTest` и нажмите **Enter** или дважды щелкните на `class`.
+1. Вставьте следующий код:
+ ```
+ import org.scalatest.funsuite.AnyFunSuite
+
+ class CubeCalculatorTest extends AnyFunSuite:
+ test("CubeCalculator.cube") {
+ assert(CubeCalculator.cube(3) === 27)
+ }
+ ```
+1. В исходном коде щелкните правой кнопкой мыши на `CubeCalculatorTest` и выберите
+ **Run 'CubeCalculatorTest'**.
+
+## Разбор кода
+
+Давайте разберем код построчно:
+
+* `class CubeCalculatorTest` означает, что мы тестируем `CubeCalculator`
+* `extends AnyFunSuite` позволяет нам использовать функциональность класса AnyFunSuite из ScalaTest,
+ такую как функция `test`
+* `test` это функция из библиотеки FunSuite, которая собирает результаты проверок в теле функции.
+* `"CubeCalculator.cube"` - это имя для теста. Вы можете называть тест как угодно, но по соглашению используется имя — "ClassName.methodName".
+* `assert` принимает логическое условие и определяет, пройден тест или нет.
+* `CubeCalculator.cube(3) === 27` проверяет, действительно ли вывод функции `cube` равен 27.
+ `===` является частью ScalaTest и предоставляет понятные сообщения об ошибках.
+
+## Добавление еще одного теста
+1. Добавьте еще один оператор `assert` после первого, который проверяет 0 в кубе.
+1. Перезапустите тест `CubeCalculatorTest`, кликнув правой кнопкой мыши и выбрав
+ **Run 'CubeCalculatorTest'**.
+
+## Заключение
+Вы видели один из способов тестирования Scala кода.
+Узнать больше о AnyFunSuite от ScalaTest можно на [официальном сайте](https://www.scalatest.org/getting_started_with_fun_suite).
+Вы также можете использовать другие тестовые фреймворки, такие, как [ScalaCheck](https://www.scalacheck.org/) и [Specs2](https://etorreborre.github.io/specs2/).
diff --git a/_ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md b/_ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md
new file mode 100644
index 0000000000..f404e3daf8
--- /dev/null
+++ b/_ru/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md
@@ -0,0 +1,111 @@
+---
+title: Начало работы со Scala и sbt в командной строке
+layout: singlepage-overview
+partof: getting-started-with-scala-and-sbt-on-the-command-line
+language: ru
+disqus: true
+next-page: /ru/testing-scala-with-sbt-on-the-command-line
+---
+
+В этом руководстве вы увидите, как создавать проекты Scala из шаблона.
+Это можно использовать как отправную точку для своих собственных проектов.
+Мы будем использовать [sbt](https://www.scala-sbt.org/1.x/docs/index.html), де-факто инструмент сборки для Scala.
+sbt компилирует, запускает и тестирует ваши проекты среди других связанных задач.
+Мы предполагаем, что вы знаете, как пользоваться терминалом.
+
+## Установка
+1. Убедитесь, что у вас установлена Java 8 JDK (также известная как 1.8)
+ * Запустите `javac -version` в командной строке и убедитесь, что выдается
+ `javac 1.8.___`
+ * Если у вас нет версии 1.8 или выше, [установите JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
+1. Установите sbt
+ * [Mac](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html)
+ * [Windows](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html)
+ * [Linux](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html)
+
+## Создание проекта
+
+{% tabs sbt-welcome-1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=sbt-welcome-1 %}
+
+1. `cd` в пустую папку.
+1. Запустите следующую команду `sbt new scala/hello-world.g8`.
+ Она извлекает шаблон 'hello-world' из GitHub.
+ Она также создаст папку `target`, которую пока можно игнорировать.
+1. При появлении запроса назовите приложение `hello-world`. Это создаст проект под названием "hello-world".
+1. Давайте взглянем на то, что только что было сгенерировано:
+
+{% endtab %}
+{% tab 'Scala 3' for=sbt-welcome-1 %}
+
+1. `cd` в пустую папку.
+1. Запустите следующую команду `sbt new scala/scala3.g8`.
+ Она извлекает шаблон 'scala3' из GitHub.
+ Она также создаст папку `target`, которую пока можно игнорировать.
+1. При появлении запроса назовите приложение `hello-world`. Это создаст проект под названием "hello-world".
+1. Давайте взглянем на то, что только что было сгенерировано:
+
+{% endtab %}
+{% endtabs %}
+
+
+```
+- hello-world
+ - project (sbt использует эту папку для установки и настройки плагинов и зависимостей)
+ - build.properties
+ - src
+ - main
+ - scala (весь Scala код находится в этой папке)
+ - Main.scala (точка входа в программу) <-- это все, что вам сейчас нужно
+ - build.sbt (файл определения сборки для sbt)
+```
+
+После того как вы создадите свой проект, sbt создаст дополнительные каталоги `target` для сгенерированных файлов.
+Вы можете игнорировать их.
+
+## Запуск проекта
+1. `cd` в `hello-world`.
+1. Запустите `sbt`. Эта команда запустит sbt console.
+1. Запустите `~run`. `~` опциональна и заставляет sbt перекомпилировать
+ и повторно запускать проект при каждом сохранении изменений в файле проекта
+ для быстрого цикла редактирование/запуск/отладка.
+ sbt также сгенерит директорию `target`, которую можно игнорировать.
+
+## Доработка кода
+1. Откройте файл `src/main/scala/Main.scala` в вашем любимом текстовом редакторе.
+1. Измените "Hello, World!" на "Hello, New York!"
+1. Если вы не остановили команду sbt, то должны увидеть "Hello, New York!", напечатанным в консоли.
+1. Вы можете продолжить вносить изменения и видеть результаты доработки в консоли.
+
+## Добавление зависимости
+Немного меняя тему, давайте посмотрим, как использовать опубликованные библиотеки
+для добавления дополнительных функций в наши приложения.
+
+1. Откройте `build.sbt` и добавьте следующую строку:
+
+```
+libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2"
+```
+Здесь `libraryDependencies` представляет набор зависимостей,
+и с помощью `+=` мы добавляем зависимость [scala-parser-combinators](https://github.com/scala/scala-parser-combinators)
+к набору зависимостей, которые sbt будет загружать при запуске.
+Теперь в любом файле Scala можно импортировать классы, объекты и т.д. из `scala-parser-combinators` с помощью обычного импорта.
+
+Вы можете найти больше опубликованных библиотек на [Scaladex](https://index.scala-lang.org/), каталоге библиотек Scala,
+где вы также можете скопировать указанную выше информацию о зависимостях для вставки в свой файл `build.sbt`.
+
+> **Примечание для Java библиотек:** Для обычной библиотеки Java следует использовать только один знак процента (`%`)
+> между названием организации и именем артефакта. Двойной процент (`%%`) — это специализация Scala библиотек.
+> Подробнее об этом можно узнать в [документации sbt][sbt-docs-lib-dependencies].
+
+## Следующие шаги
+
+Перейдите к следующему учебнику из серии _getting started with sbt_ и узнайте, как [тестировать Scala c sbt и ScalaTest в командной строке](testing-scala-with-sbt-on-the-command-line.html).
+
+**или**
+
+- Продолжайте изучать Scala в интерактивном режиме на
+ [Scala Exercises](https://www.scala-exercises.org/scala_tutorial).
+- Узнайте о возможностях Scala с помощью небольших статей, ознакомившись с нашим [туром по Scala]({{ site.baseurl }}/ru/tour/tour-of-scala.html).
+
+[sbt-docs-lib-dependencies]: https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Getting+the+right+Scala+version+with
diff --git a/_ru/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md b/_ru/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md
new file mode 100644
index 0000000000..a74aa92a19
--- /dev/null
+++ b/_ru/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md
@@ -0,0 +1,105 @@
+---
+title: Тестирование Scala c sbt и ScalaTest в командной строке
+layout: singlepage-overview
+partof: testing-scala-with-sbt-on-the-command-line
+language: ru
+disqus: true
+previous-page: /ru/getting-started-with-scala-and-sbt-on-the-command-line
+---
+
+Для Scala существует множество библиотек и методологий тестирования,
+но в этом руководстве мы продемонстрируем один популярный вариант из фреймворка ScalaTest
+под названием [AnyFunSuite](https://www.scalatest.org/getting_started_with_fun_suite).
+
+Это предполагает, что вы знаете, [как создать проект с sbt](getting-started-with-scala-and-sbt-on-the-command-line.html).
+
+## Настройка
+1. Используя командную строку создайте новую директорию.
+1. Перейдите (`cd`) в этот каталог и запустите `sbt new scala/scalatest-example.g8`.
+1. Назовите проект `ScalaTestTutorial`.
+1. Проект поставляется с зависимостью ScalaTest в файле `build.sbt`.
+1. Перейдите (`cd`) в этот каталог и запустите `sbt test`. Это запустит набор тестов
+`CubeCalculatorTest` с одним тестом под названием `CubeCalculator.cube`.
+
+```
+sbt test
+[info] Loading global plugins from /Users/username/.sbt/0.13/plugins
+[info] Loading project definition from /Users/username/workspace/sandbox/my-something-project/project
+[info] Set current project to scalatest-example (in build file:/Users/username/workspace/sandbox/my-something-project/)
+[info] CubeCalculatorTest:
+[info] - CubeCalculator.cube
+[info] Run completed in 267 milliseconds.
+[info] Total number of tests run: 1
+[info] Suites: completed 1, aborted 0
+[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0
+[info] All tests passed.
+[success] Total time: 1 s, completed Feb 2, 2017 7:37:31 PM
+```
+
+## Разбор кода
+1. Откройте два файла в текстовом редакторе:
+ * `src/main/scala/CubeCalculator.scala`
+ * `src/test/scala/CubeCalculatorTest.scala`
+1. В файле `CubeCalculator.scala` увидите определение функции `cube`.
+1. В файле `CubeCalculatorTest.scala` тестируемый класс, названный так же как и объект.
+
+```
+ import org.scalatest.funsuite.AnyFunSuite
+
+ class CubeCalculatorTest extends AnyFunSuite:
+ test("CubeCalculator.cube") {
+ assert(CubeCalculator.cube(3) === 27)
+ }
+```
+
+Давайте разберем код построчно:
+
+* `class CubeCalculatorTest` означает, что мы тестируем `CubeCalculator`
+* `extends AnyFunSuite` позволяет нам использовать функциональность класса AnyFunSuite из ScalaTest,
+ такую как функция `test`
+* `test` это функция из библиотеки FunSuite, которая собирает результаты проверок в теле функции.
+* `"CubeCalculator.cube"` - это имя для теста. Вы можете называть тест как угодно, но по соглашению используется имя — "ClassName.methodName".
+* `assert` принимает логическое условие и определяет, пройден тест или нет.
+* `CubeCalculator.cube(3) === 27` проверяет, действительно ли вывод функции `cube` равен 27.
+ `===` является частью ScalaTest и предоставляет понятные сообщения об ошибках.
+
+## Добавление еще одного теста
+1. Добавьте еще один тестовый блок с собственным оператором assert, который проверяет 0 в кубе.
+
+ ```
+ import org.scalatest.funsuite.AnyFunSuite
+
+ class CubeCalculatorTest extends AnyFunSuite {
+ test("CubeCalculator.cube 3 should be 27") {
+ assert(CubeCalculator.cube(3) === 27)
+ }
+
+ test("CubeCalculator.cube 0 should be 0") {
+ assert(CubeCalculator.cube(0) === 0)
+ }
+ }
+ ```
+
+1. Запустите `sbt test` еще раз, чтобы увидеть результаты.
+
+ ```
+ sbt test
+ [info] Loading project definition from C:\projects\scalaPlayground\scalatestpractice\project
+ [info] Loading settings for project root from build.sbt ...
+ [info] Set current project to scalatest-example (in build file:/C:/projects/scalaPlayground/scalatestpractice/)
+ [info] Compiling 1 Scala source to C:\projects\scalaPlayground\scalatestpractice\target\scala-2.13\test-classes ...
+ [info] CubeCalculatorTest:
+ [info] - CubeCalculator.cube 3 should be 27
+ [info] - CubeCalculator.cube 0 should be 0
+ [info] Run completed in 257 milliseconds.
+ [info] Total number of tests run: 2
+ [info] Suites: completed 1, aborted 0
+ [info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 0
+ [info] All tests passed.
+ [success] Total time: 3 s, completed Dec 4, 2019 10:34:04 PM
+ ```
+
+## Заключение
+Вы видели один из способов тестирования Scala кода.
+Узнать больше о AnyFunSuite от ScalaTest можно на [официальном сайте](https://www.scalatest.org/getting_started_with_fun_suite).
+Вы также можете использовать другие тестовые фреймворки, такие, как [ScalaCheck](https://www.scalacheck.org/) и [Specs2](https://etorreborre.github.io/specs2/).
diff --git a/_ru/index.md b/_ru/index.md
index b7678c8bfa..7ac8c2a455 100644
--- a/_ru/index.md
+++ b/_ru/index.md
@@ -1,42 +1,50 @@
---
-layout: inner-page-documentation
-title: Документация
+layout: landing-page
+title: Изучаем Scala
language: ru
partof: documentation
-discourse: true
-
-# Content masthead links
more-resources-label: Дополнительные Материалы
-sections:
- - title: "Для новичков"
+sections:
+ - title: "Первые шаги..."
links:
- - title: "Самое начало"
- description: "Установка Scala на ваш компьютер и написание пробного Scala кода!"
+ - title: "Приступая к работе"
+ description: "Установите Scala на свой компьютер и начните писать код на Scala!"
icon: "fa fa-rocket"
- link: /getting-started.html
+ link: /ru/getting-started/install-scala.html
- title: "Тур по Scala"
description: "Вступительный обзор по основным возможностям языка."
icon: "fa fa-flag"
link: /ru/tour/tour-of-scala.html
- - title: "для Java программистов"
- description: "Быстрое знакомство со Scala для тех кто уже знает Java."
- icon: "fa fa-coffee"
- link: /tutorials/scala-for-java-programmers.html
- more-resources:
+ - title: "Книга по Scala 3"
+ description: "Изучайте Scala используя серию коротких уроков."
+ icon: "fa fa-book-open"
+ link: /ru/scala3/book/introduction.html
+ - title: "Набор инструментов Scala"
+ description: "Отправка HTTP-запросов, запись файлов, запуск программ, обработка JSON..."
+ icon: "fa fa-toolbox"
+ link: /toolkit/introduction.html
- title: Онлайн Курсы, Упражнения и Блоги
- url: /learn.html
+ description: "Обучающие курсы по Scala от новичка до продвинутого уровня."
+ icon: "fa fa-cloud"
+ link: /online-courses.html
- title: Книги
- url: /books.html
+ description: "Напечатанные, а также электронные книги о Scala."
+ icon: "fa fa-book"
+ link: /books.html
+ - title: Уроки
+ description: "Пройдемся по серии коротких шагов по созданию Scala приложений."
+ icon: "fa fa-tasks"
+ link: /tutorials.html
- title: "Для опытных"
links:
- title: "API"
- description: "API документация для всех версий Scala."
- icon: "fa fa-file-text"
+ description: "Документация по API для каждой версии Scala."
+ icon: "fa fa-file-alt"
link: /api/all.html
- - title: "Обзоры"
- description: "Подробная документация, охватывающая возможности Scala."
+ - title: "Справочники"
+ description: "Подробные справочники по отдельным разделам языка."
icon: "fa fa-database"
link: /ru/overviews/index.html
- title: "Стилистика"
@@ -48,23 +56,49 @@ sections:
icon: "fa fa-list"
link: /ru/cheatsheets/index.html
- title: "Вопрос-Ответ"
- description: "Список по наиболее часто задаваемых вопросов с ответами по функционалу Scala"
+ description: "Список по наиболее часто задаваемым вопросам с ответами по функционалу Scala."
icon: "fa fa-question-circle"
link: /tutorials/FAQ/index.html
- - title: "Спецификация"
- description: "Официальная спецификация языка Scala"
+ - title: "Спецификация v2.x"
+ description: "Официальная спецификация языка Scala 2."
icon: "fa fa-book"
link: https://scala-lang.org/files/archive/spec/2.13/
+ - title: "Спецификация v3.x"
+ description: "Официальная спецификация языка Scala 3."
+ icon: "fa fa-book"
+ link: https://scala-lang.org/files/archive/spec/3.4/
+ - title: "Справочник по языку Scala 3"
+ description: "Справочник по языку Scala 3."
+ icon: "fa fa-book"
+ link: https://docs.scala-lang.org/scala3/reference
+
+ - title: "Исследуем Scala 3"
+ links:
+ - title: "Руководство по миграции"
+ description: "Руководство, которое поможет вам перейти от Scala 2 к Scala 3."
+ icon: "fa fa-suitcase"
+ link: /scala3/guides/migration/compatibility-intro.html
+ - title: "Новое в Scala 3"
+ description: "Обзор новой функциональности в Scala 3."
+ icon: "fa fa-star"
+ link: /ru/scala3/new-in-scala3.html
+ - title: "Новая функциональность Scaladoc для Scala 3"
+ description: "Ключевые особенности новой функциональности Scaladoc."
+ icon: "fa fa-star"
+ link: /ru/scala3/scaladoc.html
+ - title: "Выступления"
+ description: "Доступные онлайн выступления о Scala 3."
+ icon: "fa fa-play-circle"
+ link: /ru/scala3/talks.html
- title: "Развитие Scala"
links:
- - title: "SIPs"
- description: "Процесс улучшения Scala (Scala Improvement Process). Эволюция языка и компилятора."
+ - title: "Процесс улучшения Scala"
+ description: "Описание процесса развития языка и список всех предложений по улучшению Scala (SIP)."
icon: "fa fa-cogs"
link: /sips/index.html
- - title: "SPP"
- description: "Развитие платформы Scala. Развитие библиотек, движимое сообществом."
- icon: "fa fa-users"
- link: https://platform.scala-lang.org
-
+ - title: "Станьте участником развития Scala"
+ description: "От начала до конца: узнайте, как вы можете помочь открытой экосистеме Scala."
+ icon: "fa fa-code-branch"
+ link: /contribute/
---
diff --git a/_ru/online-courses.md b/_ru/online-courses.md
new file mode 100644
index 0000000000..2ec0c26bc9
--- /dev/null
+++ b/_ru/online-courses.md
@@ -0,0 +1,62 @@
+---
+title: Online ресурсы
+layout: singlepage-overview
+language: ru
+redirect-from:
+ - /learn.html
+---
+
+## Попробуй Scala в своем браузере!
+
+Существует несколько веб-сайтов, на которых вы можете интерактивно запускать код Scala в своем браузере!
+Взгляните на [Scastie](https://scastie.scala-lang.org/).
+
+## Онлайн-курсы от Scala Center
+
+[Scala Center](https://scala.epfl.ch) стремится создавать высококачественные и бесплатные онлайн-курсы
+для изучения Scala и функционального программирования.
+Уровни курса варьируются от начального до продвинутого.
+Более подробная информация доступна [на следующей странице]({% link scalacenter-courses.md %}).
+
+## Упражнения на языке Scala
+
+[Scala Exercises](https://www.scala-exercises.org/) — это серия уроков и упражнений, созданных [47 Degrees](https://www.47deg.com/).
+Это отличный способ получить краткое представление о Scala и одновременно проверить свои знания.
+
+[Tour of Scala](https://tourofscala.com) шаг за шагом знакомит вас со Scala, от новичка до эксперта.
+
+## Лекции доктора Mark C Lewis из Trinity University
+
+[Dr. Mark C Lewis](https://www.cs.trinity.edu/~mlewis/) из Университета Тринити, Сан-Антонио, Техас,
+преподает курсы программирования с использованием языка Scala.
+Видеокурсы доступны на YouTube бесплатно. Некоторые курсы ниже.
+
+- [Introduction to Programming and Problem Solving Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt9MIJ9DV4ps-_trOzWtphYO)
+- [Object-Orientation, Abstraction, and Data Structures Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt8JLumqKj-3BlHmEXPIfR42)
+
+Вы можете посетить его [YouTube канал](https://www.youtube.com/user/DrMarkCLewis/featured),
+чтобы найти больше видео.
+
+## Сообщество обучения Scala
+
+[Сообщество по изучению Scala в Discord](http://sca.la/learning-community) — растущее онлайн-сообщество,
+объединяющее учащихся с онлайн-ресурсами для совместного изучения Scala.
+
+## allaboutscala
+
+[allaboutscala](https://allaboutscala.com/) предоставляет подробные руководства для начинающих.
+
+## DevInsideYou
+
+[DevInsideYou](https://youtube.com/devinsideyou) — это YouTube канал с сотнями часов бесплатного контента Scala.
+
+## Rock the JVM
+
+[Rock the JVM](https://rockthejvm.com) — это учебная платформа с бесплатными и платными курсами
+по языку Scala, Akka, Cats Effect, ZIO, Apache Spark и другим инструментам экосистемы Scala.
+Он также содержит сотни [бесплатных видеоуроков](https://youtube.com/rockthejvm)
+и [статей](https://blog.rockthejvm.com) по различным темам, связанным со Scala.
+
+## Visual Scala Reference
+
+[Visual Scala Reference](https://superruzafa.github.io/visual-scala-reference/) — руководство по визуальному изучению концепций и функций Scala.
diff --git a/_ru/overviews/collections-2.13/arrays.md b/_ru/overviews/collections-2.13/arrays.md
index 7e71da1027..856c08002c 100644
--- a/_ru/overviews/collections-2.13/arrays.md
+++ b/_ru/overviews/collections-2.13/arrays.md
@@ -1,22 +1,16 @@
---
layout: multipage-overview
title: Массивы
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
num: 10
previous-page: concrete-mutable-collection-classes
next-page: strings
language: ru
-
---
[Массивы](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/Array.html) особый вид коллекций в Scala.
-С одной стороны, Scala массивы соответствуют массивам из Java. Например, Scala массив `Array[Int]` реализован в виде Java `int[]`, а `Array[Double]` как Java `double[]` и `Array[String]` как Java `String[]`
- С другой стороны, Scala массивы дают намного больше чем их Java аналоги. Во-первых Scala массивы могут быть обобщены (_generic_). То есть вы можете описать массив как `Array[T]`, где `T` дополнительный `параметр-тип` массива или же абстрактный тип.
+С одной стороны, Scala массивы соответствуют массивам из Java. Например, Scala массив `Array[Int]` реализован в виде Java `int[]`, а `Array[Double]` как Java `double[]` и `Array[String]` как Java `String[]`. С другой стороны, Scala массивы дают намного больше чем их Java аналоги. Во-первых, Scala массивы могут быть обобщены (_generic_). То есть вы можете описать массив как `Array[T]`, где `T` дополнительный `параметр-тип` массива или же абстрактный тип.
Во-вторых, Scala массивы совместимы со списками (`Seq`) Scala - вы можете передавать `Array[T]` на вход туда, где требуется `Seq[T]`. Ну и наконец, Scala массивы также поддерживают все операции, которые есть у списков. Вот пример:
scala> val a1 = Array(1, 2, 3)
@@ -28,7 +22,7 @@ language: ru
scala> a3.reverse
res0: Array[Int] = Array(9, 3)
-Учитывая то что Scala массивы соответствуют массивам из Java, каким же образом реализованы остальные дополнительные возможности массивов в Scala?
+Учитывая то, что Scala массивы соответствуют массивам из Java, каким же образом реализованы остальные дополнительные возможности массивов в Scala?
Реализация массивов в Scala постоянно использует неявные преобразования. В Scala массив не пытается _притворяться_ последовательностью. Он и не может, потому что тип данных лежащий в основе массива не является подтипом `Seq`. Вместо этого, используя "упаковывание", происходит неявное преобразование между массивами и экземплярами класса `scala.collection.mutable.ArraySeq`, который является подклассом `Seq`. Вот как это работает:
scala> val seq: collection.Seq[Int] = a1
@@ -55,7 +49,7 @@ language: ru
Вы видите, что вызов `reverse` на `seq`, который является `ArraySeq`, даст снова `ArraySeq`. Это логично, потому что массивы - это `Seqs`, и вызов `reverse` на любом `Seq` даст снова `Seq`. С другой стороны, вызов `reverse` на экземпляре класса `ArrayOps` даст значение `Array`, а не `Seq`.
-Пример `ArrayOps`, приведенный выше искусственный и используется лишь, чтоб показать разницу с `ArraySeq`. Обычно, вы никогда не создаете экземпляры класса `ArrayOps`. Вы просто вызываете методы `Seq` на массиве:
+Пример `ArrayOps`, приведенный выше искусственный и используется лишь, чтобы показать разницу с `ArraySeq`. Обычно, вы никогда не создаете экземпляры класса `ArrayOps`. Вы просто вызываете методы `Seq` на массиве:
scala> a1.reverse
res4: Array[Int] = Array(3, 2, 1)
@@ -67,7 +61,7 @@ language: ru
где `intArrayOps` - неявное преобразование, которое было вставлено ранее. В связи с этим возникает вопрос, как компилятор выбрал `intArrayOps` вместо другого неявного преобразования в `ArraySeq` в строке выше. В конце концов, оба преобразования преобразуют массив в тип, поддерживающий метод reverse. Ответ на этот вопрос заключается в том, что два неявных преобразования имеют приоритет. Преобразование `ArrayOps` имеет больший приоритет, чем преобразование `ArraySeq`. Первый определяется в объекте `Predef`, а второй - в классе `scala.LowPriorityImplicits`, который `Predef` наследует. Неявные преобразования в дочерних классах и дочерних объектах имеют более высокий приоритет над преобразованиями в базовых классах. Таким образом, если оба преобразования применимы, выбирается вариант в `Predef`. Очень похожая схема используется для строк.
-Итак, теперь вы знаете, как массивы могут быть совместимы с последовательностями и как они могут поддерживать все операции последовательностей. А как же обобщения? В Java нельзя написать `T[]`, где `T` является параметром типа. Как же представлен Scala `Array[T]`? На самом деле обобщенный массив типа `Array[T]` может быть любым из восьми примитивных типов массивов Java `byte[]`, `short[]`, `char[]`, `int[] `, `long[] `, `float[]`, `double ` или может быть массивом объектов. Единственным общим типом, включающим все эти типы, является `AnyRef` (или, равнозначно `java.lang.Object`), так что это тот тип в который компилятор Scala отобразит `Array[T]`. Во время исполнения, при обращении к элементу массива типа `Array[T]`, происходит последовательность проверок типов, которые определяют тип массива, за которыми следует подходящая операция на Java-массиве. Эти проверки типов замедляют работу массивов. Можно ожидать падения скорости доступа к обобщенным массивам в три-четыре раза, по сравнению с обычными массивами или массивами объектов. Это означает, что если вам нужна максимальная производительность, вам следует выбирать конкретные массивы, вместо обобщенных. Отображать обобщенный массив еще пол беды, нам нужен еще способ создания обобщенных массивов. Это куда более сложная задача, которая требует, от вас, небольшой помощи. Чтобы проиллюстрировать проблему, рассмотрим следующую попытку написания обобщенного метода, который создает массив.
+Итак, теперь вы знаете, как массивы могут быть совместимы с последовательностями и как они могут поддерживать все операции последовательностей. А как же обобщения? В Java нельзя написать `T[]`, где `T` является параметром типа. Как же представлен Scala `Array[T]`? На самом деле обобщенный массив типа `Array[T]` может быть любым из восьми примитивных типов массивов Java `byte[]`, `short[]`, `char[]`, `int[] `, `long[] `, `float[]`, `double ` или может быть массивом объектов. Единственным общим типом, включающим все эти типы, является `AnyRef` (или, равнозначно `java.lang.Object`), так что это тот тип, в который компилятор Scala отобразит `Array[T]`. Во время исполнения, при обращении к элементу массива типа `Array[T]`, происходит последовательность проверок типов, которые определяют тип массива, за которыми следует подходящая операция на Java-массиве. Эти проверки типов замедляют работу массивов. Можно ожидать падения скорости доступа к обобщенным массивам в три-четыре раза, по сравнению с обычными массивами или массивами объектов. Это означает, что если вам нужна максимальная производительность, вам следует выбирать конкретные массивы, вместо обобщенных. Отображать обобщенный массив еще полбеды, нам нужен еще способ создания обобщенных массивов. Это куда более сложная задача, которая требует от вас небольшой помощи. Чтобы проиллюстрировать проблему, рассмотрим следующую попытку написания обобщенного метода, который создает массив.
// это неправильно!
def evenElems[T](xs: Vector[T]): Array[T] = {
diff --git a/_ru/overviews/collections-2.13/concrete-immutable-collection-classes.md b/_ru/overviews/collections-2.13/concrete-immutable-collection-classes.md
index 6da8bcc3e1..e2f94e3455 100644
--- a/_ru/overviews/collections-2.13/concrete-immutable-collection-classes.md
+++ b/_ru/overviews/collections-2.13/concrete-immutable-collection-classes.md
@@ -1,18 +1,12 @@
---
layout: multipage-overview
title: Реализации Неизменяемых Коллекций
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
previous-page: maps
next-page: concrete-mutable-collection-classes
-
num: 8
language: ru
-
---
Scala предлагает множество конечных реализаций неизменяемых коллекций. Они отличаются реализуемыми трейтами (мапы (map), множества(set), последовательности(seq)), они могут быть бесконечными, и различаются производительностью операций. Вот некоторые из наиболее распространенных неизменяемых типов коллекций, используемых в Scala.
@@ -30,7 +24,7 @@ Scala предлагает множество конечных реализац
scala> val lazyList = 1 #:: 2 #:: 3 #:: LazyList.empty
lazyList: scala.collection.immutable.LazyList[Int] = LazyList(?)
-На первом месте в этом ленивом списке - 1, а на втором - 2 и 3. Но ни один из элементов здесь не выводится, потому что список еще не вычислен! Ленивые списки задуманны обрабатываться лениво, поэтому метод `toString`, не выводит всех элементов, не заставляя производить дополнительные вычисления.
+На первом месте в этом ленивом списке - 1, а на втором - 2 и 3. Но ни один из элементов здесь не выводится, потому что список еще не вычислен! Ленивые списки задуманы обрабатываться лениво, поэтому метод `toString` не выводит всех элементов, не заставляя производить дополнительные вычисления.
Ниже приводится более сложный пример. Вычисления ленивого списка, содержащего последовательность Фибоначчи, которая начинается с заданных двух чисел. Последовательность Фибоначчи - это последовательность, в которой каждый элемент представляет собой сумму двух предыдущих элементов в серии.
@@ -78,7 +72,7 @@ res27: scala.collection.immutable.ArraySeq[Int] = ArraySeq(1, 2, 3)
Как видно из последней строки выше, вызов `updated` не влияет на исходный ArraySeq `arr`.
-ArraySeqs хранят свои элементы в приватном [Массиве](arrays.html). Таким образом достигается компактное представление и обеспечивается быстрый индексированный доступ к элементам, но обновление или добавление одного элемента занимает линейное время, так как требует создания другого массива и копирования всех элементов исходного массива.
+ArraySeqs хранят свои элементы в приватном [Массиве]({% link _ru/overviews/collections-2.13/arrays.md %}). Таким образом достигается компактное представление и обеспечивается быстрый индексированный доступ к элементам, но обновление или добавление одного элемента занимает линейное время, так как требует создания другого массива и копирования всех элементов исходного массива.
## Вектора (Vectors)
@@ -86,7 +80,7 @@ ArraySeqs хранят свои элементы в приватном [Масс
[Вектор](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/Vector.html) - тип коллекции, который обеспечивает хорошую производительность для всех своих операций. Вектора позволяют получить доступ к любому элементу последовательности за "практически" постоянное время. Это значит что константа больше, чем при получении переднего (`head`) элемента списка или при чтения элемента из ArraySeq, но, тем не менее, это константа. Избегайте использование векторов в алгоритмах базирующихся на активной работе с передними (`head`) элементами. Вектора могут получать доступ к элементам и изменять их в произвольных местах, что делает разработку более простой и удобной.
-Вектора создаются и модифицируются также как и другие последовательности.
+Вектора создаются и модифицируются так же, как и другие последовательности.
scala> val vec = scala.collection.immutable.Vector.empty
vec: scala.collection.immutable.Vector[Nothing] = Vector()
@@ -97,10 +91,10 @@ ArraySeqs хранят свои элементы в приватном [Масс
scala> vec3(0)
res1: Int = 100
-Вектора представленны деревьями с высоким уровнем ветвления (уровень ветвления дерева или графа - это количество дочерних элементов у каждого узла). Каждый узел дерева содержит до 32х элементов вектора или содержит до 32х других узлов. Вектора с размером до 32х элементов могут быть представленны одним узлом. Вектора `32 * 32 = 1024` элементы могут быть представлены одним витком.
+Вектора представлены деревьями с высоким уровнем ветвления (уровень ветвления дерева или графа - это количество дочерних элементов у каждого узла). Каждый узел дерева содержит до 32х элементов вектора или содержит до 32х других узлов. Вектора с размером до 32х элементов могут быть представлены одним узлом. Вектора `32 * 32 = 1024` элементы могут быть представлены одним витком.
Для векторов с 215 элементами достаточно двух переходов от корня дерева до конечного элемента узла, трех переходов для векторов с 220 элементами, четырех переходов для 225 элементами и пяти переходов для 230 элементами. Таким образом, для всех векторов разумных размеров выбор элемента включает до 5 простых выборок массивов. Именно это мы подразумевали, когда писали, что доступ к элементам осуществляется с "практически постоянным временем".
-Также как и доступ к элементу, операция обновления в векторах занимает "практически" постоянное время. Добавление элемента в середину вектора может быть выполнено через копирование узла содержащего этот элемент и каждого ссылающегося на него узла, начиная от корня дерева. Это означает, что процесс обновления элемента создает от одного до пяти узлов, каждый из которых содержит до 32 элементов или поддеревьев. Это, конечно, дороже, чем просто обновление элемента в изменяемом массиве, но все же намного дешевле, чем копирование вообще всего вектора.
+Так же как и доступ к элементу, операция обновления в векторах занимает "практически" постоянное время. Добавление элемента в середину вектора может быть выполнено через копирование узла содержащего этот элемент и каждого ссылающегося на него узла, начиная от корня дерева. Это означает, что процесс обновления элемента создает от одного до пяти узлов, каждый из которых содержит до 32 элементов или поддеревьев. Это, конечно, дороже, чем просто обновление элемента в изменяемом массиве, но все же намного дешевле, чем копирование вообще всего вектора.
Поскольку вектора обладают хорошим балансом между быстрой случайной выборкой и быстрым случайным обновлением элементов, они используются в качестве реализации неизменяемых индексированных последовательностей:
@@ -157,7 +151,7 @@ ArraySeqs хранят свои элементы в приватном [Масс
Хэш деревья - это стандартный способ эффективного создания неизменяемых множеств и ассоциативных массивов (мап). [Compressed Hash-Array Mapped Prefix-trees](https://github.com/msteindorfer/oopsla15-artifact/) - это специальные хэш деревья для JVM, которые улучшают локальность и обеспечивают компактную и элегантную реализацию деревьев. Они базируются на классе [immutable.HashMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/immutable/HashMap.html). Их представление очень похоже на реализацию векторов, которые также являются деревьями, где каждый узел имеет либо 32 элемента либо 32 поддерева. Но в данном случае ключ выбирается на основе хэш-кода. Например, чтобы найти ключ на мапе, сначала берут хэш-код ключа. Затем самые младшие 5 бит хэш-кода используются для выбора первого поддерева, за которым следуют следующие 5 бит и так далее. Выбор прекращается, когда для всех битов будут найдены ключи.
-Хэш деревья пытаются предоставить разумный баланс между достаточно быстрым поиском и достаточно эффективными операциями вставки (`+`) и удаления (`-`) элементов. Именно поэтому они лежат в основе стандартных реализаций Scala неизменяемых множеств и ассоциативных массивов (мап). На самом деле, в Scala есть дополнительная оптимизацию для неизменяемых множеств и мап, которые содержат менее пяти элементов. Множества и мапы от одного до четырех элементов хранятся как обычные объекты, которые содержат только элементы (или пары ключ/значение в случае мапы) как поля. Пустое неизменяемое множество и пустая неизменяемая мапа - это всегда объект-сингэлтон - нет необходимости размножать сущности для них, потому что пустое неизменяемое множество или мапа всегда будут оставаться пустыми.
+Хэш деревья пытаются предоставить разумный баланс между достаточно быстрым поиском и достаточно эффективными операциями вставки (`+`) и удаления (`-`) элементов. Именно поэтому они лежат в основе стандартных реализаций Scala неизменяемых множеств и ассоциативных массивов (мап). На самом деле, в Scala есть дополнительная оптимизация для неизменяемых множеств и мап, которые содержат менее пяти элементов. Множества и мапы от одного до четырех элементов хранятся как обычные объекты, которые содержат только элементы (или пары ключ/значение в случае мапы) как поля. Пустое неизменяемое множество и пустая неизменяемая мапа - это всегда объект-сингэлтон - нет необходимости размножать сущности для них, потому что пустое неизменяемое множество или мапа всегда будут оставаться пустыми.
## Красно-Черные Деревья (Red-Black Trees)
diff --git a/_ru/overviews/collections-2.13/concrete-mutable-collection-classes.md b/_ru/overviews/collections-2.13/concrete-mutable-collection-classes.md
index 7152037ce9..1506db43ce 100644
--- a/_ru/overviews/collections-2.13/concrete-mutable-collection-classes.md
+++ b/_ru/overviews/collections-2.13/concrete-mutable-collection-classes.md
@@ -1,25 +1,19 @@
---
layout: multipage-overview
title: Реализации Изменяемых Коллекций
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
num: 9
previous-page: concrete-immutable-collection-classes
next-page: arrays
-
language: ru
-
---
Вы уже успели увидеть наиболее часто используемые неизменяемые типы коллекции, которые есть в стандартной библиотеке Scala. Настало время посмотреть на изменяемые (mutable) типы коллекции.
## Array Buffers
-[ArrayBuffer](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayBuffer.html) - буферизированный массив в своем буфере хранит массив и его размер. Большинство операций с буферизированным массивом выполняются с той же скоростью, что и с массивом, так как операции просто обращаются и изменяют исходный массив. Кроме того он может эффективно добавлять данные к своему концу. Присоединение элемента к такому массиву занимает амортизированное константное время. Поэтому буферизированные массивы будут полезны, если вы строите большую коллекцию данных регулярно добавляя новые элементы в конец.
+[ArrayBuffer](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArrayBuffer.html) - буферизированный массив в своем буфере хранит массив и его размер. Большинство операций с буферизированным массивом выполняются с той же скоростью, что и с массивом, так как операции просто обращаются и изменяют исходный массив. Кроме того, он может эффективно добавлять данные к своему концу. Присоединение элемента к такому массиву занимает амортизированное константное время. Поэтому буферизированные массивы будут полезны, если вы строите большую коллекцию данных регулярно добавляя новые элементы в конец.
scala> val buf = scala.collection.mutable.ArrayBuffer.empty[Int]
buf: scala.collection.mutable.ArrayBuffer[Int] = ArrayBuffer()
@@ -45,7 +39,7 @@ language: ru
## StringBuilders
-Так же, как буферизированный массив полезен для создания массивов, а буферизированный список полезен для построения списков, [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html) полезен для создания строк. StringBuilders настолько широко используются, что они уже импортированы по умолчанию в стандартную область видимости. Можете создать их с помощью `new StringBuilder`, как в следующем примере:
+Так же как буферизированный массив полезен для создания массивов, а буферизированный список полезен для построения списков, [StringBuilder](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/StringBuilder.html) полезен для создания строк. StringBuilders настолько широко используются, что они уже импортированы по умолчанию в стандартную область видимости. Можете создать их с помощью `new StringBuilder`, как в следующем примере:
scala> val buf = new StringBuilder
buf: StringBuilder =
@@ -108,7 +102,7 @@ Scala предоставляет не только неизменяемые, н
Последовательные массивы - это изменяемые массивы со свойствами последовательности фиксированного размера, которые хранят свои элементы внутри `Array[Object]`. Они реализованы в Scala классом [ArraySeq](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/ArraySeq.html).
-Вам стоит использовать `ArraySeq`, если вам нужен массив из-за его показателей производительности, но вы дополнительно хотите использовать обобщеные экземпляры последовательности, в которых вы не знаете тип элементов и у которого нет `ClassTag` который будет предоставлен непосредственно во время исполнения. Эти аспекты рассматриваются в разделе [arrays]({{ site.baseurl }}/overviews/collections/arrays.html).
+Вам стоит использовать `ArraySeq`, если вам нужен массив из-за его показателей производительности, но вы дополнительно хотите использовать обобщеные экземпляры последовательности, в которых вы не знаете тип элементов и у которого нет `ClassTag` который будет предоставлен непосредственно во время исполнения. Эти аспекты рассматриваются в разделе [arrays]({% link _ru/overviews/collections-2.13/arrays.md %}).
## Hash Tables (Хэш Таблицы)
@@ -146,11 +140,11 @@ Scala предоставляет не только неизменяемые, н
| `m.replace(k, old, new)` |Заменяет значение, связанное с ключом `k` на `new`, если ранее оно было равно `old`. |
| `m.replace (k, v)` | Заменяет значение, связанное с ключом `k` на `v`, если ранее значение вообще существовало.|
-`concurrent.Map` это трейт в библиотеке коллекций Scala. В настоящее время он реализуется двумя способами. Первый - через Java мапу `java.util.concurrent.ConcurrentMap`, который может быть автоматически преобразован в Scala мапу с помощью [стандартного механизма преобразования Java/Scala коллекций]({{ site.baseurl }}/overviews/collections/conversions-between-java-and-scala-collections.html). Вторая реализация через [TrieMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/concurrent/TrieMap.html), которая представляет из себя не блокируемую хэш-таблицу привязанную к дереву.
+`concurrent.Map` это трейт в библиотеке коллекций Scala. В настоящее время он реализуется двумя способами. Первый - через Java мапу `java.util.concurrent.ConcurrentMap`, который может быть автоматически преобразован в Scala мапу с помощью [стандартного механизма преобразования Java/Scala коллекций]({% link _ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md %}). Вторая реализация через [TrieMap](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/concurrent/TrieMap.html), которая представляет из себя не блокируемую хэш-таблицу привязанную к дереву.
## Mutable Bitsets (Изменяемый Битовый Набор)
-Изменяемый набор типа [mutable.BitSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/BitSet.html) практически такойже как и неизменяемый набор, за исключением того, что он при изменении сам меняется. Изменяемые битовые наборы немного эффективнее при обновлении, чем неизменяемые, так как им не нужно копировать `Long`, которые не изменились.
+Изменяемый набор типа [mutable.BitSet](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/mutable/BitSet.html) практически такой же, как и неизменяемый набор, за исключением того, что он при изменении сам меняется. Изменяемые битовые наборы немного эффективнее при обновлении, чем неизменяемые, так как им не нужно копировать `Long`, которые не изменились.
scala> val bits = scala.collection.mutable.BitSet.empty
bits: scala.collection.mutable.BitSet = BitSet()
diff --git a/_ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md b/_ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md
index 2471e0121f..0320c0c59d 100644
--- a/_ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md
+++ b/_ru/overviews/collections-2.13/conversions-between-java-and-scala-collections.md
@@ -1,17 +1,11 @@
---
layout: multipage-overview
title: Преобразования между Java и Scala коллекциями
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
num: 17
previous-page: creating-collections-from-scratch
-
language: ru
-
---
Как и в Scala, в Java есть богатая библиотека коллекций. Между ними много общего. Например, обе библиотеки предоставляют итераторы, итерируемые сущности, множества, мапы и списки. Но есть и серьезные различия. В частности, библиотека Scala фокусируют больше внимания на неизменяемых коллекциях, предоставляя больше возможностей для преобразования исходной коллекции в новую.
diff --git a/_ru/overviews/collections-2.13/creating-collections-from-scratch.md b/_ru/overviews/collections-2.13/creating-collections-from-scratch.md
index 1eacea990f..5956c8e4a2 100644
--- a/_ru/overviews/collections-2.13/creating-collections-from-scratch.md
+++ b/_ru/overviews/collections-2.13/creating-collections-from-scratch.md
@@ -1,18 +1,12 @@
---
layout: multipage-overview
title: Создание коллекций с нуля
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
num: 16
previous-page: iterators
next-page: conversions-between-java-and-scala-collections
-
language: ru
-
---
У вас есть синтаксис `List(1, 2, 3)` для создания списка из трех целых чисел и `Map('A' -> 1, 'C' -> 2)` для создания мапы с двумя элементами. На самом деле, это универсальная функциональность коллекций Scala. Можно получить любую коллекцию написав ее название и указав следом список элементов в круглых скобках. В результате получится новая коллекция с заданными элементами. Вот еще несколько примеров:
@@ -55,7 +49,7 @@ language: ru
| `C.empty` | Пустая коллекция. |
| `C(x, y, z)` | Коллекция состоящая из элементов `x, y, z`. |
| `C.concat(xs, ys, zs)` | Коллекция, полученная путем объединения элементов `xs, ys, zs`. |
-| `C.fill(n){e}` | Коллекция длины `n`, где каждый элемент вычисляется выражением`e`. |
+| `C.fill(n){e}` | Коллекция длины `n`, где каждый элемент вычисляется выражением `e`. |
| `C.fill(m, n){e}` | Коллекция коллекций размерности `m×n`, где каждый элемент вычисляется выражением `e`. (существует и в более высоких измерениях). |
| `C.tabulate(n){f}` | Коллекция длины `n`, где элемент каждого индекса i вычисляется с помощью `f(i)`. |
| `C.tabulate(m, n){f}` | Коллекция коллекций измерений `m×n`, где элемент каждого индекса `(i, j)` вычисляется с помощью `f(i, j)`. (существует также в более высоких измерениях). |
diff --git a/_ru/overviews/collections-2.13/equality.md b/_ru/overviews/collections-2.13/equality.md
index 5908d1ca2b..e05ee5ee73 100644
--- a/_ru/overviews/collections-2.13/equality.md
+++ b/_ru/overviews/collections-2.13/equality.md
@@ -1,21 +1,15 @@
---
layout: multipage-overview
title: Равенство
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
num: 13
previous-page: performance-characteristics
next-page: views
-
language: ru
-
---
-Коллекций придерживаются единого подхода к определению равенства и получению хэшей. Идея состоит, во-первых, в том, чтобы разделить коллекции на группы: множества, мапы и последовательности. Коллекции в разных группах всегда различаются. Например, `Set(1,2,3)` неравнозначен списку `List(1,2,3)`, хотя они содержат одни и те же элементы. С другой стороны, в рамках одной и той же группы коллекции равны тогда и только тогда, когда они имеют одинаковые элементы (для последовательностей: одни и те же элементы в одном порядке). Например `List(1, 2, 3) == Vector(1, 2, 3)`, и `HashSet(1, 2) == TreeSet(2, 1)`.
+Коллекции придерживаются единого подхода к определению равенства и получению хэшей. Идея состоит, во-первых, в том, чтобы разделить коллекции на группы: множества, мапы и последовательности. Коллекции в разных группах всегда различаются. Например, `Set(1,2,3)` неравнозначен списку `List(1,2,3)`, хотя они содержат одни и те же элементы. С другой стороны, в рамках одной и той же группы коллекции равны тогда и только тогда, когда они имеют одинаковые элементы (для последовательностей: одни и те же элементы в одном порядке). Например `List(1, 2, 3) == Vector(1, 2, 3)`, и `HashSet(1, 2) == TreeSet(2, 1)`.
Для проверки на равенство не важно, является ли коллекция изменяемой или неизменяемой. Для изменяемой коллекции достаточно просто рассмотреть ее текущие элементы на момент проведения проверки на равенство. Это означает, что коллекция в разные моменты может быть эквивалентна разным коллекциям, в зависимости от того, какие элементы в неё добавляются или удаляются. В этом кроится потенциальная опасность при использовании изменяемой коллекции в качестве ключа для хэшмапы. Пример:
diff --git a/_ru/overviews/collections-2.13/introduction.md b/_ru/overviews/collections-2.13/introduction.md
index c965ef979e..e97c142eb8 100644
--- a/_ru/overviews/collections-2.13/introduction.md
+++ b/_ru/overviews/collections-2.13/introduction.md
@@ -1,17 +1,11 @@
---
layout: multipage-overview
title: Введение
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
num: 1
next-page: overview
-
language: ru
-
---
**Martin Odersky и Lex Spoon**
diff --git a/_ru/overviews/collections-2.13/iterators.md b/_ru/overviews/collections-2.13/iterators.md
index ee7c02c50d..3d43d76a8f 100644
--- a/_ru/overviews/collections-2.13/iterators.md
+++ b/_ru/overviews/collections-2.13/iterators.md
@@ -1,18 +1,12 @@
---
layout: multipage-overview
title: Итераторы
-
-discourse: true
-
partof: collections-213
overview-name: Collections
-
num: 15
previous-page: views
next-page: creating-collections-from-scratch
-
language: ru
-
---
Итератор (Iterator) - это не коллекция, а скорее способ поочередного доступа к элементам коллекции. Есть две основные операции у итератора - это `next` и `hasNext`. Вызов метода `it.next()` на итераторе `it` вернет следующий элемент и изменит его состояние. Повторный вызов `next` на том же итераторе выведит следующий элемент идущий после ранее возвращённого. Если больше нет элементов для возврата, вызов команды `next` кинет исключение `NoSuchElementException`. Вы можете узнать, есть ли еще элементы для возврата с помощью метода `hasNext` у [Итератора](https://www.scala-lang.org/api/{{ site.scala-version }}/scala/collection/Iterator.html).
@@ -62,8 +56,8 @@ language: ru
Обратите внимание еще раз, что сам итератор`it` был изменен вызовом `dropWhile`: теперь он указывает на второе слово `number` в списке.
Фактически, `it` и результат `res4` возвращаемый после`dropWhile` возвращают одну и туже последовательность элементов.
-Чтоб избежать такое поведение, как вариант можно использовать `duplicate` (дублировать используемый итератор), вызывая методы на разных итераторах.
-Каждый из _двух_ итераторов будет обрабатывать точно такие же элементы, как и тот из которого состоит итераторатор `it`:
+Чтобы избежать такое поведение, как вариант можно использовать `duplicate` (дублировать используемый итератор), вызывая методы на разных итераторах.
+Каждый из _двух_ итераторов будет обрабатывать точно такие же элементы, как и тот, из которого состоит итераторатор `it`:
scala> val (words, ns) = Iterator("a", "number", "of", "words").duplicate
words: Iterator[String] = 
]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png)
+[]({{ site.baseurl }}/resources/images/parallel-collections-hierarchy.png)
diff --git a/_ru/overviews/parallel-collections/concrete-parallel-collections.md b/_ru/overviews/parallel-collections/concrete-parallel-collections.md index ab41a576c7..1bda571a82 100644 --- a/_ru/overviews/parallel-collections/concrete-parallel-collections.md +++ b/_ru/overviews/parallel-collections/concrete-parallel-collections.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Конкретные классы параллельных коллекций - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 2 --- @@ -47,10 +43,10 @@ num: 2 [ParRange](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/parallel/immutable/ParRange.html) представляет собой упорядоченную последовательность элементов, отстоящих друг от друга на одинаковые промежутки. Параллельный диапазон создается подобно последовательному [Range](https://www.scala-lang.org/api/{{ site.scala-212-version }}/scala/collection/immutable/Range.html): - scala> 1 to 3 par + scala> (1 to 3).par res0: scala.collection.parallel.immutable.ParRange = ParRange(1, 2, 3) - scala> 15 to 5 by -2 par + scala> (15 to 5 by -2).par res1: scala.collection.parallel.immutable.ParRange = ParRange(15, 13, 11, 9, 7, 5) Подобно тому, как последовательные диапазоны не имеют строителей, параллельные диапазоны не имеют [компоновщиков]({{ site.baseurl }}/ru/overviews/parallel-collections/architecture.html). При создании отображения (mapping) элементов параллельного диапазона получается параллельный вектор. Последовательные и параллельные диапазоны могут эффективно преобразовываться друг в друга вызовами методов `seq` и `par`. @@ -76,7 +72,7 @@ num: 2 scala> val phs = scala.collection.parallel.immutable.ParHashSet(1 until 1000: _*) phs: scala.collection.parallel.immutable.ParHashSet[Int] = ParSet(645, 892, 69, 809, 629, 365, 138, 760, 101, 479,... - scala> phs map { x => x * x } sum + scala> phs.map(x => x * x).sum res0: Int = 332833500 [Компоновщики]({{ site.baseurl }}/overviews/parallel-collections/architecture.html) параллельных хэш-деревьев действуют аналогично компоновщикам хэш-таблиц, а именно предварительно распределяют элементы по блокам, а после этого параллельно составляют результирующее хэш-дерево, назначая обработку различных блоков разным процессорам, каждый из которых независимо собирает свое поддерево. @@ -92,19 +88,19 @@ num: 2 scala> while (numbers.nonEmpty) { | numbers foreach { case (num, sqrt) => - | val nsqrt = 0.5 * (sqrt + num / sqrt) - | numbers(num) = nsqrt - | if (math.abs(nsqrt - sqrt) < 0.01) { - | println(num, nsqrt) - | numbers.remove(num) - | } - | } - | } - (1.0,1.0) + | val nsqrt = 0.5 * (sqrt + num / sqrt) + | numbers(num) = nsqrt + | if (math.abs(nsqrt - sqrt) < 0.01) { + | println(num, nsqrt) + | numbers.remove(num) + | } + | } + | } + (1.0,1.0) (2.0,1.4142156862745097) (7.0,2.64576704419029) (4.0,2.0000000929222947) - ... + ... [Компоновщики]({{ site.baseurl }}/ru/overviews/parallel-collections/architecture.html) реализованы как `TrieMap`-- так как эта структура является многопоточной, при вызове метода трансформации создается только один компоновщик, разделяемый всеми процессорами. @@ -114,53 +110,52 @@ num: 2 Характеристики производительности последовательных типов (sequence types): -| | head | tail | apply | update| prepend | append | insert | -| -------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- | -| `ParArray` | C | L | C | C | L | L | L | -| `ParVector` | eC | eC | eC | eC | eC | eC | - | -| `ParRange` | C | C | C | - | - | - | - | +| | head | tail | apply | update | prepend | append | insert | +| ----------- | ---- | ---- | ----- | ------ | ------- | ------ | ------ | +| `ParArray` | C | L | C | C | L | L | L | +| `ParVector` | eC | eC | eC | eC | eC | eC | - | +| `ParRange` | C | C | C | - | - | - | - | Характеристики производительности множеств (set) и ассоциативных массивов (map): -| | lookup | add | remove | -| -------- | ---- | ---- | ---- | -| **неизменяемые** | | | | -| `ParHashSet`/`ParHashMap`| eC | eC | eC | -| **изменяемые** | | | | -| `ParHashSet`/`ParHashMap`| C | C | C | -| `ParTrieMap` | eC | eC | eC | - +| | lookup | add | remove | +| ------------------------- | ------ | --- | ------ | +| **неизменяемые** | | | | +| `ParHashSet`/`ParHashMap` | eC | eC | eC | +| **изменяемые** | | | | +| `ParHashSet`/`ParHashMap` | C | C | C | +| `ParTrieMap` | eC | eC | eC | ### Расшифровка Обозначения в двух представленных выше таблицах означают следующее: -| | | -| --- | ---- | -| **C** | Операция (быстрая) выполняется за постоянное время. | -| **eC** | Операция выполняется за фактически постоянное время, но только при соблюдении некоторых предположений, например о максимальной длине вектора или распределении хэш-кодов.| +| | | +| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **C** | Операция (быстрая) выполняется за постоянное время. | +| **eC** | Операция выполняется за фактически постоянное время, но только при соблюдении некоторых предположений, например о максимальной длине вектора или распределении хэш-кодов. | | **aC** | Операция выполняется за амортизированное постоянное время. Некоторые вызовы операции могут выполняться медленнее, но при подсчете времени выполнения большого количества операций выходит, что в среднем на операцию требуется постоянное время. | -| **Log** | Операция занимает время, пропорциональное логарифму размера коллекции. | -| **L** | Операция линейна, то есть занимает время, пропорциональное размеру коллекции. | -| **-** | Операция не поддерживается. | +| **Log** | Операция занимает время, пропорциональное логарифму размера коллекции. | +| **L** | Операция линейна, то есть занимает время, пропорциональное размеру коллекции. | +| **-** | Операция не поддерживается. | Первая таблица трактует последовательные типы-- изменяемые и неизменяемые-- в контексте выполнения следующих операций: -| | | -| --- | ---- | -| **head** | Получение первого элемента последовательности. | -| **tail** | Получение новой последовательности, состоящей из всех элементов исходной, кроме первого. | -| **apply** | Индексирование. | -| **update** | Функциональное обновление (с помощью `updated`) для неизменяемых последовательностей, обновление с побочными действиями (с помощью `update`) для изменяемых. | -| **prepend**| Добавление элемента в начало последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | -| **append** | Добавление элемента в конец последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | -| **insert** | Вставка элемента в выбранную позицию последовательности. Поддерживается только изменяемыми последовательностями. | +| | | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **head** | Получение первого элемента последовательности. | +| **tail** | Получение новой последовательности, состоящей из всех элементов исходной, кроме первого. | +| **apply** | Индексирование. | +| **update** | Функциональное обновление (с помощью `updated`) для неизменяемых последовательностей, обновление с побочными действиями (с помощью `update`) для изменяемых. | +| **prepend** | Добавление элемента в начало последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | +| **append** | Добавление элемента в конец последовательности. Для неизменяемых последовательностей создается новая последовательность, для изменяемых-- модифицируется существующая. | +| **insert** | Вставка элемента в выбранную позицию последовательности. Поддерживается только изменяемыми последовательностями. | Вторая таблица рассматривает изменяемые и неизменяемые множества и ассоциативные массивы в контексте следующих операций: -| | | -| --- | ---- | +| | | +| ---------- | ---------------------------------------------------------------------------------------------- | | **lookup** | Проверка принадлежности элемента множеству, или получение значения, ассоциированного с ключом. | -| **add** | Добавление нового элемента во множество или новой пары ключ/значение в ассоциативный массив. | -| **remove** | Удаление элемента из множества или ключа из ассоциативного массива. | -| **min** | Минимальный элемент множества или минимальный ключ ассоциативного массива. | +| **add** | Добавление нового элемента во множество или новой пары ключ/значение в ассоциативный массив. | +| **remove** | Удаление элемента из множества или ключа из ассоциативного массива. | +| **min** | Минимальный элемент множества или минимальный ключ ассоциативного массива. | diff --git a/_ru/overviews/parallel-collections/configuration.md b/_ru/overviews/parallel-collections/configuration.md index 5dbd2b1e38..253c4c30d5 100644 --- a/_ru/overviews/parallel-collections/configuration.md +++ b/_ru/overviews/parallel-collections/configuration.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Конфигурирование параллельных коллекций - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 7 --- diff --git a/_ru/overviews/parallel-collections/conversions.md b/_ru/overviews/parallel-collections/conversions.md index 114f2d8986..f001762841 100644 --- a/_ru/overviews/parallel-collections/conversions.md +++ b/_ru/overviews/parallel-collections/conversions.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Преобразования параллельных коллекций - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 3 --- diff --git a/_ru/overviews/parallel-collections/ctries.md b/_ru/overviews/parallel-collections/ctries.md index 9e52d407bf..640ac7e8b9 100644 --- a/_ru/overviews/parallel-collections/ctries.md +++ b/_ru/overviews/parallel-collections/ctries.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Многопоточные префиксные деревья - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 4 --- diff --git a/_ru/overviews/parallel-collections/custom-parallel-collections.md b/_ru/overviews/parallel-collections/custom-parallel-collections.md index 6fd6fa9f58..4dbcdf7e96 100644 --- a/_ru/overviews/parallel-collections/custom-parallel-collections.md +++ b/_ru/overviews/parallel-collections/custom-parallel-collections.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Создание пользовательской параллельной коллекции - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - language: ru num: 6 --- diff --git a/_ru/overviews/parallel-collections/overview.md b/_ru/overviews/parallel-collections/overview.md index 2d68d91d8d..e2b4bbcd7d 100644 --- a/_ru/overviews/parallel-collections/overview.md +++ b/_ru/overviews/parallel-collections/overview.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Обзор - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - num: 1 language: ru --- diff --git a/_ru/overviews/parallel-collections/performance.md b/_ru/overviews/parallel-collections/performance.md index b86e90bc2c..64e533e359 100644 --- a/_ru/overviews/parallel-collections/performance.md +++ b/_ru/overviews/parallel-collections/performance.md @@ -1,12 +1,8 @@ --- layout: multipage-overview title: Измерение производительности - -discourse: false - partof: parallel-collections overview-name: Parallel Collections - num: 8 language: ru --- diff --git a/_ru/scala3/book/ca-context-bounds.md b/_ru/scala3/book/ca-context-bounds.md new file mode 100644 index 0000000000..91c18c5101 --- /dev/null +++ b/_ru/scala3/book/ca-context-bounds.md @@ -0,0 +1,141 @@ +--- +layout: multipage-overview +title: Контекстные границы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлены контекстные границы в Scala 3. +language: ru +num: 62 +previous-page: ca-context-parameters +next-page: ca-given-imports +--- + +Во многих ситуациях имя [контекстного параметра]({% link _overviews/scala3-book/ca-context-parameters.md %}#context-parameters) +не нужно указывать явно, поскольку оно используется компилятором только в синтезированных аргументах для других параметров контекста. +В этом случае вам не нужно определять имя параметра, а можно просто указать тип. + +## Предыстория + +Например, рассмотрим метод `maxElement`, возвращающий максимальное значение в коллекции: + +{% tabs context-bounds-max-named-param class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +```scala +def maxElement[A](as: List[A])(implicit ord: Ord[A]): A = + as.reduceLeft(max(_, _)(ord)) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +def maxElement[A](as: List[A])(using ord: Ord[A]): A = + as.reduceLeft(max(_, _)(using ord)) +``` + +{% endtab %} + +{% endtabs %} + +Метод `maxElement` принимает _контекстный параметр_ типа `Ord[A]` только для того, +чтобы передать его в качестве аргумента методу `max`. + +Для полноты приведем определения `max` и `Ord` +(обратите внимание, что на практике мы будем использовать существующий метод `max` для `List`, +но мы создали этот пример для иллюстрации): + +{% tabs context-bounds-max-ord class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +```scala +/** Определяет, как сравнивать значения типа `A` */ +trait Ord[A] { + def greaterThan(a1: A, a2: A): Boolean +} + +/** Возвращает максимальное из двух значений */ +def max[A](a1: A, a2: A)(implicit ord: Ord[A]): A = + if (ord.greaterThan(a1, a2)) a1 else a2 +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +/** Определяет, как сравнивать значения типа `A` */ +trait Ord[A]: + def greaterThan(a1: A, a2: A): Boolean + +/** Возвращает максимальное из двух значений */ +def max[A](a1: A, a2: A)(using ord: Ord[A]): A = + if ord.greaterThan(a1, a2) then a1 else a2 +``` + +{% endtab %} + +{% endtabs %} + +Обратите внимание, что метод `max` принимает контекстный параметр типа `Ord[A]`, как и метод `maxElement`. + +## Пропуск контекстных аргументов + +Так как `ord` - это контекстный параметр в методе `max`, +компилятор может предоставить его для нас в реализации `maxElement` при вызове `max`: + +{% tabs context-bounds-context class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +```scala +def maxElement[A](as: List[A])(implicit ord: Ord[A]): A = + as.reduceLeft(max(_, _)) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +def maxElement[A](as: List[A])(using Ord[A]): A = + as.reduceLeft(max(_, _)) +``` + +Обратите внимание: поскольку нам не нужно явно передавать его методу `max`, +мы можем не указывать его имя в определении метода `maxElement`. +Это _анонимный параметр контекста_. + +{% endtab %} + +{% endtabs %} + +## Границы контекста + +Учитывая написанное выше, _привязка к контексту_ — это сокращенный синтаксис +для выражения шаблона "параметр контекста, применяемый к параметру типа". + +Используя привязку к контексту, метод `maxElement` можно записать следующим образом: + +{% tabs context-bounds-max-rewritten %} + +{% tab 'Scala 2 и 3' %} + +```scala +def maxElement[A: Ord](as: List[A]): A = + as.reduceLeft(max(_, _)) +``` + +{% endtab %} + +{% endtabs %} + +Привязка типа `: Ord` к параметру типа `A` метода или класса указывает на параметр контекста с типом `Ord[A]`. +Под капотом компилятор преобразует этот синтаксис в тот, который показан в разделе "Предыстория". + +Дополнительные сведения о границах контекста см. в разделе ["Что такое границы контекста?"]({% link _overviews/FAQ/index.md %}#what-are-context-bounds) раздел FAQ по Scala. diff --git a/_ru/scala3/book/ca-context-parameters.md b/_ru/scala3/book/ca-context-parameters.md new file mode 100644 index 0000000000..dc66f2fc98 --- /dev/null +++ b/_ru/scala3/book/ca-context-parameters.md @@ -0,0 +1,196 @@ +--- +layout: multipage-overview +title: Параметры контекста +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как объявлять параметры контекста и как компилятор выводит их на стороне вызова. +language: ru +num: 61 +previous-page: ca-extension-methods +next-page: ca-context-bounds +--- + +Scala предлагает две важные функции для контекстной абстракции: + +- **Параметры контекста** позволяют указать параметры, которые на стороне вызова могут быть опущены программистом + и должны автоматически предоставляться контекстом. +- **Экземпляры given** (в Scala 3) или **неявные определения** (в Scala 2) — это термины, + которые компилятор Scala может использовать для заполнения отсутствующих аргументов. + +## Параметры контекста + +При проектировании системы зачастую необходимо предоставлять контекстную информацию, +такую как конфигурация или настройки, различным компонентам вашей системы. +Одним из распространенных способов добиться этого является передача конфигурации +в качестве дополнительного аргумента методам. + +В следующем примере мы определяем кейс класс `Config` для моделирования некоторой конфигурации веб-сайта +и передаем ее в различных методах. + +{% tabs example %} +{% tab 'Scala 2 и 3' %} + +```scala +case class Config(port: Int, baseUrl: String) + +def renderWebsite(path: String, config: Config): String = + "" + renderWidget(List("cart"), config) + "" + +def renderWidget(items: List[String], config: Config): String = ??? + +val config = Config(8080, "docs.scala-lang.org") +renderWebsite("/home", config) +``` + +{% endtab %} +{% endtabs %} + +Предположим, что конфигурация не меняется на протяжении большей части нашей кодовой базы. +Передача `config` каждому вызову метода (например `renderWidget`) становится очень утомительной +и делает нашу программу более трудной для чтения, поскольку нам нужно игнорировать аргумент `config`. + +### Установка параметров как контекстных + +Мы можем пометить некоторые параметры наших методов как _контекстные_. + +{% tabs 'contextual-parameters' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def renderWebsite(path: String)(implicit config: Config): String = + "" + renderWidget(List("cart")) + "" + // ^ + // аргумент config больше не требуется + +def renderWidget(items: List[String])(implicit config: Config): String = ??? +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def renderWebsite(path: String)(using config: Config): String = + "" + renderWidget(List("cart")) + "" + // ^ + // аргумент config больше не требуется + +def renderWidget(items: List[String])(using config: Config): String = ??? +``` + +{% endtab %} +{% endtabs %} + +Начав секцию параметров с ключевого слова `using` в Scala 3 или `implicit` в Scala 2, мы сообщаем компилятору, +что на стороне вызова он должен автоматически найти аргумент с необходимым типом. +Таким образом, компилятор Scala выполняет **вывод термов**. + +При вызове `renderWidget(List("cart"))` компилятор Scala увидит, что в области видимости есть терм типа `Config` +(в нашем случае - `config`) и автоматически предоставит его для `renderWidget`. +Таким образом, программа эквивалентна приведенной выше. + +На самом деле, поскольку в реализации `renderWebsite` больше не нужно ссылаться на `config`, +мы можем даже опустить его имя в подписи в Scala 3: + +{% tabs 'anonymous' %} +{% tab 'Только в Scala 3' %} + +```scala +// нет необходимости придумывать имя параметра +// vvvvvvvvvvvvv +def renderWebsite(path: String)(using Config): String = + "" + renderWidget(List("cart")) + "" +``` + +{% endtab %} +{% endtabs %} + +В Scala 2 именовать неявные параметры по-прежнему необходимо. + +### Явное указание контекстных параметров + +Мы увидели, как _абстрагироваться_ от контекстных параметров +и что компилятор Scala может автоматически предоставлять нам аргументы. +Но как мы можем указать, какую конфигурацию использовать для нашего вызова `renderWebsite`? + +{% tabs 'explicit' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +Мы явно указываем значение аргумента, как если бы это был обычный аргумент: + +```scala +renderWebsite("/home")(config) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +Подобно тому, как мы указали наш раздел параметров с помощью `using`, +мы также можем явно указать контекстные параметры с помощью `using`: + +```scala +renderWebsite("/home")(using config) +``` + +{% endtab %} +{% endtabs %} + +Явное предоставление контекстных параметров может быть полезно, +когда у нас в области видимости есть несколько разных значений, +подходящих по типу, и мы хотим убедиться в корректности передачи параметра методу. + +Для всех остальных случаев, как мы увидим в следующем разделе, +есть еще один способ ввести контекстуальные значения в область видимости. + +## Экземпляры given (определения implicit в Scala 2) + +Мы видели, что можем явно передавать аргументы в качестве контекстных параметров. +Однако, если для определенного типа существует _единственное каноническое значение_, +есть другой предпочтительный способ сделать его доступным для компилятора Scala: +пометив его как `given` в Scala 3 или `implicit` в Scala 2. + +{% tabs 'instances' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +implicit val config: Config = Config(8080, "docs.scala-lang.org") +// ^^^^^^ +// это значение, которое выведет компилятор Scala +// в качестве аргумента контекстного параметра типа Config +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val config = Config(8080, "docs.scala-lang.org") + +// это тип, который мы хотим предоставить для канонического значения +// vvvvvv +given Config = config +// ^^^^^^ +// это значение, которое выведет компилятор Scala +// в качестве аргумента контекстного параметра типа Config +``` + +{% endtab %} +{% endtabs %} + +В приведенном выше примере мы указываем, что всякий раз, +когда в текущей области видимости опущен контекстный параметр типа `Config`, +компилятор должен вывести `config` в качестве аргумента. + +Определив каноническое значение для типа `Config`, +мы можем вызвать `renderWebsite` следующим образом: + +```scala +renderWebsite("/home") +// ^ +// снова без аргумента +``` + +Подробное руководство о том, где Scala ищет канонические значения, можно найти в [FAQ]({% link _overviews/FAQ/index.md %}#where-does-scala-look-for-implicits). + +[reference]: {{ site.scala3ref }}/overview.html +[blog-post]: /2020/11/06/explicit-term-inference-in-scala-3.html diff --git a/_ru/scala3/book/ca-contextual-abstractions-intro.md b/_ru/scala3/book/ca-contextual-abstractions-intro.md new file mode 100644 index 0000000000..eef3910c30 --- /dev/null +++ b/_ru/scala3/book/ca-contextual-abstractions-intro.md @@ -0,0 +1,96 @@ +--- +layout: multipage-overview +title: Контекстные абстракции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе представлено введение в концепцию контекстных абстракций Scala 3. +language: ru +num: 59 +previous-page: types-others +next-page: ca-extension-methods +--- + +## Предпосылка + +Контекстные абстракции — это способ абстрагироваться от контекста. +Они представляют собой единую парадигму с большим разнообразием вариантов использования, среди которых: + +- реализация тайп классов (_type classes_) +- установление контекста +- внедрение зависимости (_dependency injection_) +- выражение возможностей +- вычисление новых типов и доказательство взаимосвязей между ними + +В этом отношении Scala оказала влияние на другие языки. Например, трейты в Rust или protocol extensions Swift. +Предложения по дизайну также представлены для Kotlin в качестве разрешения зависимостей во время компиляции, +для C# в качестве Shapes и Extensions или для F# в качестве Traits. +Контекстные абстракции также являются общей особенностью средств доказательства теорем, таких как Coq или Agda. + +Несмотря на то, что в этих проектах используется разная терминология, +все они являются вариантами основной идеи вывода терминов (term inference): +учитывая тип, компилятор синтезирует "канонический" термин, который имеет этот тип. + +## Редизайн в Scala 3 + +В Scala 2 контекстные абстракции поддерживаются пометкой `implicit` определений (методов и значений) или параметров +(см. [Параметры контекста]({% link _overviews/scala3-book/ca-context-parameters.md %})). + +Scala 3 включает в себя переработку контекстных абстракций. +Хотя эти концепции постепенно "открывались" в Scala 2, теперь они хорошо известны и понятны, и редизайн использует эти знания. + +Дизайн Scala 3 фокусируется на **намерении**, а не на **механизме**. +Вместо того, чтобы предлагать одну очень мощную функцию имплицитов, +Scala 3 предлагает несколько функций, ориентированных на варианты использования: + +- **Расширение классов задним числом**. + В Scala 2 методы расширения должны были кодироваться с использованием [неявных преобразований][implicit-conversions] или [неявных классов]({% link _overviews/core/implicit-classes.md %}). + Напротив, в Scala 3 [методы расширения][extension-methods] теперь встроены непосредственно в язык, что приводит к улучшению сообщений об ошибках и улучшению вывода типов. + +- **Абстрагирование контекстной информации**. + [Предложения Using][givens] позволяют программистам абстрагироваться от информации, + которая доступна в контексте вызова и должна передаваться неявно. + В качестве улучшения по сравнению со Scala 2 подразумевается, что предложения using могут быть указаны по типу, + освобождая сигнатуры функций от имен переменных, на которые никогда не ссылаются явно. + +- **Предоставление экземпляров тайп-классов**. + [Given экземпляры][givens] позволяют программистам определять _каноническое значение_ определенного типа. + Это делает программирование с [тайп-классами][type-classes] более простым без утечек деталей реализации. + +- **Неявное преобразование одного типа в другой**. + Неявное преобразование было [переработано с нуля][implicit-conversions] как экземпляры тайп-класса `Conversion`. + +- **Контекстные абстракции высшего порядка**. + _Совершенно новая_ функция [контекстных функций][contextual-functions] делает контекстные абстракции объектами первого класса. + Они являются важным инструментом для авторов библиотек и позволяют выражать лаконичный DSL. + +- **Полезная обратная связь от компилятора**. + Если компилятор не может разрешить неявный параметр, теперь он предлагает [предложения по импорту](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html), которые могут решить проблему. + +## Преимущества + +Эти изменения в Scala 3 обеспечивают лучшее разделение вывода терминов от остального языка: + +- существует единственный способ определить данные +- существует единственный способ ввести неявные параметры и аргументы +- существует отдельный способ [импорта givens][given-imports], который не позволяет им прятаться в море обычного импорта +- существует единственный способ определить [неявное преобразование][implicit-conversions], которое четко обозначено как таковое и не требует специального синтаксиса + +К преимуществам этих изменений относятся: + +- новый дизайн позволяет избежать взаимодействия функций и делает язык более согласованным +- implicits становятся более легкими для изучения и более сложными для злоупотреблений +- значительно улучшается ясность 95% программ Scala, использующих implicits +- есть потенциал, чтобы сделать вывод термов однозначным способом, который также доступен и удобен. + +В этой главе в следующих разделах представлены многие из этих новых функций. + +[givens]: {% link _overviews/scala3-book/ca-context-parameters.md %} +[given-imports]: {% link _overviews/scala3-book/ca-given-imports.md %} +[implicit-conversions]: {% link _overviews/scala3-book/ca-implicit-conversions.md %} +[extension-methods]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[context-bounds]: {% link _overviews/scala3-book/ca-context-bounds.md %} +[type-classes]: {% link _overviews/scala3-book/ca-type-classes.md %} +[equality]: {% link _overviews/scala3-book/ca-multiversal-equality.md %} +[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html diff --git a/_ru/scala3/book/ca-extension-methods.md b/_ru/scala3/book/ca-extension-methods.md new file mode 100644 index 0000000000..6f530b141f --- /dev/null +++ b/_ru/scala3/book/ca-extension-methods.md @@ -0,0 +1,145 @@ +--- +layout: multipage-overview +title: Методы расширения +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлена работа методов расширения в Scala 3. +language: ru +num: 60 +previous-page: ca-contextual-abstractions-intro +next-page: ca-context-parameters +versionSpecific: true +--- + +В Scala 2 аналогичного результата можно добиться с помощью [неявных классов]({% link _overviews/core/implicit-classes.md %}). + +--- + +Методы расширения позволяют добавлять методы к типу после того, как он был определен, +т.е. они позволяют добавлять новые методы в закрытые классы. +Например, представьте, что кто-то создал класс `Circle`: + +{% tabs ext1 %} +{% tab 'Scala 2 и 3' %} + +```scala +case class Circle(x: Double, y: Double, radius: Double) +``` + +{% endtab %} +{% endtabs %} + +Теперь представим, что необходим метод `circumference`, но нет возможности изменить исходный код `Circle`. +До того как концепция вывода терминов была введена в языки программирования, +единственное, что можно было сделать, это написать метод в отдельном классе или объекте, подобном этому: + +{% tabs ext2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object CircleHelpers { + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object CircleHelpers: + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +``` + +{% endtab %} +{% endtabs %} + +Затем этот метод можно было использовать следующим образом: + +{% tabs ext3 %} +{% tab 'Scala 2 и 3' %} + +```scala +val aCircle = Circle(2, 3, 5) + +// без использования метода расширения +CircleHelpers.circumference(aCircle) +``` + +{% endtab %} +{% endtabs %} + +Но методы расширения позволяют создать метод `circumference` для работы с экземплярами `Circle`: + +{% tabs ext4 %} +{% tab 'Только в Scala 3' %} + +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 +``` + +{% endtab %} +{% endtabs %} + +В этом коде: + +- `Circle` — это тип, к которому будет добавлен метод расширения `circumference` +- Синтаксис `c: Circle` позволяет ссылаться на переменную `c` в методах расширения + +Затем в коде метод `circumference` можно использовать так же, как если бы он был изначально определен в классе `Circle`: + +{% tabs ext5 %} +{% tab 'Только в Scala 3' %} + +```scala +aCircle.circumference +``` + +{% endtab %} +{% endtabs %} + +### Импорт методов расширения + +Представим, что `circumference` определен в пакете `lib` - его можно импортировать с помощью + +{% tabs ext6 %} +{% tab 'Только в Scala 3' %} + +```scala +import lib.circumference + +aCircle.circumference +``` + +{% endtab %} +{% endtabs %} + +Если импорт отсутствует, то компилятор выводит подробное сообщение об ошибке, подсказывая возможный импорт, например так: + +```text +value circumference is not a member of Circle, but could be made available as an extension method. + +The following import might fix the problem: + + import lib.circumference +``` + +## Обсуждение + +Ключевое слово `extension` объявляет о намерении определить один или несколько методов расширения для типа, заключенного в круглые скобки. +Чтобы определить для типа несколько методов расширения, используется следующий синтаксис: + +{% tabs ext7 %} +{% tab 'Только в Scala 3' %} + +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` + +{% endtab %} +{% endtabs %} diff --git a/_ru/scala3/book/ca-given-imports.md b/_ru/scala3/book/ca-given-imports.md new file mode 100644 index 0000000000..41439a27be --- /dev/null +++ b/_ru/scala3/book/ca-given-imports.md @@ -0,0 +1,54 @@ +--- +layout: multipage-overview +title: Given импорты +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как работают операторы импорта 'given' в Scala 3. +language: ru +num: 63 +previous-page: ca-context-bounds +next-page: ca-type-classes +versionSpecific: true +--- + +Для большей ясности, откуда берутся данные в текущей области видимости, +для импорта экземпляров `given` используется специальная форма оператора `import`. +Базовая форма показана в этом примере: + +```scala +object A: + class TC + given tc: TC = ??? + def f(using TC) = ??? + +object B: + import A.* // импорт всех не-given элементов + import A.given // импорт экземпляров given +``` + +В этом коде предложение `import A.*` объекта `B` импортирует все элементы `A`, _кроме_ `given` экземпляра `tc`. +И наоборот, второй импорт, `import A.given`, импортирует _только_ экземпляр `given`. +Два предложения импорта также могут быть объединены в одно: + +```scala +object B: + import A.{given, *} +``` + +## Обсуждение + +Селектор с подстановочным знаком `*` помещает в область видимости все определения, кроме given-ов или расширений, +тогда как селектор `given` помещает в область видимости _все_ given-ы, включая те, которые являются результатом расширений. + +Эти правила имеют два основных преимущества: + +- понятнее, откуда берутся данные в текущей области видимости. + В частности, невозможно скрыть импортированные given-ы в длинном списке других импортов. +- есть возможность импортировать все given, не импортируя ничего другого. + Это важно, потому что given-ы могут быть анонимными, поэтому обычное использование именованного импорта нецелесообразно. + +Дополнительные примеры синтаксиса "import given" показаны в главе ["Пакеты и импорт"][imports]. + +[imports]: {% link _overviews/scala3-book/packaging-imports.md %} diff --git a/_ru/scala3/book/ca-implicit-conversions.md b/_ru/scala3/book/ca-implicit-conversions.md new file mode 100644 index 0000000000..f4703dc075 --- /dev/null +++ b/_ru/scala3/book/ca-implicit-conversions.md @@ -0,0 +1,236 @@ +--- +layout: multipage-overview +title: Неявное преобразование типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице демонстрируется, как реализовать неявное преобразование типов в Scala 3. +language: ru +num: 66 +previous-page: ca-multiversal-equality +next-page: ca-summary +--- + +Неявные преобразования — это мощная функция Scala, позволяющая пользователям предоставлять аргумент одного типа, +как если бы он был другого типа, чтобы избежать шаблонного преобразования. + +> Обратите внимание, что в Scala 2 неявные преобразования также использовались для предоставления дополнительных членов +> запечатанным классам (см. [Неявные классы]({% link _overviews/core/implicit-classes.md %})). +> В Scala 3 мы рекомендуем использовать эту функциональность, определяя методы расширения вместо неявных преобразований +> (хотя стандартная библиотека по-прежнему полагается на неявные преобразования по историческим причинам). + +## Пример + +Рассмотрим, например, метод `findUserById`, принимающий параметр типа `Long`: + +{% tabs implicit-conversions-1 %} +{% tab 'Scala 2 и 3' %} + +```scala +def findUserById(id: Long): Option[User] +``` + +{% endtab %} +{% endtabs %} + +Для краткости опустим определение типа `User` - это не имеет значения для нашего примера. + +В Scala есть возможность вызвать метод `findUserById` с аргументом типа `Int` вместо ожидаемого типа `Long`, +потому что аргумент будет неявно преобразован в тип `Long`: + +{% tabs implicit-conversions-2 %} +{% tab 'Scala 2 и 3' %} + +```scala +val id: Int = 42 +findUserById(id) // OK +``` + +{% endtab %} +{% endtabs %} + +Этот код не упадет с ошибкой компиляции “type mismatch: expected `Long`, found `Int`”, +потому что есть неявное преобразование, которое преобразует аргумент `id` в значение типа `Long`. + +## Детальное объяснение + +В этом разделе описывается, как определять и использовать неявные преобразования. + +### Определение неявного преобразования + +{% tabs implicit-conversions-3 class=tabs-scala-version %} + +{% tab 'Scala 2' %} + +В Scala 2 неявное преобразование из типа `S` в тип `T` определяется [неявным классом]({% link _overviews/core/implicit-classes.md %}) `T`, +который принимает один параметр конструктора типа `S`, [неявное значение]({% link _overviews/scala3-book/ca-context-parameters.md %}) +типа функции `S => T` или неявный метод, преобразуемый в значение этого типа. + +Например, следующий код определяет неявное преобразование из `Int` в `Long`: + +```scala +import scala.language.implicitConversions + +implicit def int2long(x: Int): Long = x.toLong +``` + +Это неявный метод, преобразуемый в значение типа `Int => Long`. + +См. раздел "Остерегайтесь силы неявных преобразований" ниже для объяснения пункта `import scala.language.implicitConversions` в начале. +{% endtab %} + +{% tab 'Scala 3' %} +В Scala 3 неявное преобразование типа `S` в тип `T` определяется [`given` экземпляром]({% link _overviews/scala3-book/ca-context-parameters.md %}) +типа `scala.Conversion[S, T]`. +Для совместимости со Scala 2 его также можно определить неявным методом (подробнее читайте во вкладке Scala 2). + +Например, этот код определяет неявное преобразование из `Int` в `Long`: + +```scala +given int2long: Conversion[Int, Long] with + def apply(x: Int): Long = x.toLong +``` + +Как и другие given определения, неявные преобразования могут быть анонимными: + +```scala +given Conversion[Int, Long] with + def apply(x: Int): Long = x.toLong +``` + +Используя псевдоним, это можно выразить более кратко: + +```scala +given Conversion[Int, Long] = (x: Int) => x.toLong +``` + +{% endtab %} + +{% endtabs %} + +### Использование неявного преобразования + +Неявные преобразования применяются в двух случаях: + +1. Если выражение `e` имеет тип `S` и `S` не соответствует ожидаемому типу выражения `T`. +2. В выборе `e.m` с `e` типа `S`, где `S` не определяет `m` + (для поддержки [методов расширения][extension methods] в стиле Scala-2). + +В первом случае ищется конверсия `c`, применимая к `e` и тип результата которой соответствует `T`. + +В примере выше, когда мы передаем аргумент `id` типа `Int` в метод `findUserById`, +вставляется неявное преобразование `int2long(id)`. + +Во втором случае ищется преобразование `c`, применимое к `e` и результат которого содержит элемент с именем `m`. + +Примером является сравнение двух строк `"foo" < "bar"`. +В этом случае `String` не имеет члена `<`, поэтому вставляется неявное преобразование `Predef.augmentString("foo") < "bar"` +(`scala.Predef` автоматически импортируется во все программы Scala.). + +### Как неявные преобразования становятся доступными? + +Когда компилятор ищет подходящие преобразования: + +- во-первых, он смотрит в текущую лексическую область + - неявные преобразования, определенные в текущей области или во внешних областях + - импортированные неявные преобразования + - неявные преобразования, импортированные с помощью импорта подстановочных знаков (только в Scala 2) +- затем он просматривает [сопутствующие объекты][companion objects], _связанные_ с типом аргумента `S` или ожидаемым типом `T`. + Сопутствующие объекты, связанные с типом `X`: + - сам объект-компаньон `X` + - сопутствующие объекты, связанные с любым из унаследованных типов `X` + - сопутствующие объекты, связанные с любым аргументом типа в `X` + - если `X` - это внутренний класс, внешние объекты, в которые он встроен + +Например, рассмотрим неявное преобразование `fromStringToUser`, определенное в объекте `Conversions`: + +{% tabs implicit-conversions-4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.language.implicitConversions + +object Conversions { + implicit def fromStringToUser(name: String): User = (name: String) => User(name) +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object Conversions: + given fromStringToUser: Conversion[String, User] = (name: String) => User(name) +``` + +{% endtab %} +{% endtabs %} + +Следующие операции импорта эквивалентно передают преобразование в область действия: + +{% tabs implicit-conversions-5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import Conversions.fromStringToUser +// или +import Conversions._ +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import Conversions.fromStringToUser +// или +import Conversions.given +// или +import Conversions.{given Conversion[String, User]} +``` + +Обратите внимание, что в Scala 3 импорт с подстановочными знаками (т.е. `import Conversions.*`) +не импортирует given определения. + +{% endtab %} +{% endtabs %} + +Во вводном примере преобразование из `Int` в `Long` не требует импорта, поскольку оно определено в объекте `Int`, +который является сопутствующим объектом типа `Int`. + +Дополнительная литература: +[Где Scala ищет неявные значения? (в Stackoverflow)](https://stackoverflow.com/a/5598107). + +### Остерегайтесь силы неявных преобразований + +{% tabs implicit-conversions-6 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +Поскольку неявные преобразования могут иметь подводные камни, если используются без разбора, +компилятор предупреждает при компиляции определения неявного преобразования. + +Чтобы отключить предупреждения, выполните одно из следующих действий: + +- Импорт `scala.language.implicitConversions` в область определения неявного преобразования +- Вызвать компилятор с командой `-language:implicitConversions` + +Предупреждение не выдается, когда компилятор применяет преобразование. +{% endtab %} +{% tab 'Scala 3' %} +Поскольку неявные преобразования могут иметь подводные камни, если они используются без разбора, +компилятор выдает предупреждение в двух случаях: + +- при компиляции определения неявного преобразования в стиле Scala 2. +- на стороне вызова, где given экземпляр `scala.Conversion` вставляется как конверсия. + +Чтобы отключить предупреждения, выполните одно из следующих действий: + +- Импортировать `scala.language.implicitConversions` в область: + - определения неявного преобразования в стиле Scala 2 + - стороны вызова, где given экземпляр `scala.Conversion` вставляется как конверсия. +- Вызвать компилятор с командой `-language:implicitConversions` + {% endtab %} + {% endtabs %} + +[extension methods]: {% link _overviews/scala3-book/ca-extension-methods.md %} +[companion objects]: {% link _overviews/scala3-book/domain-modeling-tools.md %}#companion-objects diff --git a/_ru/scala3/book/ca-multiversal-equality.md b/_ru/scala3/book/ca-multiversal-equality.md new file mode 100644 index 0000000000..19960bc97a --- /dev/null +++ b/_ru/scala3/book/ca-multiversal-equality.md @@ -0,0 +1,207 @@ +--- +layout: multipage-overview +title: Многостороннее равенство +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице демонстрируется, как реализовать многостороннее равенство в Scala 3. +language: ru +num: 65 +previous-page: ca-type-classes +next-page: ca-implicit-conversions +versionSpecific: true +--- + +Раньше в Scala было _универсальное равенство_ (_universal equality_): +два значения любых типов можно было сравнивать друг с другом с помощью `==` и `!=`. +Это произошло из-за того факта, что `==` и `!=` реализованы в терминах метода `equals` Java, +который также может сравнивать значения любых двух ссылочных типов. + +Универсальное равенство удобно, но оно также опасно, поскольку подрывает безопасность типов. +Например, предположим, что после некоторого рефакторинга осталась ошибочная программа, +в которой значение `y` имеет тип `S` вместо правильного типа `T`: + +```scala +val x = ... // типа T +val y = ... // типа S, но должно быть типа T +x == y // результат проверки типов всегда будет false +``` + +Если `y` сравнивается с другими значениями типа `T`, программа все равно будет проверять тип, +так как значения всех типов можно сравнивать друг с другом. +Но это, вероятно, даст неожиданные результаты и завершится ошибкой во время выполнения. + +Типобезопасный язык программирования может работать лучше, а многостороннее равенство — +это дополнительный способ сделать универсальное равенство более безопасным. +Он использует класс двоичного типа `CanEqual`, чтобы указать, что значения двух заданных типов можно сравнивать друг с другом. + +## Разрешение сравнения экземпляров класса + +По умолчанию в Scala 3 все ещё можно сравнивать на равенство следующим образом: + +```scala +case class Cat(name: String) +case class Dog(name: String) +val d = Dog("Fido") +val c = Cat("Morris") + +d == c // false, но он компилируется +``` + +Но в Scala 3 такие сравнения можно отключить. +При (а) импорте `scala.language.strictEquality` или (б) использовании флага компилятора `-language:strictEquality` +это сравнение больше не компилируется: + +```scala +import scala.language.strictEquality + +val rover = Dog("Rover") +val fido = Dog("Fido") +println(rover == fido) // ошибка компиляции + +// сообщение об ошибке компиляции: +// Values of types Dog and Dog cannot be compared with == or != +``` + +## Включение сравнений + +Есть два способа включить сравнение с помощью класса типов `CanEqual`. +Для простых случаев класс может _выводиться_ (_derive_) от класса `CanEqual`: + +```scala +// Способ 1 +case class Dog(name: String) derives CanEqual +``` + +Как вы вскоре увидите, когда нужна большая гибкость, вы также можете использовать следующий синтаксис: + +```scala +// Способ 2 +case class Dog(name: String) +given CanEqual[Dog, Dog] = CanEqual.derived +``` + +Любой из этих двух подходов позволяет сравнивать экземпляры `Dog` друг с другом. + +## Более реалистичный пример + +В более реалистичном примере представим, что есть книжный интернет-магазин +и мы хотим разрешить или запретить сравнение бумажных, печатных и аудиокниг. +В Scala 3 для начала необходимо включить многостороннее равенство: + +```scala +// [1] добавить этот импорт или command line flag: -language:strictEquality +import scala.language.strictEquality +``` + +Затем создать объекты домена: + +```scala +// [2] создание иерархии классов +trait Book: + def author: String + def title: String + def year: Int + +case class PrintedBook( + author: String, + title: String, + year: Int, + pages: Int +) extends Book + +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book +``` + +Наконец, используем `CanEqual`, чтобы определить, какие сравнения необходимо разрешить: + +```scala +// [3] создайте экземпляры класса типов, чтобы определить разрешенные сравнения. +// разрешено `PrintedBook == PrintedBook` +// разрешено `AudioBook == AudioBook` +given CanEqual[PrintedBook, PrintedBook] = CanEqual.derived +given CanEqual[AudioBook, AudioBook] = CanEqual.derived + +// [4a] сравнение двух печатных книг разрешено +val p1 = PrintedBook("1984", "George Orwell", 1961, 328) +val p2 = PrintedBook("1984", "George Orwell", 1961, 328) +println(p1 == p2) // true + +// [4b] нельзя сравнивать печатную книгу и аудиокнигу +val pBook = PrintedBook("1984", "George Orwell", 1961, 328) +val aBook = AudioBook("1984", "George Orwell", 2006, 682) +println(pBook == aBook) // ошибка компиляции +``` + +Последняя строка кода приводит к следующему сообщению компилятора об ошибке: + +``` +Values of types PrintedBook and AudioBook cannot be compared with == or != +``` + +Вот как многостороннее равенство отлавливает недопустимые сравнения типов во время компиляции. + +### Включение “PrintedBook == AudioBook” + +Если есть необходимость разрешить сравнение "печатной книги" (`PrintedBook`) с аудио-книгой (`AudioBook`), +то достаточно создать следующие два дополнительных сравнения равенства: + +```scala +// разрешить `PrintedBook == AudioBook` и `AudioBook == PrintedBook` +given CanEqual[PrintedBook, AudioBook] = CanEqual.derived +given CanEqual[AudioBook, PrintedBook] = CanEqual.derived +``` + +Теперь можно сравнивать печатную книгу с аудио-книгой без ошибки компилятора: + +```scala +println(pBook == aBook) // false +println(aBook == pBook) // false +``` + +#### Внедрите "equals", чтобы они действительно работали + +Хотя эти сравнения теперь разрешены, они всегда будут ложными, +потому что их методы `equals` не знают, как проводить подобные сравнения. +Чтобы доработать сравнение, можно переопределить методы `equals` для каждого класса. +Например, если переопределить метод `equals` для `AudioBook`: + +```scala +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book: + // переопределить, чтобы разрешить сравнение AudioBook с PrintedBook + override def equals(that: Any): Boolean = that match + case a: AudioBook => + this.author == a.author + && this.title == a.title + && this.year == a.year + && this.lengthInMinutes == a.lengthInMinutes + case p: PrintedBook => + this.author == p.author && this.title == p.title + case _ => + false +``` + +Теперь можно сравнить `AudioBook` с `PrintedBook`: + +```scala +println(aBook == pBook) // true (работает из-за переопределенного `equals` в `AudioBook`) +println(pBook == aBook) // false +``` + +Книга `PrintedBook` не имеет метода `equals`, поэтому второе сравнение возвращает `false`. +Чтобы включить это сравнение, достаточно переопределить метод `equals` в `PrintedBook`. + +Вы можете найти дополнительную информацию о [многостороннем равенстве][ref-equal] в справочной документации. + +[ref-equal]: {{ site.scala3ref }}/contextual/multiversal-equality.html diff --git a/_ru/scala3/book/ca-summary.md b/_ru/scala3/book/ca-summary.md new file mode 100644 index 0000000000..f3b68b7211 --- /dev/null +++ b/_ru/scala3/book/ca-summary.md @@ -0,0 +1,38 @@ +--- +layout: multipage-overview +title: Обзор +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлен краткий обзор уроков по контекстуальным абстракциям. +language: ru +num: 67 +previous-page: ca-implicit-conversions +next-page: concurrency +--- + +В этой главе представлено введение в большинство тем контекстных абстракций, в том числе: + +- [Методы расширения](ca-extension-methods.html) +- [Экземпляры given и параметры контекста](ca-context-parameters.html) +- [Контекстные границы](ca-context-bounds.html) +- [Импорт given](ca-given-imports.html) +- [Классы типов](ca-type-classes.html) +- [Многостороннее равенство](ca-multiversal-equality.html) +- [Неявные преобразования](ca-implicit-conversions.html) + +Все эти функции являются вариантами основной идеи **вывода термов**: +учитывая тип, компилятор синтезирует “канонический” терм, который имеет этот тип. + +Несколько более сложных тем здесь не рассматриваются, в том числе: + +- Условные given экземпляры +- Вывод класса типов +- Контекстные функции +- Контекстные параметры по имени +- Связь с имплицитами Scala 2 + +Эти темы подробно обсуждаются в [справочной документации][ref]. + +[ref]: {{ site.scala3ref }}/contextual diff --git a/_ru/scala3/book/ca-type-classes.md b/_ru/scala3/book/ca-type-classes.md new file mode 100644 index 0000000000..5da4f9468f --- /dev/null +++ b/_ru/scala3/book/ca-type-classes.md @@ -0,0 +1,230 @@ +--- +layout: multipage-overview +title: Классы типов +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе демонстрируется создание и использование классов типов. +language: ru +num: 64 +previous-page: ca-given-imports +next-page: ca-multiversal-equality +--- + +Класс типов (_type class_) — это абстрактный параметризованный тип, +который позволяет добавлять новое поведение к любому закрытому типу данных без использования подтипов. +Если вы пришли с Java, то можно думать о классах типов как о чем-то вроде [`java.util.Comparator[T]`][comparator]. + +> В статье ["Type Classes as Objects and Implicits"][typeclasses-paper] (2010 г.) обсуждаются основные идеи, +> лежащие в основе классов типов в Scala. +> Несмотря на то, что в статье используется более старая версия Scala, идеи актуальны и по сей день. + +Этот стиль программирования полезен во многих случаях, например: + +- выражение того, как тип, которым вы не владеете, например, из стандартной или сторонней библиотеки, соответствует такому поведению +- добавление поведения к нескольким типам без введения отношений подтипов между этими типами (например, когда один расширяет другой) + +Классы типов — это трейты с одним или несколькими параметрами, +реализации которых предоставляются в виде экземпляров `given` в Scala 3 или `implicit` значений в Scala 2. + +## Пример + +Например, `Show` - хорошо известный класс типов в Haskell, и в следующем коде показан один из способов его реализации в Scala. +Если предположить, что классы Scala не содержат метода `toString`, то можно определить класс типов `Show`, +чтобы добавить это поведение к любому типу, который вы хотите преобразовать в пользовательскую строку. + +### Класс типов + +Первым шагом в создании класса типов является объявление параметризованного trait, содержащего один или несколько абстрактных методов. +Поскольку `Showable` содержит только один метод с именем `show`, он записывается так: + +{% tabs 'definition' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// класс типов +trait Showable[A] { + def show(a: A): String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// класс типов +trait Showable[A]: + extension (a: A) def show: String +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что этот подход близок к обычному объектно-ориентированному подходу, +когда обычно trait `Show` определяется следующим образом: + +{% tabs 'trait' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// a trait +trait Show { + def show: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// a trait +trait Show: + def show: String +``` + +{% endtab %} +{% endtabs %} + +Следует отметить несколько важных моментов: + +1. Классы типов, например, `Showable` принимают параметр типа `A`, чтобы указать, для какого типа мы предоставляем реализацию `show`; + в отличие от классических трейтов, наподобие `Show`. +2. Чтобы добавить функциональность `show` к определенному типу `A`, классический трейт требует наследования `A extends Show`, + в то время как для классов типов нам требуется реализация `Showable[A]`. +3. В Scala 3, чтобы разрешить один и тот же синтаксис вызова метода в обоих случаях `Showable`, + который имитирует синтаксис `Show`, мы определяем `Showable.show` как метод расширения. + +### Реализация конкретных экземпляров + +Следующий шаг — определить, какие классы `Showable` должны работать в вашем приложении, а затем реализовать для них это поведение. +Например, для реализации `Showable` следующего класса `Person`: + +{% tabs 'person' %} +{% tab 'Scala 2 и 3' %} + +```scala +case class Person(firstName: String, lastName: String) +``` + +{% endtab %} +{% endtabs %} + +необходимо определить одно _каноническое значение_ типа `Showable[Person]`, т.е. экземпляр `Showable` для типа `Person`, +как показано в следующем примере кода: + +{% tabs 'instance' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +implicit val showablePerson: Showable[Person] = new Showable[Person] { + def show(p: Person): String = + s"${p.firstName} ${p.lastName}" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +given Showable[Person] with + extension (p: Person) def show: String = + s"${p.firstName} ${p.lastName}" +``` + +{% endtab %} +{% endtabs %} + +### Использование класса типов + +Теперь вы можете использовать этот класс типов следующим образом: + +{% tabs 'usage' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val person = Person("John", "Doe") +println(showablePerson.show(person)) +``` + +Обратите внимание, что на практике классы типов обычно используются со значениями, тип которых неизвестен, +в отличие от type `Person`, как показано в следующем разделе. + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val person = Person("John", "Doe") +println(person.show) +``` + +{% endtab %} +{% endtabs %} + +Опять же, если бы в Scala не было метода `toString`, доступного для каждого класса, вы могли бы использовать эту технику, +чтобы добавить поведение `Showable` к любому классу, который вы хотите преобразовать в `String`. + +### Написание методов, использующих класс типов + +Как и в случае с наследованием, вы можете определить методы, которые используют `Showable` в качестве параметра типа: + +{% tabs 'method' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def showAll[A](as: List[A])(implicit showable: Showable[A]): Unit = + as.foreach(a => println(showable.show(a))) + +showAll(List(Person("Jane"), Person("Mary"))) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def showAll[A: Showable](as: List[A]): Unit = + as.foreach(a => println(a.show)) + +showAll(List(Person("Jane"), Person("Mary"))) +``` + +{% endtab %} +{% endtabs %} + +### Класс типов с несколькими методами + +Обратите внимание: если вы хотите создать класс типов с несколькими методами, исходный синтаксис выглядит следующим образом: + +{% tabs 'multiple-methods' class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasLegs[A] { + def walk(a: A): Unit + def run(a: A): Unit +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait HasLegs[A]: + extension (a: A) + def walk(): Unit + def run(): Unit +``` + +{% endtab %} +{% endtabs %} + +### Пример из реального мира + +В качестве примера из реального мира, как классы типов используются в Scala 3, +см. обсуждение `CanEqual` в [разделе Multiversal Equality][multiversal]. + +[typeclasses-paper]: https://infoscience.epfl.ch/record/150280/files/TypeClasses.pdf + +[typeclasses-chapter]: {% link _overviews/scala3-book/ca-type-classes.md %} +[comparator]: https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html +[multiversal]: {% link _overviews/scala3-book/ca-multiversal-equality.md %} diff --git a/_ru/scala3/book/collections-classes.md b/_ru/scala3/book/collections-classes.md new file mode 100644 index 0000000000..80fcf30248 --- /dev/null +++ b/_ru/scala3/book/collections-classes.md @@ -0,0 +1,971 @@ +--- +layout: multipage-overview +title: Типы коллекций +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице представлены общие типы коллекций Scala 3 и некоторые из их методов. +language: ru +num: 38 +previous-page: collections-intro +next-page: collections-methods +--- + + +На этой странице показаны общие коллекции Scala 3 и сопутствующие им методы. +Scala поставляется с большим количеством типов коллекций, на изучение которых может уйти время, +поэтому желательно начать с нескольких из них, а затем использовать остальные по мере необходимости. +Точно так же у каждого типа коллекции есть десятки методов, облегчающих разработку, +поэтому лучше начать изучение лишь с небольшого количества. + +В этом разделе представлены наиболее распространенные типы и методы коллекций, +которые вам понадобятся для начала работы. + +В конце этого раздела представлены дополнительные ссылки, для более глубокого изучения коллекций. + +## Три основные категории коллекций + +Для коллекций Scala можно выделить три основные категории: + +- **Последовательности** (**Sequences**/**Seq**) представляют собой последовательный набор элементов + и могут быть _индексированными_ (как массив) или _линейными_ (как связанный список) +- **Мапы** (**Maps**) содержат набор пар ключ/значение, например Java `Map`, Python dictionary или Ruby `Hash` +- **Множества** (**Sets**) — это неупорядоченный набор уникальных элементов + +Все они являются базовыми типами и имеют подтипы подходящие под конкретные задачи, +таких как параллелизм (concurrency), кэширование (caching) и потоковая передача (streaming). +В дополнение к этим трем основным категориям существуют и другие полезные типы коллекций, +включая диапазоны (ranges), стеки (stacks) и очереди (queues). + + +### Иерархия коллекций + +В качестве краткого обзора следующие три рисунка показывают иерархию классов и трейтов в коллекциях Scala. + +На первом рисунке показаны типы коллекций в пакете _scala.collection_. +Все это высокоуровневые абстрактные классы или трейты, которые обычно имеют _неизменяемые_ и _изменяемые_ реализации. + +![General collection hierarchy][collections1] + +На этом рисунке показаны все коллекции в пакете _scala.collection.immutable_: + +![Immutable collection hierarchy][collections2] + +А на этом рисунке показаны все коллекции в пакете _scala.collection.mutable_: + +![Mutable collection hierarchy][collections3] + +В следующих разделах представлены некоторые из распространенных типов. + +## Общие коллекции + +Основные коллекции, используемые чаще всего: + +| Тип коллекции | Неизменяемая | Изменяемая | Описание | +|----------------|--------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `List` | ✓ | | Линейная неизменяемая последовательность (связный список) | +| `Vector` | ✓ | | Индексированная неизменяемая последовательность | +| `LazyList` | ✓ | | Ленивый неизменяемый связанный список, элементы которого вычисляются только тогда, когда они необходимы; подходит для больших или бесконечных последовательностей. | +| `ArrayBuffer` | | ✓ | Подходящий тип для изменяемой индексированной последовательности | +| `ListBuffer` | | ✓ | Используется, когда вам нужен изменяемый список; обычно преобразуется в `List` | +| `Map` | ✓ | ✓ | Итерируемая коллекция, состоящая из пар ключей и значений | +| `Set` | ✓ | ✓ | Итерируемая коллекция без повторяющихся элементов | + +Как показано, `Map` и `Set` бывают как изменяемыми, так и неизменяемыми. + +Основы каждого типа демонстрируются в следующих разделах. + +> В Scala _буфер_ (_buffer_), такой как `ArrayBuffer` или `ListBuffer`, представляет собой последовательность, +> которая может увеличиваться и уменьшаться. + +### Примечание о неизменяемых коллекциях + +В последующих разделах всякий раз, когда используется слово _immutable_, можно с уверенностью сказать, +что тип предназначен для использования в стиле _функционального программирования_ (ФП). +С помощью таких типов коллекция не меняется, +а при вызове функциональных методов возвращается новый результат - новая коллекция. + +## Выбор последовательности + +При выборе _последовательности_ (последовательной коллекции элементов) нужно руководствоваться двумя основными вопросами: + +- должна ли последовательность индексироваться (как массив), обеспечивая быстрый доступ к любому элементу, + или она должна быть реализована как линейный связанный список? +- необходима изменяемая или неизменяемая коллекция? + +Рекомендуемые универсальные последовательности: + +| Тип\Категория | Неизменяемая | Изменяемая | +|-----------------------------|--------------|---------------| +| индексируемая | `Vector` | `ArrayBuffer` | +| линейная (связанный список) | `List` | `ListBuffer` | + +Например, если нужна неизменяемая индексированная коллекция, в общем случае следует использовать `Vector`. +И наоборот, если нужна изменяемая индексированная коллекция, используйте `ArrayBuffer`. + +> `List` и `Vector` часто используются при написании кода в функциональном стиле. +> `ArrayBuffer` обычно используется при написании кода в императивном стиле. +> `ListBuffer` используется тогда, когда стили смешиваются, например, при создании списка. + +Следующие несколько разделов кратко демонстрируют типы `List`, `Vector` и `ArrayBuffer`. + + +## `List` + +[List](https://www.scala-lang.org/api/current/scala/collection/immutable/List.html) +представляет собой линейную неизменяемую последовательность. +Каждый раз, когда в список добавляются или удаляются элементы, по сути создается новый список из существующего. + +### Создание списка + +`List` можно создать различными способами: + +{% tabs list-creation %} + +{% tab 'Scala 2 и 3' %} +```scala +val ints = List(1, 2, 3) +val names = List("Joel", "Chris", "Ed") + +// другой путь создания списка List +val namesAgain = "Joel" :: "Chris" :: "Ed" :: Nil +``` +{% endtab %} + +{% endtabs %} + +При желании тип списка можно объявить, хотя обычно в этом нет необходимости: + +{% tabs list-type %} + +{% tab 'Scala 2 и 3' %} +```scala +val ints: List[Int] = List(1, 2, 3) +val names: List[String] = List("Joel", "Chris", "Ed") +``` +{% endtab %} + +{% endtabs %} + +Одно исключение — когда в коллекции смешанные типы; в этом случае тип желательно указывать явно: + +{% tabs list-mixed-types class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +val things: List[Any] = List(1, "two", 3.0) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val things: List[String | Int | Double] = List(1, "two", 3.0) // с типами объединения +val thingsAny: List[Any] = List(1, "two", 3.0) // с Any +``` +{% endtab %} + +{% endtabs %} + +### Добавление элементов в список + +Поскольку `List` неизменяем, в него нельзя добавлять новые элементы. +Вместо этого создается новый список с добавленными к существующему списку элементами. +Например, учитывая этот `List`: + +{% tabs adding-elements-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val a = List(1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +Для _добавления_ (_prepend_) к началу списка одного элемента используется метод `::`, для добавления нескольких — `:::`, как показано здесь: + +{% tabs adding-elements-example %} + +{% tab 'Scala 2 и 3' %} +```scala +val b = 0 :: a // List(0, 1, 2, 3) +val c = List(-1, 0) ::: a // List(-1, 0, 1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +Также можно _добавить_ (_append_) элементы в конец `List`, но, поскольку `List` является односвязным, +следует добавлять к нему элементы только в начало; +добавление элементов в конец списка — относительно медленная операция, +особенно при работе с большими последовательностями. + +> Совет: если необходимо добавлять к неизменяемой последовательности элементы в начало и конец, используйте `Vector`. + +Поскольку `List` является связанным списком, +крайне нежелательно пытаться получить доступ к элементам больших списков по значению их индекса. +Например, если есть `List` с миллионом элементов, доступ к такому элементу, как `myList(999_999)`, +займет относительно много времени, потому что этот запрос должен пройти почти через все элементы. +Если есть большая коллекция и необходимо получать доступ к элементам по их индексу, то +вместо `List` используйте `Vector` или `ArrayBuffer`. + +### Как запомнить названия методов + +В методах Scala символ `:` представляет сторону, на которой находится последовательность, +поэтому, когда используется метод `+:`, список нужно указывать справа: + +{% tabs list-prepending %} + +{% tab 'Scala 2 и 3' %} +```scala +0 +: a +``` +{% endtab %} + +{% endtabs %} + +Аналогично, если используется `:+`, список должен быть слева: + +{% tabs list-appending %} + +{% tab 'Scala 2 и 3' %} +```scala +a :+ 4 +``` +{% endtab %} + +{% endtabs %} + +Хорошей особенностью таких символических имен у методов является то, что они стандартизированы. + +Те же имена методов используются с другими неизменяемыми последовательностями, такими как `Seq` и `Vector`. +Также можно использовать несимволические имена методов для добавления элементов в начало (`a.prepended(4)`) +или конец (`a.appended(4)`). + +### Как пройтись по списку + +Представим, что есть `List` имён: + +{% tabs list-loop-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val names = List("Joel", "Chris", "Ed") +``` +{% endtab %} + +{% endtabs %} + +Напечатать каждое имя можно следующим способом: + +{% tabs list-loop-example class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +for (name <- names) println(name) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +for name <- names do println(name) +``` +{% endtab %} + +{% endtabs %} + +Вот как это выглядит в REPL: + +{% tabs list-loop-repl class=tabs-scala-version %} + +{% tab 'Scala 2' %} +```scala +scala> for (name <- names) println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for name <- names do println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% endtabs %} + + +Преимуществом использования выражений вида `for` с коллекциями в том, что Scala стандартизирован, +и один и тот же подход работает со всеми последовательностями, +включая `Array`, `ArrayBuffer`, `List`, `Seq`, `Vector`, `Map`, `Set` и т.д. + +### Немного истории + +Список Scala подобен списку из языка программирования [Lisp](https://en.wikipedia.org/wiki/Lisp_(programming_language)), +который был впервые представлен в 1958 году. +Действительно, в дополнение к привычному способу создания списка: + +{% tabs list-history-init %} + +{% tab 'Scala 2 и 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +точно такой же список можно создать следующим образом: + +{% tabs list-history-init2 %} + +{% tab 'Scala 2 и 3' %} +```scala +val list = 1 :: 2 :: 3 :: Nil +``` +{% endtab %} + +{% endtabs %} + +REPL показывает, как это работает: + +{% tabs list-history-repl %} + +{% tab 'Scala 2 и 3' %} +```scala +scala> val list = 1 :: 2 :: 3 :: Nil +list: List[Int] = List(1, 2, 3) +``` +{% endtab %} + +{% endtabs %} + +Это работает, потому что `List` — односвязный список, оканчивающийся элементом `Nil`, +а `::` — это метод `List`, работающий как оператор “cons” в Lisp. + + +### Отступление: LazyList + +Коллекции Scala также включают [LazyList](https://www.scala-lang.org/api/current/scala/collection/immutable/LazyList.html), +который представляет собой _ленивый_ неизменяемый связанный список. +Он называется «ленивым» — или нестрогим — потому что вычисляет свои элементы только тогда, когда они необходимы. + +Вы можете увидеть отложенное вычисление `LazyList` в REPL: + +{% tabs lazylist-example %} + +{% tab 'Scala 2 и 3' %} +```scala +val x = LazyList.range(1, Int.MaxValue) +x.take(1) // LazyList(
+ Это новое в Scala 3 и не поддерживается в Scala 2. ++ +При желании можно дополнительно включить оператор `end if` в конце каждого выражения: +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +end if +``` + +### `if`/`else` выражения всегда возвращают результат + +Сравнения `if`/`else` образуют _выражения_ - это означает, что они возвращают значение, которое можно присвоить переменной. +Поэтому нет необходимости в специальном тернарном операторе: + +{% tabs control-structures-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-6 %} +```scala +val minValue = if (a < b) a else b +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-6 %} +```scala +val minValue = if a < b then a else b +``` +{% endtab %} +{% endtabs %} + + +Поскольку эти выражения возвращают значение, то выражения `if`/`else` можно использовать в качестве тела метода: + +{% tabs control-structures-7 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-7 %} +```scala +def compare(a: Int, b: Int): Int = + if (a < b) + -1 + else if (a == b) + 0 + else + 1 +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-7 %} +```scala +def compare(a: Int, b: Int): Int = + if a < b then + -1 + else if a == b then + 0 + else + 1 +``` +{% endtab %} +{% endtabs %} + +### В сторону: программирование, ориентированное на выражения + +Кратко о программировании в целом: когда каждое написанное вами выражение возвращает значение, +такой стиль называется _программированием, ориентированным на выражения_, +или EOP (_expression-oriented programming_). +Например, это _выражение_: + +{% tabs control-structures-8 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-8 %} +```scala +val minValue = if (a < b) a else b +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-8 %} +```scala +val minValue = if a < b then a else b +``` +{% endtab %} +{% endtabs %} + +И наоборот, строки кода, которые не возвращают значения, называются _операторами_ +и используются для получения _побочных эффектов_. +Например, эти строки кода не возвращают значения, поэтому они используются для побочных эффектов: + +{% tabs control-structures-9 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-9 %} +```scala +if (a == b) action() +println("Hello") +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-9 %} +```scala +if a == b then action() +println("Hello") +``` +{% endtab %} +{% endtabs %} + +В первом примере метод `action` запускается как побочный эффект, когда `a` равно `b`. +Второй пример используется для побочного эффекта печати строки в STDOUT. +Когда вы узнаете больше о Scala, то обнаружите, что пишете больше _выражений_ и меньше _операторов_. + +## Циклы `for` + +В самом простом случае цикл `for` в Scala можно использовать для перебора элементов в коллекции. +Например, имея последовательность целых чисел, +вы можете перебрать ее элементы и вывести их значения следующим образом: + +{% tabs control-structures-10 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-10 %} +```scala +val ints = Seq(1, 2, 3) +for (i <- ints) println(i) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-10 %} +```scala +val ints = Seq(1, 2, 3) +for i <- ints do println(i) +``` +{% endtab %} +{% endtabs %} + + +Код `i <- ints` называется _генератором_. + +Вот как выглядит результат в Scala REPL: + +{% tabs control-structures-11 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for (i <- ints) println(i) +1 +2 +3 +```` +{% endtab %} +{% tab 'Scala 3' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for i <- ints do println(i) +1 +2 +3 +```` +{% endtab %} +{% endtabs %} + + +Если вам нужен многострочный блок кода после генератора `for`, используйте следующий синтаксис: + +{% tabs control-structures-12 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-12 %} +```scala +for (i <- ints) { + val x = i * 2 + println(s"i = $i, x = $x") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-12 %} +```scala +for i <- ints +do + val x = i * 2 + println(s"i = $i, x = $x") +``` +{% endtab %} +{% endtabs %} + + +### Несколько генераторов + +Циклы `for` могут иметь несколько генераторов, как показано в этом примере: + +{% tabs control-structures-13 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-13 %} +```scala +for { + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +} { + println(s"i = $i, j = $j, k = $k") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-13 %} +```scala +for + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +do + println(s"i = $i, j = $j, k = $k") +``` +{% endtab %} +{% endtabs %} + + +Это выражение выводит следующее: + +```` +i = 1, j = a, k = 1 +i = 1, j = a, k = 6 +i = 1, j = b, k = 1 +i = 1, j = b, k = 6 +i = 2, j = a, k = 1 +i = 2, j = a, k = 6 +i = 2, j = b, k = 1 +i = 2, j = b, k = 6 +```` + +### "Ограничители" + +Циклы `for` также могут содержать операторы `if`, известные как _ограничители_ (_guards_): + +{% tabs control-structures-14 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-14 %} +```scala +for { + i <- 1 to 5 + if i % 2 == 0 +} { + println(i) +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-14 %} +```scala +for + i <- 1 to 5 + if i % 2 == 0 +do + println(i) +``` +{% endtab %} +{% endtabs %} + + +Результат этого цикла: + +```` +2 +4 +```` + +Цикл `for` может содержать столько стражников, сколько необходимо. +В этом примере показан один из способов печати числа `4`: + +{% tabs control-structures-15 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-15 %} +```scala +for { + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +} { + println(i) +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-15 %} +```scala +for + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +do + println(i) +``` +{% endtab %} +{% endtabs %} + +### Использование `for` с Maps + +Вы также можете использовать циклы `for` с `Map`. +Например, если задана такая `Map` с аббревиатурами штатов и их полными названиями: + +{% tabs map %} +{% tab 'Scala 2 и 3' for=map %} +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AR" -> "Arizona" +) +``` +{% endtab %} +{% endtabs %} + +, то можно распечатать ключи и значения, используя `for`. Например: + +{% tabs control-structures-16 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-16 %} +```scala +for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-16 %} +```scala +for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +``` +{% endtab %} +{% endtabs %} + +Вот как это выглядит в REPL: + +{% tabs control-structures-17 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-17 %} +```scala +scala> for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-17 %} +```scala +scala> for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` +{% endtab %} +{% endtabs %} + +Когда цикл `for` перебирает мапу, каждая пара ключ/значение привязывается +к переменным `abbrev` и `fullName`, которые находятся в кортеже: + +```scala +(abbrev, fullName) <- states +``` + +По мере выполнения цикла переменная `abbrev` принимает значение текущего _ключа_ в мапе, +а переменная `fullName` - соответствующему ключу _значению_. + +## Выражение `for` + +В предыдущих примерах циклов `for` все эти циклы использовались для _побочных эффектов_, +в частности для вывода этих значений в STDOUT с помощью `println`. + +Важно знать, что вы также можете создавать _выражения_ `for`, которые возвращают значения. +Вы создаете выражение `for`, добавляя ключевое слово `yield` и возвращаемое выражение, например: + +{% tabs control-structures-18 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-18 %} +```scala +val list = + for (i <- 10 to 12) + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-18 %} +```scala +val list = + for i <- 10 to 12 + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` +{% endtab %} +{% endtabs %} + + +После выполнения этого выражения `for` переменная `list` содержит `Vector` с отображаемыми значениями. +Вот как работает выражение: + +1. Выражение `for` начинает перебирать значения в диапазоне `(10, 11, 12)`. + Сначала оно работает со значением `10`, умножает его на `2`, затем выдает результат - `20`. +2. Далее берет `11` — второе значение в диапазоне. Умножает его на `2`, а затем выдает значение `22`. + Можно представить эти полученные значения как накопление во временном хранилище. +3. Наконец, цикл берет число `12` из диапазона, умножает его на `2`, получая число `24`. + Цикл завершается в этой точке и выдает конечный результат - `Vector(20, 22, 24)`. + +Хотя целью этого раздела является демонстрация выражений `for`, полезно знать, +что показанное выражение `for` эквивалентно вызову метода `map`: + +{% tabs map-call %} +{% tab 'Scala 2 и 3' for=map-call %} +```scala +val list = (10 to 12).map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +Выражения `for` можно использовать в любой момент, когда вам нужно просмотреть все элементы в коллекции +и применить алгоритм к этим элементам для создания нового списка. + +Вот пример, который показывает, как использовать блок кода после `yield`: + +{% tabs control-structures-19 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-19 %} +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for (name <- names) yield { + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName +} + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-19 %} +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for name <- names yield + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` +{% endtab %} +{% endtabs %} + +### Использование выражения `for` в качестве тела метода + + +Поскольку выражение `for` возвращает результат, его можно использовать в качестве тела метода, +который возвращает полезное значение. +Этот метод возвращает все значения в заданном списке целых чисел, которые находятся между `3` и `10`: + +{% tabs control-structures-20 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-20 %} +```scala +def between3and10(xs: List[Int]): List[Int] = + for { + x <- xs + if x >= 3 + if x <= 10 + } yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-20 %} +```scala +def between3and10(xs: List[Int]): List[Int] = + for + x <- xs + if x >= 3 + if x <= 10 + yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` +{% endtab %} +{% endtabs %} + +## Циклы `while` + +Синтаксис цикла `while` в Scala выглядит следующим образом: + +{% tabs control-structures-21 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-21 %} +```scala +var i = 0 + +while (i < 3) { + println(i) + i += 1 +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-21 %} +```scala +var i = 0 + +while i < 3 do + println(i) + i += 1 +``` +{% endtab %} +{% endtabs %} + +## `match` выражения + +Сопоставление с образцом (_pattern matching_) является основой функциональных языков программирования. +Scala включает в себя pattern matching, обладающий множеством возможностей. + +В самом простом случае можно использовать выражение `match`, подобное оператору Java `switch`, +сопоставляя на основе целочисленного значения. +Как и предыдущие структуры, сопоставление с образцом - это действительно выражение, поскольку оно вычисляет результат: + +{% tabs control-structures-22 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-22 %} +```scala +// `i` is an integer +val day = i match { + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // по умолчанию, перехватывает остальное +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-22 %} +```scala +// `i` is an integer +val day = i match + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // по умолчанию, перехватывает остальное +``` +{% endtab %} +{% endtabs %} + + +В этом примере переменная `i` сопоставляется с заданными числами. +Если она находится между `0` и `6`, `day` принимает значение строки, представляющей день недели. +В противном случае она соответствует подстановочному знаку, представленному символом `_`, +и `day` принимает значение строки `"invalid day"`. + +Поскольку сопоставляемые значения рассматриваются в том порядке, в котором они заданы, +и используется первое совпадение, +случай по умолчанию, соответствующий любому значению, должен идти последним. +Любые сопоставляемые случаи после значения по умолчанию будут помечены как недоступные и будет выведено предупреждение. + +> При написании простых выражений соответствия, подобных этому, рекомендуется использовать аннотацию `@switch` для переменной `i`. +> Эта аннотация содержит предупреждение во время компиляции, если switch не может быть скомпилирован в `tableswitch` +> или `lookupswitch`, которые лучше подходят с точки зрения производительности. + + +### Использование значения по умолчанию + +Когда необходимо получить доступ к универсальному значению по умолчанию в `match` выражении, +просто укажите вместо `_` имя переменной в левой части оператора `case`, +а затем используйте это имя переменной в правой части оператора при необходимости: + +{% tabs control-structures-23 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-23 %} +```scala +i match { + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-23 %} +```scala +i match + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what") +``` +{% endtab %} +{% endtabs %} + +Имя, используемое в шаблоне, должно начинаться со строчной буквы. +Имя, начинающееся с заглавной буквы, не представляет собой новую переменную, +но соответствует значению в области видимости: + +{% tabs control-structures-24 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-24 %} +```scala +val N = 42 +i match { + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-24 %} +```scala +val N = 42 +i match + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +``` +{% endtab %} +{% endtabs %} + +Если `i` равно `42`, то оно будет соответствовать `case N` и напечатает строку `"42"`. +И не достигнет случая по умолчанию. + +### Обработка нескольких возможных совпадений в одной строке + +Как уже упоминалось, `match` выражения многофункциональны. +В этом примере показано, как в каждом операторе `case` использовать несколько возможных совпадений: + +{% tabs control-structures-25 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-25 %} +```scala +val evenOrOdd = i match { + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-25 %} +```scala +val evenOrOdd = i match + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +``` +{% endtab %} +{% endtabs %} + +### Использование `if` стражников в `case` предложениях + +В case выражениях также можно использовать стражников. +В этом примере второй и третий case используют стражников для сопоставления нескольких целочисленных значений: + +{% tabs control-structures-26 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-26 %} +```scala +i match { + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-26 %} +```scala +i match + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +``` +{% endtab %} +{% endtabs %} + + +Вот еще один пример, который показывает, как сопоставить заданное значение с диапазоном чисел: + +{% tabs control-structures-27 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-27 %} +```scala +i match { + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-27 %} +```scala +i match + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +``` +{% endtab %} +{% endtabs %} + + +#### Case классы и сопоставление с образцом + +Вы также можете извлекать поля из `case` классов — и классов, которые имеют корректно написанные методы `apply`/`unapply` — +и использовать их в своих условиях. +Вот пример использования простого case класса `Person`: + +{% tabs control-structures-28 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-28 %} +```scala +case class Person(name: String) + +def speak(p: Person) = p match { + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") +} + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-28 %} +```scala +case class Person(name: String) + +def speak(p: Person) = p match + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` +{% endtab %} +{% endtabs %} + +### Использование `match` выражения в качестве тела метода + +Поскольку `match` выражения возвращают значение, их можно использовать в качестве тела метода. +Метод `isTruthy` принимает в качестве входного параметра значение `Matchable` +и возвращает `Boolean` на основе сопоставления с образцом: + +{% tabs control-structures-29 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-29 %} +```scala +def isTruthy(a: Matchable) = a match { + case 0 | "" | false => false + case _ => true +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-29 %} +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" | false => false + case _ => true +``` +{% endtab %} +{% endtabs %} + +Входной параметр `a` имеет [тип `Matchable`][matchable], являющийся основой всех типов Scala, +для которых может выполняться сопоставление с образцом. +Метод реализован путем сопоставления на входе в метод, обрабатывая два варианта: +первый проверяет, является ли заданное значение целым числом `0`, пустой строкой или `false` и в этом случае возвращается `false`. +Для любого другого значения в случае по умолчанию мы возвращаем `true`. +Примеры ниже показывают, как работает этот метод: + +{% tabs is-truthy-call %} +{% tab 'Scala 2 и 3' for=is-truthy-call %} +```scala +isTruthy(0) // false +isTruthy(false) // false +isTruthy("") // false +isTruthy(1) // true +isTruthy(" ") // true +isTruthy(2F) // true +``` +{% endtab %} +{% endtabs %} + +Использование сопоставления с образцом в качестве тела метода очень распространено. + +#### Использование различных шаблонов в сопоставлении с образцом + +Для выражения `match` можно использовать множество различных шаблонов. +Например: + +- Сравнение с константой (такое как `case 3 =>`) +- Сравнение с последовательностями (такое как `case List(els : _*) =>`) +- Сравнение с кортежами (такое как `case (x, y) =>`) +- Сравнение с конструктором класса (такое как `case Person(first, last) =>`) +- Сравнение по типу (такое как `case p: Person =>`) + +Все эти виды шаблонов показаны в следующем методе `pattern`, +который принимает входной параметр типа `Matchable` и возвращает `String`: + +{% tabs control-structures-30 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-30 %} +```scala +def pattern(x: Matchable): String = x match { + + // сравнение с константой + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // сравнение с последовательностями + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // сравнение с кортежами + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // сравнение с конструктором класса + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // сравнение по типу + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // значение по умолчанию с подстановочным знаком + case _ => "Unknown" +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-30 %} +```scala +def pattern(x: Matchable): String = x match + + // сравнение с константой + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // сравнение с последовательностями + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // сравнение с кортежами + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // сравнение с конструктором класса + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // сравнение по типу + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // значение по умолчанию с подстановочным знаком + case _ => "Unknown" +``` +{% endtab %} +{% endtabs %} + +## try/catch/finally + +Как и в Java, в Scala есть конструкция `try`/`catch`/`finally`, позволяющая перехватывать исключения и управлять ими. +Для обеспечения согласованности Scala использует тот же синтаксис, что и выражения `match`, +и поддерживает сопоставление с образцом для различных возможных исключений. + +В следующем примере `openAndReadAFile` - это метод, который выполняет то, что следует из его названия: +он открывает файл и считывает из него текст, присваивая результат изменяемой переменной `text`: + +{% tabs control-structures-31 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-31 %} +```scala +var text = "" +try { + text = openAndReadAFile(filename) +} catch { + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +} finally { + // здесь необходимо закрыть ресурсы + println("Came to the 'finally' clause.") +} +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-31 %} +```scala +var text = "" +try + text = openAndReadAFile(filename) +catch + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +finally + // здесь необходимо закрыть ресурсы + println("Came to the 'finally' clause.") +``` +{% endtab %} +{% endtabs %} + +Предполагая, что метод `openAndReadAFile` использует Java `java.io.*` классы для чтения файла +и не перехватывает его исключения, попытка открыть и прочитать файл может привести как к `FileNotFoundException`, +так и к `IOException`, и эти два исключения перехватываются в блоке `catch` этого примера. + +[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html diff --git a/_ru/scala3/book/domain-modeling-fp.md b/_ru/scala3/book/domain-modeling-fp.md new file mode 100644 index 0000000000..a5bdb326c5 --- /dev/null +++ b/_ru/scala3/book/domain-modeling-fp.md @@ -0,0 +1,825 @@ +--- +layout: multipage-overview +title: Моделирование ФП +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлено введение в моделирование предметной области с использованием ФП в Scala 3. +language: ru +num: 23 +previous-page: domain-modeling-oop +next-page: methods-intro +--- + + +В этой главе представлено введение в моделирование предметной области +с использованием функционального программирования (ФП) в Scala 3. +При моделировании окружающего нас мира с помощью ФП обычно используются следующие конструкции Scala: + +- Перечисления +- Case классы +- Trait-ы + +> Если вы не знакомы с алгебраическими типами данных (ADT) и их обобщенной версией (GADT), +> то можете прочитать главу ["Алгебраические типы данных"][adts], прежде чем читать этот раздел. + +## Введение + +В ФП *данные* и *операции над этими данными* — это две разные вещи; вы не обязаны инкапсулировать их вместе, как в ООП. + +Концепция аналогична числовой алгебре. +Когда вы думаете о целых числах, больших либо равных нулю, +у вас есть *набор* возможных значений, который выглядит следующим образом: + +```` +0, 1, 2 ... Int.MaxValue +```` + +Игнорируя деление целых чисел, возможные *операции* над этими значениями такие: + +```` ++, -, * +```` + +Схема ФП реализуется аналогичным образом: + +- описывается свой набор значений (данные) +- описываются операции, которые работают с этими значениями (функции) + +> Как будет видно, рассуждения о программах в этом стиле сильно отличаются от объектно-ориентированного программирования. +> Проще говоря о данных в ФП: +> Отделение функциональности от данных позволяет проверять свои данные, не беспокоясь о поведении. + +В этой главе мы смоделируем данные и операции для “пиццы” в пиццерии. +Будет показано, как реализовать часть “данных” модели Scala/ФП, +а затем - несколько различных способов организации операций с этими данными. + +## Моделирование данных + +В Scala достаточно просто описать модель данных: + +- если необходимо смоделировать данные с различными вариантами, то используется конструкция `enum` (или `case object` в Scala 2) +- если необходимо только сгруппировать сущности (или нужен более детальный контроль), то используются case class-ы + +### Описание вариантов + +Данные, которые просто состоят из различных вариантов, таких как размер корочки, тип корочки и начинка, +кратко моделируются с помощью перечислений: + +{% tabs data_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_1 %} + +В Scala 2 перечисления выражаются комбинацией `sealed class` и нескольких `case object`, которые расширяют класс: + +```scala +sealed abstract class CrustSize +object CrustSize { + case object Small extends CrustSize + case object Medium extends CrustSize + case object Large extends CrustSize +} + +sealed abstract class CrustType +object CrustType { + case object Thin extends CrustType + case object Thick extends CrustType + case object Regular extends CrustType +} + +sealed abstract class Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_1 %} + +В Scala 3 перечисления кратко выражаются конструкцией `enum`: + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +> Типы данных, которые описывают различные варианты (например, `CrustSize`), +> также иногда называются суммированными типами (_sum types_). + +### Описание основных данных + +Пиццу можно рассматривать как _составной_ контейнер с различными атрибутами, указанными выше. +Мы можем использовать `case class`, чтобы описать, +что `Pizza` состоит из `crustSize`, `crustType` и, возможно, нескольких `toppings`: + +{% tabs data_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_2 %} + +```scala +import CrustSize._ +import CrustType._ +import Topping._ + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% tab 'Scala 3' for=data_2 %} + +```scala +import CrustSize.* +import CrustType.* +import Topping.* + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% endtabs %} + +> Типы данных, объединяющие несколько компонентов (например, `Pizza`), также иногда называют типами продуктов (_product types_). + +И все. Это модель данных для системы доставки пиццы в стиле ФП. +Решение очень лаконично, поскольку оно не требует объединения модели данных с операциями с пиццей. +Модель данных легко читается, как объявление дизайна для реляционной базы данных. +Также очень легко создавать значения нашей модели данных и проверять их: + +{% tabs data_3 %} +{% tab 'Scala 2 и 3' for=data_3 %} + +```scala +val myFavPizza = Pizza(Small, Regular, Seq(Cheese, Pepperoni)) +println(myFavPizza.crustType) // печатает Regular +``` + +{% endtab %} +{% endtabs %} + +#### Подробнее о модели данных + +Таким же образом можно было бы смоделировать всю систему заказа пиццы. +Вот несколько других `case class`-ов, которые используются для моделирования такой системы: + +{% tabs data_4 %} +{% tab 'Scala 2 и 3' for=data_4 %} + +```scala +case class Address( + street1: String, + street2: Option[String], + city: String, + state: String, + zipCode: String +) + +case class Customer( + name: String, + phone: String, + address: Address +) + +case class Order( + pizzas: Seq[Pizza], + customer: Customer +) +``` + +{% endtab %} +{% endtabs %} + +#### “Узкие доменные объекты” + +В своей книге *Functional and Reactive Domain Modeling*, Debasish Ghosh утверждает, +что там, где специалисты по ООП описывают свои классы как “широкие модели предметной области”, +которые инкапсулируют данные и поведение, +модели данных ФП можно рассматривать как “узкие объекты предметной области”. +Это связано с тем, что, как показано выше, модели данных определяются как `case` классы с атрибутами, +но без поведения, что приводит к коротким и лаконичным структурам данных. + +## Моделирование операций + +Возникает интересный вопрос: поскольку ФП отделяет данные от операций над этими данными, +то как эти операции реализуются в Scala? + +Ответ на самом деле довольно прост: пишутся функции (или методы), работающие со значениями смоделированных данных. +Например, можно определить функцию, которая вычисляет цену пиццы. + +{% tabs data_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match { + case Pizza(crustSize, crustType, toppings) => { + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match + case Pizza(crustSize, crustType, toppings) => + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops +``` + +{% endtab %} +{% endtabs %} + +Можно заметить, что реализация функции просто повторяет форму данных: поскольку `Pizza` является case class-ом, +используется сопоставление с образцом для извлечения компонентов, +а затем вызываются вспомогательные функции для вычисления отдельных цен. + +{% tabs data_6 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match { + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +``` + +{% endtab %} +{% endtabs %} + +Точно так же, поскольку `Topping` является перечислением, +используется сопоставление с образцом, чтобы разделить варианты. +Сыр и лук продаются по 50 центов за штуку, остальные — по 75. + +{% tabs data_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match { + // если размер корочки маленький или средний, тип не важен + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 + } +``` + +{% endtab %} + +{% tab 'Scala 3' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match + // если размер корочки маленький или средний, тип не важен + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 +``` + +{% endtab %} +{% endtabs %} + +Чтобы рассчитать цену корки, мы одновременно сопоставляем образцы как по размеру, так и по типу корки. + +> Важным моментом во всех показанных выше функциях является то, что они являются чистыми функциями (_pure functions_): +> они не изменяют данные и не имеют других побочных эффектов (таких, как выдача исключений или запись в файл). +> Всё, что они делают - это просто получают значения и вычисляют результат. + +## Как организовать функциональность? + +При реализации функции `pizzaPrice`, описанной выше, не было сказано, _где_ ее определять. +Scala предоставляет множество отличных инструментов для организации логики в различных пространствах имен и модулях. + +Существует несколько способов реализации и организации поведения: + +- определить функции в сопутствующих объектах (companion object) +- использовать модульный стиль программирования +- использовать подход “функциональных объектов” +- определить функциональность в методах расширения + +Эти различные решения показаны в оставшейся части этого раздела. + +### Сопутствующий объект + +Первый подход — определить поведение (функции) в сопутствующем объекте. + +> Как обсуждалось в разделе [“Инструменты”][modeling-tools], +> _сопутствующий объект_ — это `object` с тем же именем, что и у класса, и объявленный в том же файле, что и класс. + +При таком подходе в дополнение к `enum` или `case class` также определяется сопутствующий объект с таким же именем, +который содержит поведение (функции). + +{% tabs org_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// сопутствующий объект для case class Pizza +object Pizza { + // тоже самое, что и `pizzaPrice` + def price(p: Pizza): Double = ... +} + +sealed abstract class Topping + +// сопутствующий объект для перечисления Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping + + // тоже самое, что и `toppingPrice` + def price(t: Topping): Double = ... +} +``` + +{% endtab %} +{% tab 'Scala 3' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// сопутствующий объект для case class Pizza +object Pizza: + // тоже самое, что и `pizzaPrice` + def price(p: Pizza): Double = ... + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions + +// сопутствующий объект для перечисления Topping +object Topping: + // тоже самое, что и `toppingPrice` + def price(t: Topping): Double = ... +``` + +{% endtab %} +{% endtabs %} + +При таком подходе можно создать `Pizza` и вычислить ее цену следующим образом: + +{% tabs org_2 %} +{% tab 'Scala 2 и 3' for=org_2 %} + +```scala +val pizza1 = Pizza(Small, Thin, Seq(Cheese, Onions)) +Pizza.price(pizza1) +``` + +{% endtab %} +{% endtabs %} + +Группировка функциональности с помощью сопутствующих объектов имеет несколько преимуществ: + +- связывает функциональность с данными и облегчает их поиск программистам (и компилятору). +- создает пространство имен и, например, позволяет использовать `price` в качестве имени метода, не полагаясь на перегрузку. +- реализация `Topping.price` может получить доступ к значениям перечисления, таким как `Cheese`, без необходимости их импорта. + +Однако также есть несколько компромиссов, которые следует учитывать: + +- модель данных тесно связывается с функциональностью. + В частности, сопутствующий объект должен быть определен в том же файле, что и `case class`. +- неясно, где определять такие функции, как `crustPrice`, + которые с одинаковым успехом можно поместить в сопутствующий объект `CrustSize` или `CrustType`. + +## Модули + +Второй способ организации поведения — использование “модульного” подхода. +В книге _“Программирование на Scala”_ _модуль_ определяется как +“небольшая часть программы с четко определенным интерфейсом и скрытой реализацией”. +Давайте посмотрим, что это значит. + +### Создание интерфейса `PizzaService` + +Первое, о чем следует подумать, — это “поведение” `Pizza`. +Делая это, определяем `trait PizzaServiceInterface` следующим образом: + +{% tabs module_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_1 %} + +```scala +trait PizzaServiceInterface { + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_1 %} + +```scala +trait PizzaServiceInterface: + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +``` + +{% endtab %} +{% endtabs %} + +Как показано, каждый метод принимает `Pizza` в качестве входного параметра вместе с другими параметрами, +а затем возвращает экземпляр `Pizza` в качестве результата. + +Когда пишется такой чистый интерфейс, можно думать о нем как о контракте, +в котором говорится: “Все неабстрактные классы, расширяющие этот trait, должны предоставлять реализацию этих сервисов”. + +На этом этапе также можно представить, что вы являетесь потребителем этого API. +Когда вы это сделаете, будет полезно набросать некоторый пример “потребительского” кода, +чтобы убедиться, что API выглядит так, как хотелось: + +{% tabs module_2 %} +{% tab 'Scala 2 и 3' for=module_2 %} + +```scala +val p = Pizza(Small, Thin, Seq(Cheese)) + +// как вы хотите использовать методы в PizzaServiceInterface +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) +``` + +{% endtab %} +{% endtabs %} + +Если с этим кодом все в порядке, как правило, можно начать набрасывать другой API, например API для заказов, +но, поскольку сейчас рассматривается только `Pizza`, перейдем к созданию конкретной реализации этого интерфейса. + +> Обратите внимание, что обычно это двухэтапный процесс. +> На первом шаге набрасывается контракт API в качестве _интерфейса_. +> На втором шаге создается конкретная _реализация_ этого интерфейса. +> В некоторых случаях в конечном итоге создается несколько конкретных реализаций базового интерфейса. + +### Создание конкретной реализации + +Теперь, когда известно, как выглядит `PizzaServiceInterface`, можно создать конкретную реализацию, +написав тело для всех методов, определенных в интерфейсе: + +{% tabs module_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface { + + def price(p: Pizza): Double = + ... // реализация была дана выше + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface: + + def price(p: Pizza): Double = + ... // реализация была дана выше + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) + +end PizzaService +``` + +{% endtab %} +{% endtabs %} + +Хотя двухэтапный процесс создания интерфейса с последующей реализацией не всегда необходим, +явное продумывание API и его использования — хороший подход. + +Когда все готово, можно использовать `Pizza` и `PizzaService`: + +{% tabs module_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_4 %} + +```scala +import PizzaService._ + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// использование методов PizzaService +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // печатает 8.75 +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_4 %} + +```scala +import PizzaService.* + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// использование методов PizzaService +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // печатает 8.75 +``` + +{% endtab %} +{% endtabs %} + +### Функциональные объекты + +В книге _“Программирование на Scala”_ авторы определяют термин “Функциональные объекты” как +“объекты, которые не имеют никакого изменяемого состояния”. +Это также относится к типам в `scala.collection.immutable`. +Например, методы в `List` не изменяют внутреннего состояния, а вместо этого в результате создают копию `List`. + +Об этом подходе можно думать, как о “гибридном дизайне ФП/ООП”, потому что: + +- данные моделируются, используя неизменяемые `case` классы. +- определяется поведение (методы) _того же типа_, что и данные. +- поведение реализуется как чистые функции: они не изменяют никакого внутреннего состояния; скорее - возвращают копию. + +> Это действительно гибридный подход: как и в **дизайне ООП**, методы инкапсулированы в класс с данными, +> но, как это обычно бывает **в дизайне ФП**, методы реализованы как чистые функции, которые данные не изменяют. + +#### Пример + +Используя этот подход, можно напрямую реализовать функциональность пиццы в `case class`: + +{% tabs module_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) { + + // операции этой модели данных + def price: Double = + pizzaPrice(this) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +} +``` + +{% endtab %} + +{% tab 'Scala 3' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +): + + // операции этой модели данных + def price: Double = + pizzaPrice(this) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что в отличие от предыдущих подходов, поскольку это методы класса `Pizza`, +они не принимают ссылку `Pizza` в качестве входного параметра. +Вместо этого у них есть собственная ссылка на текущий экземпляр пиццы - `this`. + +Теперь можно использовать этот новый дизайн следующим образом: + +{% tabs module_6 %} +{% tab 'Scala 2 и 3' for=module_6 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +### Методы расширения + +Методы расширения - подход, который находится где-то между первым (определение функций в сопутствующем объекте) +и последним (определение функций как методов самого типа). + +Методы расширения позволяют создавать API, похожий на API функционального объекта, +без необходимости определять функции как методы самого типа. +Это может иметь несколько преимуществ: + +- модель данных снова _очень лаконична_ и не упоминает никакого поведения. +- можно _задним числом_ развить функциональность типов дополнительными методами, не изменяя исходного определения. +- помимо сопутствующих объектов или прямых методов типов, методы расширения могут быть определены _извне_ в другом файле. + +Вернемся к примеру: + +{% tabs module_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +implicit class PizzaOps(p: Pizza) { + def price: Double = + pizzaPrice(p) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` +В приведенном выше коде мы определяем различные методы для пиццы как методы в _неявном классе_ (_implicit class_). +С `implicit class PizzaOps(p: Pizza)` тогда, где бы `PizzaOps` ни был импортирован, +его методы будут доступны в экземплярах `Pizza`. +Получатель в этом случае `p`. + +{% endtab %} +{% tab 'Scala 3' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +extension (p: Pizza) + def price: Double = + pizzaPrice(p) // такая же имплементация, как и выше + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +``` +В приведенном выше коде мы определяем различные методы для пиццы как _методы расширения_ (_extension methods_). +С помощью `extension (p: Pizza)` мы говорим, что хотим сделать методы доступными для экземпляров `Pizza`. +Получатель в этом случае `p`. + +{% endtab %} +{% endtabs %} + +Используя наши методы расширения, мы можем получить тот же API, что и раньше: + +{% tabs module_8 %} +{% tab 'Scala 2 и 3' for=module_8 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +При этом методы расширения можно определить в любом другом модуле. +Как правило, если вы являетесь разработчиком модели данных, то определяете свои методы расширения в сопутствующем объекте. +Таким образом, они уже доступны всем пользователям. +В противном случае методы расширения должны быть импортированы явно, чтобы их можно было использовать. + +## Резюме функционального подхода + +Определение модели данных в Scala/ФП, как правило, простое: +моделируются варианты данных с помощью перечислений и составных данных с помощью `case` классов. +Затем, чтобы смоделировать поведение, определяются функции, которые работают со значениями модели данных. +Были рассмотрены разные способы организации функций: + +- можно поместить методы в сопутствующие объекты +- можно использовать модульный стиль программирования, разделяющий интерфейс и реализацию +- можно использовать подход “функциональных объектов” и хранить методы в определенном типе данных +- можно использовать методы расширения, чтобы снабдить модель данных функциональностью + +[adts]: {% link _overviews/scala3-book/types-adts-gadts.md %} +[modeling-tools]: {% link _overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_ru/scala3/book/domain-modeling-intro.md b/_ru/scala3/book/domain-modeling-intro.md new file mode 100644 index 0000000000..79828b6d84 --- /dev/null +++ b/_ru/scala3/book/domain-modeling-intro.md @@ -0,0 +1,19 @@ +--- +layout: multipage-overview +title: Моделирование предметной области +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе показано, как можно моделировать предметную область с помощью Scala 3. +language: ru +num: 20 +previous-page: control-structures +next-page: domain-modeling-tools +--- + +В этой главе показано, как можно смоделировать предметную область с помощью Scala 3: + +- В разделе "Инструменты" представлены доступные вам инструменты, включая классы, трейты, перечисления и многое другое. +- В разделе "Моделирование ООП" рассматриваются атрибуты и поведение моделирования в стиле объектно-ориентированного программирования (ООП). +- В разделе "Моделирование ФП" рассматривается моделирование предметной области в стиле функционального программирования (ФП). diff --git a/_ru/scala3/book/domain-modeling-oop.md b/_ru/scala3/book/domain-modeling-oop.md new file mode 100644 index 0000000000..f9de517ddd --- /dev/null +++ b/_ru/scala3/book/domain-modeling-oop.md @@ -0,0 +1,602 @@ +--- +layout: multipage-overview +title: Моделирование ООП +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлено введение в моделирование предметной области с использованием ООП в Scala 3. +language: ru +num: 22 +previous-page: domain-modeling-tools +next-page: domain-modeling-fp +--- + +В этой главе представлено введение в моделирование предметной области с использованием +объектно-ориентированного программирования (ООП) в Scala 3. + +## Введение + +Scala предоставляет все необходимые инструменты для объектно-ориентированного проектирования: + +- **Traits** позволяют указывать (абстрактные) интерфейсы, а также конкретные реализации. +- **Mixin Composition** предоставляет инструменты для создания компонентов из более мелких деталей. +- **Классы** могут реализовывать интерфейсы, заданные трейтами. +- **Экземпляры** классов могут иметь свое собственное приватное состояние. +- **Subtyping** позволяет использовать экземпляр одного класса там, где ожидается экземпляр его суперкласса. +- **Модификаторы доступа** позволяют управлять, к каким членам класса можно получить доступ с помощью какой части кода. + +## Трейты + +В отличие от других языков с поддержкой ООП, таких как Java, возможно, +основным инструментом декомпозиции в Scala являются не классы, а трейты. +Они могут служить для описания абстрактных интерфейсов, таких как: + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String +``` +{% endtab %} +{% endtabs %} + +а также могут содержать конкретные реализации: + +{% tabs traits_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String + def showHtml = "
" + show + "
" +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String + def showHtml = "" + show + "
" +``` +{% endtab %} +{% endtabs %} + +На примере видно, что метод `showHtml` определяется в терминах абстрактного метода `show`. + +[Odersky и Zenger][scalable] представляют _сервис-ориентированную компонентную модель_ и рассматривают: + +- **абстрактные члены** как _требуемые_ службы: их все еще необходимо реализовать в подклассе. +- **конкретные члены** как _предоставляемые_ услуги: они предоставляются подклассу. + +Это видно на примере со `Showable`: определяя класс `Document`, который расширяет `Showable`, +все еще нужно определить `show`, но `showHtml` уже предоставляется: + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Document(text: String) extends Showable { + def show = text +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Document(text: String) extends Showable: + def show = text +``` + +{% endtab %} +{% endtabs %} + +#### Абстрактные члены + +Абстрактными в `trait` могут оставаться не только методы. +`trait` может содержать: + +- абстрактные методы (`def m(): T`) +- абстрактные переменные (`val x: T`) +- абстрактные типы (`type T`), потенциально с ограничениями (`type T <: S`) +- абстрактные given (`given t: T`) только в Scala 3 + +Каждая из вышеперечисленных функций может быть использована для определения той или иной формы требований к реализатору `trait`. + +## Смешанная композиция + +Кроме того, что `trait`-ы могут содержать абстрактные и конкретные определения, +Scala также предоставляет мощный способ создания нескольких `trait`: +структура, которую часто называют _смешанной композицией_. + +Предположим, что существуют следующие два (потенциально независимо определенные) `trait`-а: + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait GreetingService { + def translate(text: String): String + def sayHello = translate("Hello") +} + +trait TranslationService { + def translate(text: String): String = "..." +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait GreetingService: + def translate(text: String): String + def sayHello = translate("Hello") + +trait TranslationService: + def translate(text: String): String = "..." +``` + +{% endtab %} +{% endtabs %} + +Чтобы скомпоновать два сервиса, можно просто создать новый `trait`, расширяющий их: + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait ComposedService extends GreetingService with TranslationService +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait ComposedService extends GreetingService, TranslationService +``` + +{% endtab %} +{% endtabs %} + +Абстрактные элементы в одном `trait`-е (например, `translate` в `GreetingService`) +автоматически сопоставляются с конкретными элементами в другом `trait`-е. +Это работает не только с методами, как в этом примере, но и со всеми другими абстрактными членами, +упомянутыми выше (то есть типами, переменными и т.д.). + +## Классы + +`trait`-ы отлично подходят для модуляции компонентов и описания интерфейсов (обязательных и предоставляемых). +Но в какой-то момент возникнет необходимость создавать их экземпляры. +При разработке программного обеспечения в Scala часто бывает полезно рассмотреть возможность +использования классов только на начальных этапах модели наследования: + +{% tabs table-traits-cls-summary class=tabs-scala-version %} +{% tab 'Scala 2' %} +| Трейты | `T1`, `T2`, `T3` +| Составные трейты | `S1 extends T1 with T2`, `S2 extends T2 with T3` +| Классы | `C extends S1 with T3` +| Экземпляры | `new C()` +{% endtab %} +{% tab 'Scala 3' %} +| Трейты | `T1`, `T2`, `T3` +| Составные трейты | `S1 extends T1, T2`, `S2 extends T2, T3` +| Классы | `C extends S1, T3` +| Экземпляры | `C()` +{% endtab %} +{% endtabs %} + +Это еще более актуально в Scala 3, где трейты теперь также могут принимать параметры конструктора, +что еще больше устраняет необходимость в классах. + +#### Определение класса + +Подобно `trait`-ам, классы могут расширять несколько `trait`-ов (но только один суперкласс): + +{% tabs class_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class MyService(name: String) extends ComposedService with Showable { + def show = s"$name says $sayHello" +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class MyService(name: String) extends ComposedService, Showable: + def show = s"$name says $sayHello" +``` + +{% endtab %} +{% endtabs %} + +#### Подтипы + +Экземпляр `MyService` создается следующим образом: + +{% tabs class_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1: MyService = new MyService("Service 1") +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s1: MyService = MyService("Service 1") +``` + +{% endtab %} +{% endtabs %} + +С помощью подтипов экземпляр `s1` можно использовать везде, где ожидается любое из расширенных свойств: + +{% tabs class_3 %} +{% tab 'Scala 2 и 3' %} + +```scala +val s2: GreetingService = s1 +val s3: TranslationService = s1 +val s4: Showable = s1 +// ... и так далее ... +``` +{% endtab %} +{% endtabs %} + +#### Планирование расширения + +Как упоминалось ранее, можно расширить еще один класс: + +{% tabs class_4 %} +{% tab 'Scala 2 и 3' %} + +```scala +class Person(name: String) +class SoftwareDeveloper(name: String, favoriteLang: String) + extends Person(name) +``` + +{% endtab %} +{% endtabs %} + +Однако, поскольку `trait`-ы разработаны как основное средство декомпозиции, +то не рекомендуется расширять класс, определенный в одном файле, из другого файла. + +Открытые классы только в Scala 3
+ +В Scala 3 расширение неабстрактных классов в других файлах ограничено. +Чтобы разрешить это, базовый класс должен быть помечен как `open`: + +{% tabs class_5 %} +{% tab 'Только в Scala 3' %} + +```scala +open class Person(name: String) +``` +{% endtab %} +{% endtabs %} + +Маркировка классов с помощью [`open`][open] - это новая функция Scala 3. +Необходимость явно помечать классы как открытые позволяет избежать многих распространенных ошибок в ООП. +В частности, это требует, чтобы разработчики библиотек явно планировали расширение +и, например, документировали классы, помеченные как открытые. + +## Экземпляры и приватное изменяемое состояние + +Как и в других языках с поддержкой ООП, трейты и классы в Scala могут определять изменяемые поля: + +{% tabs instance_6 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Counter { + // получить значение можно только с помощью метода `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Counter: + // получить значение можно только с помощью метода `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +``` + +{% endtab %} +{% endtabs %} + +Каждый экземпляр класса `Counter` имеет собственное приватное состояние, +которое можно получить только через метод `count`, как показано в следующем взаимодействии: + +{% tabs instance_7 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val c1 = new Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val c1 = Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% endtabs %} + +#### Модификаторы доступа + +По умолчанию все определения элементов в Scala общедоступны. +Чтобы скрыть детали реализации, можно определить элементы (методы, поля, типы и т.д.) в качестве `private` или `protected`. +Таким образом, вы можете управлять доступом к ним или их переопределением. +Закрытые (`private`) элементы видны только самому классу/трейту и его сопутствующему объекту. +Защищенные (`protected`) элементы также видны для подклассов класса. + +## Дополнительный пример: сервис-ориентированный дизайн + +Далее будут проиллюстрированы некоторые расширенные возможности Scala и показано, +как их можно использовать для структурирования более крупных программных компонентов. +Примеры взяты из статьи Мартина Одерски и Маттиаса Зенгера ["Scalable Component Abstractions"][scalable]. +Пример в первую очередь предназначен для демонстрации того, +как использовать несколько функций типа для создания более крупных компонентов. + +Цель состоит в том, чтобы определить программный компонент с семейством типов, +которые могут быть уточнены позже при реализации компонента. +Конкретно, следующий код определяет компонент `SubjectObserver` как `trait` с двумя членами абстрактного типа, +`S` (для субъектов) и `O` (для наблюдателей): + +{% tabs example_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait SubjectObserver { + + type S <: Subject + type O <: Observer + + trait Subject { self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = { + observers = obs :: observers + } + def publish() = { + for ( obs <- observers ) obs.notify(this) + } + } + + trait Observer { + def notify(sub: S): Unit + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait SubjectObserver: + + type S <: Subject + type O <: Observer + + trait Subject: + self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = + observers = obs :: observers + def publish() = + for obs <- observers do obs.notify(this) + + trait Observer: + def notify(sub: S): Unit +``` + +{% endtab %} +{% endtabs %} + +Есть несколько вещей, которые нуждаются в объяснении. + +#### Члены абстрактного типа + +Тип объявления `S <: Subject` говорит, что внутри trait `SubjectObserver` можно ссылаться на +некоторый _неизвестный_ (то есть абстрактный) тип, который называется `S`. +Однако этот тип не является полностью неизвестным: мы знаем, по крайней мере, что это какой-то подтип `Subject`. +Все trait-ы и классы, расширяющие `SubjectObserver`, могут свободно выбирать любой тип для `S`, +если выбранный тип является подтипом `Subject`. +Часть `<: Subject` декларации также упоминается как верхняя граница на `S`. + +#### Вложенные trait-ы + +_В рамках_ trait-а `SubjectObserver` определяются два других trait-а. +trait `Observer`, который определяет только один абстрактный метод `notify` с одним аргументом типа `S`. +Как будет видно, важно, чтобы аргумент имел тип `S`, а не тип `Subject`. + +Второй trait, `Subject`, определяет одно приватное поле `observers` для хранения всех наблюдателей, +подписавшихся на этот конкретный объект. Подписка на объект просто сохраняет объект в списке. +Опять же, тип параметра `obs` - это `O`, а не `Observer`. + +#### Аннотации собственного типа + +Наконец, что означает `self: S =>` в trait-е `Subject`? Это называется аннотацией собственного типа. +И требует, чтобы подтипы `Subject` также были подтипами `S`. +Это необходимо, чтобы иметь возможность вызывать `obs.notify` с `this` в качестве аргумента, +поскольку для этого требуется значение типа `S`. +Если бы `S` был конкретным типом, аннотацию собственного типа можно было бы заменить на `trait Subject extends S`. + +### Реализация компонента + +Теперь можно реализовать вышеуказанный компонент и определить члены абстрактного типа как конкретные типы: + +{% tabs example_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object SensorReader extends SubjectObserver { + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject { + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = { + currentValue = v + publish() + } + } + + class Display extends Observer { + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +object SensorReader extends SubjectObserver: + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject: + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = + currentValue = v + publish() + + class Display extends Observer: + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") +``` + +{% endtab %} +{% endtabs %} + +В частности, мы определяем _singleton_ `object SensorReader`, который расширяет `SubjectObserver`. +В реализации `SensorReader` говорится, что тип `S` теперь определяется как тип `Sensor`, +а тип `O` определяется как тип `Display`. +И `Sensor`, и `Display` определяются как вложенные классы в `SensorReader`, +реализующие trait-ы `Subject` и `Observer` соответственно. + +Помимо того, что этот код является примером сервис-ориентированного дизайна, +он также освещает многие аспекты объектно-ориентированного программирования: + +- Класс `Sensor` вводит свое собственное частное состояние (`currentValue`) + и инкапсулирует изменение состояния за методом `changeValue`. +- Реализация `changeValue` использует метод `publish`, определенный в родительском trait-е. +- Класс `Display` расширяет trait `Observer` и реализует отсутствующий метод `notify`. + +Важно отметить, что реализация `notify` может безопасно получить доступ только к `label` и значению `sub`, +поскольку мы изначально объявили параметр типа `S`. + +### Использование компонента + +Наконец, следующий код иллюстрирует, как использовать компонент `SensorReader`: + +{% tabs example_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import SensorReader._ + +// настройка сети +val s1 = new Sensor("sensor1") +val s2 = new Sensor("sensor2") +val d1 = new Display() +val d2 = new Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// распространение обновлений по сети +s1.changeValue(2) +s2.changeValue(3) + +// печатает: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 + +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import SensorReader.* + +// настройка сети +val s1 = Sensor("sensor1") +val s2 = Sensor("sensor2") +val d1 = Display() +val d2 = Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// распространение обновлений по сети +s1.changeValue(2) +s2.changeValue(3) + +// печатает: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 +``` + +{% endtab %} +{% endtabs %} + +Имея под рукой все утилиты объектно-ориентированного программирования, в следующем разделе будет продемонстрировано, +как разрабатывать программы в функциональном стиле. + +[scalable]: https://doi.org/10.1145/1094811.1094815 +[open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_ru/scala3/book/domain-modeling-tools.md b/_ru/scala3/book/domain-modeling-tools.md new file mode 100644 index 0000000000..ec35430443 --- /dev/null +++ b/_ru/scala3/book/domain-modeling-tools.md @@ -0,0 +1,1175 @@ +--- +layout: multipage-overview +title: Инструменты +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: В этой главе представлено введение в доступные инструменты моделирования предметной области в Scala 3, включая классы, трейты, перечисления и многое другое. +language: ru +num: 21 +previous-page: domain-modeling-intro +next-page: domain-modeling-oop +--- + + +Scala предоставляет множество различных конструкций для моделирования предметной области: + +- Классы +- Объекты +- Сопутствующие объекты +- Трейты +- Абстрактные классы +- Перечисления только в Scala 3 +- Case классы +- Case объекты + +В этом разделе кратко представлена каждая из этих языковых конструкций. + + +## Классы + +Как и в других языках, _класс_ в Scala — это шаблон для создания экземпляров объекта. +Вот несколько примеров классов: + +{% tabs class_1 %} +{% tab 'Scala 2 и 3' %} + +```scala +class Person(var name: String, var vocation: String) +class Book(var title: String, var author: String, var year: Int) +class Movie(var name: String, var director: String, var year: Int) +``` + +{% endtab %} +{% endtabs %} + +Эти примеры показывают, что в Scala есть очень легкий способ объявления классов. + +Все параметры в примерах наших классов определены как `var` поля, а значит, они изменяемы: их можно читать, а также изменять. +Если вы хотите, чтобы они были неизменяемыми — только для чтения — создайте их как `val` поля или используйте case класс. + +До Scala 3 для создания нового экземпляра класса использовалось ключевое слово `new`: + +{% tabs class_2 %} +{% tab 'Scala 2 и 3' %} + +```scala +val p = new Person("Robert Allen Zimmerman", "Harmonica Player") +// --- +``` + +{% endtab %} +{% endtabs %} + +Однако с [универсальными apply методами][creator] в Scala 3 этого больше не требуется: только в Scala 3. + +{% tabs class_3 %} +{% tab 'Только в Scala 3' %} + +```scala +val p = Person("Robert Allen Zimmerman", "Harmonica Player") +``` + +{% endtab %} +{% endtabs %} + +Если у вас есть экземпляр класса, такой как `p`, то вы можете получить доступ к полям экземпляра, +которые в этом примере являются параметрами конструктора: + +{% tabs class_4 %} +{% tab 'Scala 2 и 3' %} + +```scala +p.name // "Robert Allen Zimmerman" +p.vocation // "Harmonica Player" +``` + +{% endtab %} +{% endtabs %} + +Как уже упоминалось, все эти параметры были созданы как `var` поля, поэтому они изменяемые: + +{% tabs class_5 %} +{% tab 'Scala 2 и 3' %} + +```scala +p.name = "Bob Dylan" +p.vocation = "Musician" +``` + +{% endtab %} +{% endtabs %} + +### Поля и методы + +Классы также могут содержать методы и дополнительные поля, не являющиеся частью конструкторов. +Они определены в теле класса. +Тело инициализируется как часть конструктора по умолчанию: + +{% tabs method class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person(var firstName: String, var lastName: String) { + + println("initialization begins") + val fullName = firstName + " " + lastName + + // метод класса + def printFullName: Unit = + // обращение к полю `fullName`, определенному выше + println(fullName) + + printFullName + println("initialization ends") +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Person(var firstName: String, var lastName: String): + + println("initialization begins") + val fullName = firstName + " " + lastName + + // метод класса + def printFullName: Unit = + // обращение к полю `fullName`, определенному выше + println(fullName) + + printFullName + println("initialization ends") +``` + +{% endtab %} +{% endtabs %} + +Следующая сессия REPL показывает, как создать новый экземпляр `Person` с этим классом: + +{% tabs demo-person class=tabs-scala-version %} +{% tab 'Scala 2' %} +````scala +scala> val john = new Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` +{% endtab %} +{% tab 'Scala 3' %} +````scala +scala> val john = Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` +{% endtab %} +{% endtabs %} + +Классы также могут расширять трейты и абстрактные классы, которые мы рассмотрим в специальных разделах ниже. + +### Значения параметров по умолчанию + +В качестве беглого взгляда на некоторые другие функции, +параметры конструктора класса также могут иметь значения по умолчанию: + +{% tabs default-values_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000) { + override def toString = s"timeout: $timeout, linger: $linger" +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000): + override def toString = s"timeout: $timeout, linger: $linger" +``` + +{% endtab %} +{% endtabs %} + +Отличительной особенностью этой функции является то, что она позволяет потребителям вашего кода +создавать классы различными способами, как если бы у класса были альтернативные конструкторы: + +{% tabs default-values_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s = new Socket() // timeout: 5000, linger: 5000 +val s = new Socket(2_500) // timeout: 2500, linger: 5000 +val s = new Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = new Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = new Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s = Socket() // timeout: 5000, linger: 5000 +val s = Socket(2_500) // timeout: 2500, linger: 5000 +val s = Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% endtabs %} + +При создании нового экземпляра класса вы также можете использовать именованные параметры. +Это особенно полезно, когда несколько параметров имеют одинаковый тип, как показано в этом сравнении: + +{% tabs default-values_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// пример 1 +val s = new Socket(10_000, 10_000) + +// пример 2 +val s = new Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// пример 1 +val s = Socket(10_000, 10_000) + +// пример 2 +val s = Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% endtabs %} + +### Вспомогательные конструкторы + +Вы можете определить класс с несколькими конструкторами, +чтобы клиенты вашего класса могли создавать его различными способами. +Например, предположим, что вам нужно написать код для моделирования студентов в системе приема в колледж. +При анализе требований вы увидели, что необходимо создавать экземпляр `Student` тремя способами: + +- С именем и государственным удостоверением личности, когда они впервые начинают процесс приема +- С именем, государственным удостоверением личности и дополнительной датой подачи заявки, когда они подают заявку +- С именем, государственным удостоверением личности и студенческим билетом после того, как они будут приняты + +Один из способов справиться с этой ситуацией в стиле ООП - с помощью нижеследующего кода: + +{% tabs structor_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import java.time._ + +// [1] основной конструктор +class Student( + var name: String, + var govtId: String +) { + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] конструктор для студента, подавшего заявку + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = { + this(name, govtId) + _applicationDate = Some(applicationDate) + } + + // [3] конструктор, когда учащийся принят и теперь имеет студенческий билет + def this( + name: String, + govtId: String, + studentId: Int + ) = { + this(name, govtId) + _studentId = studentId + } +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import java.time.* + +// [1] основной конструктор +class Student( + var name: String, + var govtId: String +): + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] конструктор для студента, подавшего заявку + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = + this(name, govtId) + _applicationDate = Some(applicationDate) + + // [3] конструктор, когда учащийся принят и теперь имеет студенческий билет + def this( + name: String, + govtId: String, + studentId: Int + ) = + this(name, govtId) + _studentId = studentId +``` + +{% endtab %} +{% endtabs %} + +Класс содержит три конструктора, обозначенных комментариями в коде: + +1. Первичный конструктор, заданный `name` и `govtId` в определении класса +2. Вспомогательный конструктор с параметрами `name`, `govtId` и `applicationDate` +3. Другой вспомогательный конструктор с параметрами `name`, `govtId` и `studentId` + +Эти конструкторы можно вызывать следующим образом: + +{% tabs structor_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1 = new Student("Mary", "123") +val s2 = new Student("Mary", "123", LocalDate.now) +val s3 = new Student("Mary", "123", 456) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +val s1 = Student("Mary", "123") +val s2 = Student("Mary", "123", LocalDate.now) +val s3 = Student("Mary", "123", 456) +``` + +{% endtab %} +{% endtabs %} + +Хотя этот метод можно использовать, имейте в виду, что параметры конструктора также могут иметь значения по умолчанию, +из-за чего создается впечатление, что класс содержит несколько конструкторов. +Это показано в предыдущем примере `Socket`. + +## Объекты + +Объект — это класс, который имеет ровно один экземпляр. +Инициализируется он лениво, тогда, когда на его элементы ссылаются, подобно `lazy val`. +Объекты в Scala позволяют группировать методы и поля в одном пространстве имен, аналогично тому, +как вы используете `static` члены в классе в Java, Javascript (ES6) или `@staticmethod` в Python. + +Объявление `object` аналогично объявлению `class`. +Вот пример объекта “строковые утилиты”, который содержит набор методов для работы со строками: + +{% tabs object_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object StringUtils { + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +object StringUtils: + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +``` + +{% endtab %} +{% endtabs %} + +Мы можем использовать объект следующим образом: + +{% tabs object_2 %} +{% tab 'Scala 2 и 3' %} + +```scala +StringUtils.truncate("Chuck Bartowski", 5) // "Chuck" +``` + +{% endtab %} +{% endtabs %} + +Импорт в Scala очень гибкий и позволяет импортировать _все_ члены объекта: + +{% tabs object_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import StringUtils._ +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import StringUtils.* +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} +{% endtabs %} + +или только _некоторые_: + +{% tabs object_4 %} +{% tab 'Scala 2 и 3' %} + +```scala +import StringUtils.{truncate, containsWhitespace} +truncate("Charles Carmichael", 7) // "Charles" +containsWhitespace("Captain Awesome") // true +isNullOrEmpty("Morgan Grimes") // Not found: isNullOrEmpty (error) +``` + +{% endtab %} +{% endtabs %} + +Объекты также могут содержать поля, доступ к которым также осуществляется как к статическим элементам: + +{% tabs object_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object MathConstants { + val PI = 3.14159 + val E = 2.71828 +} + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +object MathConstants: + val PI = 3.14159 + val E = 2.71828 + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} +{% endtabs %} + +## Сопутствующие объекты + +Объект `object`, имеющий то же имя, что и класс, и объявленный в том же файле, что и класс, +называется _"сопутствующим объектом"_. Точно так же соответствующий класс называется сопутствующим классом объекта. +Сопутствующие класс или объект могут получить доступ к закрытым членам своего “соседа”. + +Сопутствующие объекты используются для методов и значений, не относящихся к экземплярам сопутствующего класса. +Например, в следующем примере у класса `Circle` есть элемент с именем `area`, специфичный для каждого экземпляра, +а у его сопутствующего объекта есть метод с именем `calculateArea`, +который (а) не специфичен для экземпляра и (б) доступен для каждого экземпляра: + +{% tabs companion class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.math._ + +class Circle(val radius: Double) { + def area: Double = Circle.calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = new Circle(5.0) +circle1.area +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +import scala.math.* + +class Circle(val radius: Double): + def area: Double = Circle.calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) + +val circle1 = Circle(5.0) +circle1.area +``` + +{% endtab %} +{% endtabs %} + +В этом примере метод `area`, доступный для каждого экземпляра `Circle`, +использует метод `calculateArea`, определенный в сопутствующем объекте. +Кроме того, поскольку `calculateArea` является приватным, к нему нельзя получить доступ с помощью другого кода, +но, как показано, его могут видеть экземпляры класса `Circle`. + +### Другие виды использования сопутствующих объектов + +Сопутствующие объекты могут использоваться для нескольких целей: + +- их можно использовать для группировки “статических” методов в пространстве имен, как в примере выше + - эти методы могут быть `public` или `private` + - если бы `calculateArea` был `public`, к нему можно было бы получить доступ из любого места как `Circle.calculateArea` +- они могут содержать методы `apply`, которые — благодаря некоторому синтаксическому сахару — + работают как фабричные методы для создания новых экземпляров +- они могут содержать методы `unapply`, которые используются для деконструкции объектов, например, с помощью сопоставления с шаблоном + +Вот краткий обзор того, как методы `apply` можно использовать в качестве фабричных методов для создания новых объектов: + +{% tabs companion-use class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person { + var name = "" + var age = 0 + override def toString = s"$name is $age years old" +} + +object Person { + // фабричный метод с одним аргументом + def apply(name: String): Person = { + var p = new Person + p.name = name + p + } + + // фабричный метод с двумя аргументами + def apply(name: String, age: Int): Person = { + var p = new Person + p.name = name + p.age = age + p + } +} + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +Метод `unapply` здесь не рассматривается, но описан в [Спецификации языка](https://scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns). + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class Person: + var name = "" + var age = 0 + override def toString = s"$name is $age years old" + +object Person: + + // фабричный метод с одним аргументом + def apply(name: String): Person = + var p = new Person + p.name = name + p + + // фабричный метод с двумя аргументами + def apply(name: String, age: Int): Person = + var p = new Person + p.name = name + p.age = age + p + +end Person + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +Метод `unapply` здесь не рассматривается, но описан в [справочной документации]({{ site.scala3ref }}/changed-features/pattern-matching.html). + +{% endtab %} +{% endtabs %} + +## Трейты + +Если провести аналогию с Java, то Scala `trait` похож на интерфейс в Java 8+. +Trait-ы могут содержать: + +- абстрактные методы и поля +- конкретные методы и поля + +В базовом использовании `trait` может использоваться как интерфейс, определяющий только абстрактные члены, +которые будут реализованы другими классами: + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Employee { + def id: Int + def firstName: String + def lastName: String +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait Employee: + def id: Int + def firstName: String + def lastName: String +``` + +{% endtab %} +{% endtabs %} + +Однако трейты также могут содержать конкретные члены. +Например, следующий трейт определяет два абстрактных члена — `numLegs` и `walk()` — +а также имеет конкретную реализацию метода `stop()`: + +{% tabs traits_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasLegs { + def numLegs: Int + def walk(): Unit + def stop() = println("Stopped walking") +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait HasLegs: + def numLegs: Int + def walk(): Unit + def stop() = println("Stopped walking") +``` + +{% endtab %} +{% endtabs %} + +Вот еще один трейт с абстрактным членом и двумя конкретными реализациями: + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasTail { + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +trait HasTail: + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что каждый трейт обрабатывает только очень специфичные атрибуты и поведение: +`HasLegs` имеет дело только с "лапами", а `HasTail` имеет дело только с функциональностью, связанной с хвостом. +Трейты позволяют создавать такие небольшие модули. + +Позже в вашем коде классы могут смешивать несколько трейтов для создания более крупных компонентов: + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class IrishSetter(name: String) extends HasLegs with HasTail { + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +class IrishSetter(name: String) extends HasLegs, HasTail: + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что класс `IrishSetter` реализует абстрактные члены, определенные в `HasLegs` и `HasTail`. +Теперь вы можете создавать новые экземпляры `IrishSetter`: + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val d = new IrishSetter("Big Red") // "Big Red is a Dog" +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val d = IrishSetter("Big Red") // "Big Red is a Dog" +``` + +{% endtab %} +{% endtabs %} + +Это всего лишь пример того, чего можно добиться с помощью trait-ов. +Дополнительные сведения см. в остальных уроках по моделированию. + +## Абстрактные классы + +Когда необходимо написать класс, но известно, что в нем будут абстрактные члены, можно создать либо `trait`, либо абстрактный класс. +В большинстве случаев желательно использовать `trait`, но исторически сложилось так, что было две ситуации, +когда предпочтительнее использование абстрактного класса: + +- необходимо создать базовый класс, который принимает аргументы конструктора +- код будет вызван из Java-кода + +### Базовый класс, который принимает аргументы конструктора + +До Scala 3, когда базовому классу нужно было принимать аргументы конструктора, он объявлялся как `abstract class`: + +{% tabs abstract_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +abstract class Pet(name: String) { + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" +} + +class Dog(name: String, var age: Int) extends Pet(name) { + val greeting = "Woof" +} + +val d = new Dog("Fido", 1) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +abstract class Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, var age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +Параметры в trait только в Scala 3
+ +Однако в Scala 3 трейты теперь могут иметь [параметры][trait-params], +так что теперь вы можете использовать трейты в той же ситуации: + +{% tabs abstract_2 %} + +{% tab 'Только в Scala 3' %} + +```scala +trait Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, var age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +Trait-ы более гибки в составлении, потому что можно смешивать (наследовать) несколько trait-ов, но только один класс. +В большинстве случаев trait-ы следует предпочитать классам и абстрактным классам. +Правило выбора состоит в том, чтобы использовать классы всякий раз, когда необходимо создавать экземпляры определенного типа, +и trait-ы, когда желательно разложить и повторно использовать поведение. + +Перечисления только в Scala 3
+ +Перечисление (_an enumeration_) может быть использовано для определения типа, +состоящего из конечного набора именованных значений (в разделе, посвященном [моделированию ФП][fp-modeling], +будут показаны дополнительные возможности перечислений). +Базовые перечисления используются для определения наборов констант, +таких как месяцы в году, дни в неделе, направления, такие как север/юг/восток/запад, и многое другое. + +В качестве примера, рассмотрим перечисления, определяющие наборы атрибутов, связанных с пиццами: + +{% tabs enum_1 %} +{% tab 'Только в Scala 3' %} + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +Для использования в коде в первую очередь перечисление нужно импортировать, а затем - использовать: + +{% tabs enum_2 %} +{% tab 'Только в Scala 3' %} + +```scala +import CrustSize.* +val currentCrustSize = Small +``` + +{% endtab %} +{% endtabs %} + +Значения перечислений можно сравнивать (`==`) и использовать в сопоставлении: + +{% tabs enum_3 %} +{% tab 'Только в Scala 3' %} + +```scala +// if/then +if currentCrustSize == Large then + println("You get a prize!") + +// match +currentCrustSize match + case Small => println("small") + case Medium => println("medium") + case Large => println("large") +``` + +{% endtab %} +{% endtabs %} + +### Дополнительные функции перечисления + +Перечисления также могут быть параметризованы: + +{% tabs enum_4 %} +{% tab 'Только в Scala 3' %} + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` + +{% endtab %} +{% endtabs %} + +И они также могут содержать элементы (например, поля и методы): + +{% tabs enum_5 %} +{% tab 'Только в Scala 3' %} + +```scala +enum Planet(mass: Double, radius: Double): + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = + otherMass * surfaceGravity + + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Earth extends Planet(5.976e+24, 6.37814e6) + // далее идут остальные планеты ... +``` + +{% endtab %} +{% endtabs %} + +### Совместимость с перечислениями Java + +Если вы хотите использовать перечисления, определенные в Scala, как перечисления Java, +то можете сделать это, расширив класс `java.lang.Enum` (импортированный по умолчанию) следующим образом: + +{% tabs enum_6 %} +{% tab 'Только в Scala 3' %} + +```scala +enum Color extends Enum[Color] { case Red, Green, Blue } +``` + +{% endtab %} +{% endtabs %} + +Параметр типа берется из определения Java `enum` и должен совпадать с типом перечисления. +Нет необходимости предоставлять аргументы конструктора (как определено в документации Java API) для `java.lang.Enum` +при его расширении — компилятор генерирует их автоматически. + +После такого определения `Color` вы можете использовать его так же, как перечисление Java: + +```` +scala> Color.Red.compareTo(Color.Green) +val res0: Int = -1 +```` + +В разделе об [алгебраических типах данных][adts] и [справочной документации][ref-enums] перечисления рассматриваются более подробно. + +## Case class-ы + +Case class используются для моделирования неизменяемых структур данных. +Возьмем следующий пример: + +{% tabs case-classes_1 %} +{% tab 'Scala 2 и 3' %} + +```scala: +case class Person(name: String, relation: String) +``` + +{% endtab %} +{% endtabs %} + +Поскольку мы объявляем `Person` как `case class`, поля `name` и `relation` по умолчанию общедоступны и неизменяемы. +Мы можем создавать экземпляры case классов следующим образом: + +{% tabs case-classes_2 %} +{% tab 'Scala 2 и 3' %} + +```scala +val christina = Person("Christina", "niece") +``` + +{% endtab %} +{% endtabs %} + +Обратите внимание, что поля не могут быть изменены: + +{% tabs case-classes_3 %} +{% tab 'Scala 2 и 3' %} + +```scala +christina.name = "Fred" // ошибка: reassignment to val +``` + +{% endtab %} +{% endtabs %} + +Поскольку предполагается, что поля case класса неизменяемы, +компилятор Scala может сгенерировать для вас множество полезных методов: + +- Генерируется метод `unapply`, позволяющий выполнять сопоставление с образцом case класса (то есть `case Person(n, r) => ...`). +- В классе генерируется метод `copy`, полезный для создания модифицированных копий экземпляра. +- Генерируются методы `equals` и `hashCode`, использующие структурное равенство, + что позволяет использовать экземпляры case классов в `Map`-ах. +- Генерируется дефолтный метод `toString`, полезный для отладки. + +Эти дополнительные функции показаны в следующем примере: + +{% tabs case-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// Case class-ы можно использовать в качестве шаблонов +christina match { + case Person(n, r) => println("name is " + n) +} + +// для вас генерируются методы `equals` и `hashCode` +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// метод `toString` +println(christina) // Person(Christina,niece) + +// встроенный метод `copy` +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// в результате: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) + +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +// Case class-ы можно использовать в качестве шаблонов +christina match + case Person(n, r) => println("name is " + n) + +// для вас генерируются методы `equals` и `hashCode` +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// метод `toString` +println(christina) // Person(Christina,niece) + +// встроенный метод `copy` +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// в результате: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) +``` + +{% endtab %} +{% endtabs %} + +### Поддержка функционального программирования + +Как уже упоминалось ранее, case class-ы поддерживают функциональное программирование (ФП): + +- ФП избегает изменения структур данных. + Поэтому поля конструктора по умолчанию имеют значение `val`. + Поскольку экземпляры case class не могут быть изменены, ими можно легко делиться, не опасаясь мутаций или условий гонки. +- вместо изменения экземпляра можно использовать метод `copy` в качестве шаблона для создания нового (потенциально измененного) экземпляра. + Этот процесс можно назвать “обновлением по мере копирования”. +- наличие автоматически сгенерированного метода `unapply` позволяет использовать case class в сопоставлении шаблонов. + +## Case object-ы + +Case object-ы относятся к объектам так же, как case class-ы относятся к классам: +они предоставляют ряд автоматически генерируемых методов, чтобы сделать их более мощными. +Case object-ы особенно полезны тогда, когда необходим одноэлементный объект, +который нуждается в небольшой дополнительной функциональности, +например, для использования с сопоставлением шаблонов в выражениях `match`. + +Case object-ы полезны, когда необходимо передавать неизменяемые сообщения. +Например, представим проект музыкального проигрывателя, и создадим набор команд или сообщений: + +{% tabs case-objects_1 %} +{% tab 'Scala 2 и 3' %} + +```scala +sealed trait Message +case class PlaySong(name: String) extends Message +case class IncreaseVolume(amount: Int) extends Message +case class DecreaseVolume(amount: Int) extends Message +case object StopPlaying extends Message +``` + +{% endtab %} +{% endtabs %} + +Затем в других частях кода можно написать методы, которые используют сопоставление с образцом +для обработки входящего сообщения +(при условии, что методы `playSong`, `changeVolume` и `stopPlayingSong` определены где-то еще): + +{% tabs case-objects_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def handleMessages(message: Message): Unit = message match { + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +} +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +def handleMessages(message: Message): Unit = message match + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +``` + +{% endtab %} +{% endtabs %} + +[ref-enums]: {{ site.scala3ref }}/enums/enums.html +[adts]: {% link _overviews/scala3-book/types-adts-gadts.md %} +[fp-modeling]: {% link _overviews/scala3-book/domain-modeling-fp.md %} +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[unapply]: {{ site.scala3ref }}/changed-features/pattern-matching.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_ru/scala3/book/first-look-at-types.md b/_ru/scala3/book/first-look-at-types.md new file mode 100644 index 0000000000..5873df07f7 --- /dev/null +++ b/_ru/scala3/book/first-look-at-types.md @@ -0,0 +1,354 @@ +--- +layout: multipage-overview +title: Первый взгляд на типы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: На этой странице представлено краткое введение во встроенные типы данных Scala, включая Int, Double, String, Long, Any, AnyRef, Nothing и Null. +language: ru +num: 17 +previous-page: taste-summary +next-page: string-interpolation +--- + +## Все значения имеют тип + +В Scala все значения имеют тип, включая числовые значения и функции. +На приведенной ниже диаграмме показано подмножество иерархии типов. + +
+
+## Иерархия типов Scala
+
+`Any` - это супертип всех типов, также называемый **верхним типом** (**the top type**).
+Он определяет универсальные методы, такие как `equals`, `hashCode` и `toString`.
+
+У верхнего типа `Any` есть подтип [`Matchable`][matchable], который используется для обозначения всех типов,
+для которых возможно выполнить pattern matching (сопоставление с образцом).
+Важно гарантировать вызов свойства _“параметричность”_, что вкратце означает,
+что мы не можем сопоставлять шаблоны для значений типа `Any`, а только для значений, которые являются подтипом `Matchable`.
+[Справочная документация][matchable] содержит более подробную информацию о `Matchable`.
+
+`Matchable` содержит два важных подтипа: `AnyVal` и `AnyRef`.
+
+_`AnyVal`_ представляет типы значений.
+Существует несколько предопределенных типов значений, и они non-nullable:
+`Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit` и `Boolean`.
+`Unit` - это тип значения, который не несет никакой значимой информации. Существует ровно один экземпляр `Unit` - `()`.
+
+_`AnyRef`_ представляет ссылочные типы. Все типы, не являющиеся значениями, определяются как ссылочные типы.
+Каждый пользовательский тип в Scala является подтипом `AnyRef`.
+Если Scala используется в контексте среды выполнения Java, `AnyRef` соответствует `java.lang.Object`.
+
+В языках, основанных на операторах, `void` используется для методов, которые ничего не возвращают.
+В Scala для методов, которые не имеют возвращаемого значения,
+такие как следующий метод, для той же цели используется `Unit`:
+
+{% tabs unit %}
+{% tab 'Scala 2 и 3' for=unit %}
+
+```scala
+def printIt(a: Any): Unit = println(a)
+```
+
+{% endtab %}
+{% endtabs %}
+
+Вот пример, демонстрирующий, что строки, целые числа, символы, логические значения и функции являются экземплярами `Any`
+и могут обрабатываться так же, как и любой другой объект:
+
+{% tabs any %}
+{% tab 'Scala 2 и 3' for=any %}
+
+```scala
+val list: List[Any] = List(
+ "a string",
+ 732, // число
+ 'c', // буква
+ '\'', // Экранированный символ
+ true, // булево значение
+ () => "an anonymous function returning a string"
+)
+
+list.foreach(element => println(element))
+```
+
+{% endtab %}
+{% endtabs %}
+
+Код определяет список значений типа `List[Any]`.
+Список инициализируется элементами различных типов, но каждый из них является экземпляром `scala.Any`,
+поэтому мы можем добавить их в список.
+
+Вот вывод программы:
+
+```
+a string
+732
+c
+'
+true
+от -128 до 127 | +| Short | 16-битное целое число в дополнении до двух со знаком (от -2^15 до 2^15-1 включительно)
от -32 768 до 32 767 | +| Int | 32-битное целое число с дополнением до двух со знаком (от -2^31 до 2^31-1 включительно)
от -2 147 483 648 до 2 147 483 647 | +| Long | 64-битное целое число с дополнением до двух со знаком (от -2^63 до 2^63-1 включительно)
(от -2^63 до 2^63-1 включительно) | +| Float | 32-разрядный IEEE 754 одинарной точности с плавающей точкой
от 1,40129846432481707e-45 до 3,40282346638528860e+38 | +| Double | 64-битный IEEE 754 двойной точности с плавающей запятой
от 4,94065645841246544e-324 до 1,79769313486231570e+308 | +| Char | 16-битный символ Unicode без знака (от 0 до 2^16-1 включительно)
от 0 до 65 535 | +| String | последовательность `Char` | + +## Строки + +Строки Scala похожи на строки Java, +хотя в отличие от Java (по крайней мере, до Java 15) +в Scala легко создавать многострочные строки с тройными кавычками: + +{% tabs string-mlines1 %} +{% tab 'Scala 2 и 3' for=string-mlines1 %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` + +{% endtab %} +{% endtabs %} + +Одним из недостатков этого базового подхода является то, +что строки после первой строки содержат отступ и выглядят следующим образом: + +{% tabs string-mlines2 %} +{% tab 'Scala 2 и 3' for=string-mlines2 %} + +```scala +"The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +Если важно исключить отступ, можно поставить символ `|` перед всеми строками после первой +и вызвать метод `stripMargin` после строки: + +{% tabs string-mlines3 %} +{% tab 'Scala 2 и 3' for=string-mlines3 %} + +```scala +val quote = """The essence of Scala: + |Fusion of functional and object-oriented + |programming in a typed setting.""".stripMargin +``` + +{% endtab %} +{% endtabs %} + +Теперь все строки выравниваются по левому краю: + +{% tabs string-mlines4 %} +{% tab 'Scala 2 и 3' for=string-mlines4 %} + +```scala +"The essence of Scala: +Fusion of functional and object-oriented +programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +Строки Scala также поддерживают мощные методы интерполяции строк, +о которых мы поговорим [в следующей главе][string-interpolation]. + +## `BigInt` и `BigDecimal` + +Для действительно больших чисел можно использовать типы `BigInt` и `BigDecimal`: + +{% tabs type-bigint %} +{% tab 'Scala 2 и 3' for=type-bigint %} + +```scala +val a = BigInt(1_234_567_890_987_654_321L) +val b = BigDecimal(123456.789) +``` + +{% endtab %} +{% endtabs %} + +Где `Double` и `Float` являются приблизительными десятичными числами, +а `BigDecimal` используется для точной арифметики, например, при работе с валютой. + +`BigInt` и `BigDecimal` поддерживают все привычные числовые операторы: + +{% tabs type-bigint2 %} +{% tab 'Scala 2 и 3' for=type-bigint2 %} + +```scala +val b = BigInt(1234567890) // scala.math.BigInt = 1234567890 +val c = b + b // scala.math.BigInt = 2469135780 +val d = b * b // scala.math.BigInt = 1524157875019052100 +``` + +{% endtab %} +{% endtabs %} + +## Приведение типов + +Типы значений могут быть приведены следующим образом: + +
+
+Например:
+
+{% tabs cast1 %}
+{% tab 'Scala 2 и 3' for=cast1 %}
+
+```scala
+val b: Byte = 127
+val i: Int = b // 127
+
+val face: Char = '☺'
+val number: Int = face // 9786
+```
+
+{% endtab %}
+{% endtabs %}
+
+Вы можете привести к типу, только если нет потери информации.
+В противном случае вам нужно четко указать приведение типов:
+
+{% tabs cast2 %}
+{% tab 'Scala 2 и 3' for=cast2 %}
+
+```scala
+val x: Long = 987654321
+val y: Float = x.toFloat // 9.8765434E8 (обратите внимание, что требуется `.toFloat`, потому что приведение приводит к потере точности)
+val z: Long = y // Ошибка
+```
+
+{% endtab %}
+{% endtabs %}
+
+Вы также можете привести ссылочный тип к подтипу.
+Это будет рассмотрено в книге позже.
+
+## `Nothing` и `null`
+
+`Nothing` является подтипом всех типов, также называемым **нижним типом** (**the bottom type**).
+Нет значения, которое имело бы тип `Nothing`.
+Он обычно сигнализирует о прекращении, таком как thrown exception, выходе из программы или бесконечном цикле -
+т.е. это тип выражения, который не вычисляется до определенного значения, или метод, который нормально не возвращается.
+
+`Null` - это подтип всех ссылочных типов (т.е. любой подтип `AnyRef`).
+Он имеет единственное значение, определяемое ключевым словом `null`.
+В настоящее время применение `null` считается плохой практикой.
+Его следует использовать в основном для взаимодействия с другими языками JVM.
+Опция компилятора `opt-in` изменяет статус `Null`, делая все ссылочные типы non-nullable.
+Этот параметр может [стать значением по умолчанию][safe-null] в будущей версии Scala.
+
+В то же время `null` почти никогда не следует использовать в коде Scala.
+Альтернативы `null` обсуждаются в главе о [функциональном программировании][fp] и в [документации API][option-api].
+
+[reference]: {{ site.scala3ref }}/overview.html
+[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html
+[fp]: {% link _overviews/scala3-book/fp-intro.md %}
+[string-interpolation]: {% link _overviews/scala3-book/string-interpolation.md %}
+[option-api]: https://scala-lang.org/api/3.x/scala/Option.html
+[safe-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html
diff --git a/_ru/scala3/book/fp-functional-error-handling.md b/_ru/scala3/book/fp-functional-error-handling.md
new file mode 100644
index 0000000000..ca3f7857eb
--- /dev/null
+++ b/_ru/scala3/book/fp-functional-error-handling.md
@@ -0,0 +1,436 @@
+---
+layout: multipage-overview
+title: Функциональная обработка ошибок
+scala3: true
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+type: section
+description: В этом разделе представлено введение в функциональную обработку ошибок в Scala 3.
+language: ru
+num: 46
+previous-page: fp-functions-are-values
+next-page: fp-summary
+---
+
+
+
+Функциональное программирование похоже на написание ряда алгебраических уравнений,
+и поскольку алгебра не имеет null значений или исключений, они не используются и в ФП.
+Что поднимает интересный вопрос: как быть в ситуациях, в которых вы обычно используете null значение или исключение программируя в ООП стиле?
+
+Решение Scala заключается в использовании конструкций, основанных на классах типа `Option`/`Some`/`None`.
+Этот урок представляет собой введение в использование такого подхода.
+
+Примечание:
+
+- классы `Some` и `None` являются подклассами `Option`
+- вместо того чтобы многократно повторять “`Option`/`Some`/`None`”,
+ следующий текст обычно просто ссылается на “`Option`” или на “классы `Option`”
+
+
+## Первый пример
+
+Хотя этот первый пример не имеет дело с `null` значениями, это хороший способ познакомиться с классами `Option`.
+
+Представим, что нужно написать метод, который упрощает преобразование строк в целочисленные значения.
+И нужен элегантный способ обработки исключения, которое возникает,
+когда метод получает строку типа `"Hello"` вместо `"1"`.
+Первое предположение о таком методе может выглядеть следующим образом:
+
+{% tabs fp-java-try class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+def makeInt(s: String): Int =
+ try {
+ Integer.parseInt(s.trim)
+ } catch {
+ case e: Exception => 0
+ }
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def makeInt(s: String): Int =
+ try
+ Integer.parseInt(s.trim)
+ catch
+ case e: Exception => 0
+```
+{% endtab %}
+
+{% endtabs %}
+
+Если преобразование работает, метод возвращает правильное значение `Int`, но в случае сбоя метод возвращает `0`.
+Для некоторых целей это может быть хорошо, но не совсем точно.
+Например, метод мог получить `"0"`, но мог также получить `"foo"`, `"bar"`
+или бесконечное количество других строк, которые выдадут исключение.
+Это реальная проблема: как определить, когда метод действительно получил `"0"`, а когда получил что-то еще?
+При таком подходе нет способа узнать правильный ответ наверняка.
+
+
+## Использование Option/Some/None
+
+Распространенным решением этой проблемы в Scala является использование классов,
+известных как `Option`, `Some` и `None`.
+Классы `Some` и `None` являются подклассами `Option`, поэтому решение работает следующим образом:
+
+- объявляется, что `makeInt` возвращает тип `Option`
+- если `makeInt` получает строку, которую он _может_ преобразовать в `Int`, ответ помещается внутрь `Some`
+- если `makeInt` получает строку, которую _не может_ преобразовать, то возвращает `None`
+
+Вот доработанная версия `makeInt`:
+
+{% tabs fp--try-option class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+def makeInt(s: String): Option[Int] =
+ try {
+ Some(Integer.parseInt(s.trim))
+ } catch {
+ case e: Exception => None
+ }
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def makeInt(s: String): Option[Int] =
+ try
+ Some(Integer.parseInt(s.trim))
+ catch
+ case e: Exception => None
+```
+{% endtab %}
+
+{% endtabs %}
+
+Этот код можно прочитать следующим образом:
+“Когда данная строка преобразуется в целое число, верните значение `Int`, заключенное в `Some`, например `Some(1)`.
+Когда строка не может быть преобразована в целое число и генерируется исключение, метод возвращает значение `None`.”
+
+Эти примеры показывают, как работает `makeInt`:
+
+{% tabs fp-try-option-example %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+val a = makeInt("1") // Some(1)
+val b = makeInt("one") // None
+```
+{% endtab %}
+
+{% endtabs %}
+
+Как показано, строка `"1"` приводится к `Some(1)`, а строка `"one"` - к `None`.
+В этом суть альтернативного подхода к обработке ошибок.
+Данная техника используется для того, чтобы методы могли возвращать _значения_ вместо _исключений_.
+В других ситуациях значения `Option` также используются для замены `null` значений.
+
+Примечание:
+
+- этот подход используется во всех классах библиотеки Scala, а также в сторонних библиотеках Scala.
+- ключевым моментом примера является то, что функциональные методы не генерируют исключения;
+ вместо этого они возвращают такие значения, как `Option`.
+
+
+## Потребитель makeInt
+
+Теперь представим, что мы являемся потребителем метода `makeInt`.
+Известно, что он возвращает подкласс `Option[Int]`, поэтому возникает вопрос:
+как работать с такими возвращаемыми типами?
+
+Есть два распространенных ответа, в зависимости от потребностей:
+
+- использование `match` выражений
+- использование `for` выражений
+
+## Использование `match` выражений
+
+Одним из возможных решений является использование выражения `match`:
+
+{% tabs fp-option-match class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+makeInt(x) match {
+ case Some(i) => println(i)
+ case None => println("That didn’t work.")
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+makeInt(x) match
+ case Some(i) => println(i)
+ case None => println("That didn’t work.")
+```
+{% endtab %}
+
+{% endtabs %}
+
+В этом примере, если `x` можно преобразовать в `Int`, вычисляется первый вариант в правой части предложения `case`;
+если `x` не может быть преобразован в `Int`, вычисляется второй вариант в правой части предложения `case`.
+
+
+## Использование `for` выражений
+
+Другим распространенным решением является использование выражения `for`, то есть комбинации `for`/`yield`.
+Например, представим, что необходимо преобразовать три строки в целочисленные значения, а затем сложить их.
+Решение задачи с использованием выражения `for`:
+
+{% tabs fp-for-comprehension class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+
+{% endtabs %}
+
+После выполнения этого выражения `y` может принять одно из двух значений:
+
+- если _все_ три строки конвертируются в значения `Int`, `y` будет равно `Some[Int]`, т.е. целым числом, обернутым внутри `Some`
+- если _какая-либо_ из трех строк не может быть преобразована в `Int`, `y` равен `None`
+
+Это можно проверить на примере:
+
+{% tabs fp-for-comprehension-evaluation class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+val stringA = "1"
+val stringB = "2"
+val stringC = "3"
+
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val stringA = "1"
+val stringB = "2"
+val stringC = "3"
+
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+
+{% endtabs %}
+
+С этими демонстрационными данными переменная `y` примет значение `Some(6)`.
+
+Чтобы увидеть негативный кейс, достаточно изменить любую из строк на что-то, что нельзя преобразовать в целое число.
+В этом случае `y` равно `None`:
+
+{% tabs fp-for-comprehension-failure-result %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+y: Option[Int] = None
+```
+{% endtab %}
+
+{% endtabs %}
+
+
+## Восприятие Option, как контейнера
+
+Для лучшего восприятия `Option`, его можно представить как _контейнер_:
+
+- `Some` представляет собой контейнер с одним элементом
+- `None` не является контейнером, в нем ничего нет
+
+Если предпочтительнее думать об `Option` как о ящике, то `None` подобен пустому ящику.
+Что-то в нём могло быть, но нет.
+
+
+## Использование `Option` для замены `null`
+
+Возвращаясь к значениям `null`, место, где `null` значение может незаметно проникнуть в код, — класс, подобный этому:
+
+{% tabs fp=case-class-nulls %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+class Address(
+ var street1: String,
+ var street2: String,
+ var city: String,
+ var state: String,
+ var zip: String
+)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Хотя каждый адрес имеет значение `street1`, значение `street2` не является обязательным.
+В результате полю `street2` можно присвоить значение `null`:
+
+{% tabs fp-case-class-nulls-example class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "1 Main Street",
+ null, // <-- О! Значение null!
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "1 Main Street",
+ null, // <-- О! Значение null!
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Исторически сложилось так, что в этой ситуации разработчики использовали пустые строки и значения `null`,
+оба варианта это “костыль” для решения основной проблемы: `street2` - _необязательное_ поле.
+В Scala и других современных языках правильное решение состоит в том,
+чтобы заранее объявить, что `street2` является необязательным:
+
+
+{% tabs fp-case-class-with-options %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+class Address(
+ var street1: String,
+ var street2: Option[String], // необязательное значение
+ var city: String,
+ var state: String,
+ var zip: String
+)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Теперь можно написать более точный код:
+
+{% tabs fp-case-class-with-options-example-none class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "1 Main Street",
+ None, // 'street2' не имеет значения
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "1 Main Street",
+ None, // 'street2' не имеет значения
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% endtabs %}
+
+или так:
+
+{% tabs fp-case-class-with-options-example-some class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "123 Main Street",
+ Some("Apt. 2B"),
+ "Talkeetna",
+ "Alaska",
+ "99676"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "123 Main Street",
+ Some("Apt. 2B"),
+ "Talkeetna",
+ "Alaska",
+ "99676"
+)
+```
+{% endtab %}
+
+{% endtabs %}
+
+
+
+## `Option` — не единственное решение
+
+В этом разделе основное внимание уделялось `Option` классам, но у Scala есть несколько других альтернатив.
+
+Например, три класса, известные как `Try`/`Success`/`Failure`, работают также,
+но (а) эти классы в основном используются, когда код может генерировать исключения,
+и (б) когда желательно использовать класс `Failure`, потому что он дает доступ к сообщению об исключении.
+Например, классы `Try` обычно используются при написании методов, которые взаимодействуют с файлами,
+базами данных или интернет-службами, поскольку эти функции могут легко создавать исключения.
+
+
+## Краткое ревью
+
+Этот раздел был довольно большим, поэтому давайте подведем краткое ревью:
+
+- функциональные программисты не используют `null` значения
+- основной заменой `null` значениям является использование классов `Option`
+- функциональные методы не выдают исключений; вместо этого они возвращают такие значения, как `Option`, `Try` или `Either`
+- распространенными способами работы со значениями `Option` являются выражения `match` и `for`
+- `Option` можно рассматривать как контейнеры с одним элементом (`Some`) и без элементов (`None`)
+- `Option` также можно использовать для необязательных параметров конструктора или метода
diff --git a/_ru/scala3/book/fp-functions-are-values.md b/_ru/scala3/book/fp-functions-are-values.md
new file mode 100644
index 0000000000..9a6cd6c423
--- /dev/null
+++ b/_ru/scala3/book/fp-functions-are-values.md
@@ -0,0 +1,161 @@
+---
+layout: multipage-overview
+title: Функции — это значения
+scala3: true
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+type: section
+description: В этом разделе рассматривается использование функций в качестве значений в функциональном программировании.
+language: ru
+num: 45
+previous-page: fp-pure-functions
+next-page: fp-functional-error-handling
+---
+
+
+Хотя каждый когда-либо созданный язык программирования, вероятно, позволяет писать чистые функции,
+вторая важная особенность ФП на Scala заключается в том, что _функции можно создавать как значения_,
+точно так же, как создаются значения `String` и `Int`.
+
+Эта особенность даёт много преимуществ, опишем наиболее распространенные из них:
+(a) можно определять методы, принимающие в качестве параметров функции
+и (b) можно передавать функции в качестве параметров в методы.
+
+Такой подход можно было наблюдать в предыдущих главах, когда демонстрировались такие методы, как `map` и `filter`:
+
+{% tabs fp-function-as-values-anonymous %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+val nums = (1 to 10).toList
+
+val doubles = nums.map(_ * 2) // удваивает каждое значение
+val lessThanFive = nums.filter(_ < 5) // List(1,2,3,4)
+```
+{% endtab %}
+
+{% endtabs %}
+
+В этих примерах анонимные функции передаются в `map` и `filter`.
+
+> Анонимные функции также известны как _лямбды_ (_lambdas_).
+
+Помимо передачи анонимных функций в `filter` и `map`, в них также можно передать _методы_:
+
+{% tabs fp-function-as-values-defined %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+// два метода
+def double(i: Int): Int = i * 2
+def underFive(i: Int): Boolean = i < 5
+
+// передача этих методов в filter и map
+val doubles = nums.filter(underFive).map(double)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Возможность обращаться с методами и функциями как со значениями — мощное свойство,
+предоставляемое языками функционального программирования.
+
+> Технически функция, которая принимает другую функцию в качестве входного параметра, известна как _функция высшего порядка_.
+> (Если вам нравится юмор, как кто-то однажды написал, это все равно, что сказать,
+> что класс, который принимает экземпляр другого класса в качестве параметра конструктора,
+> является классом высшего порядка.)
+
+
+## Функции, анонимные функции и методы
+
+В примерах выше анонимная функция это:
+
+{% tabs fp-anonymous-function-short %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+_ * 2
+```
+{% endtab %}
+
+{% endtabs %}
+
+Как было показано в обсуждении [функций высшего порядка][hofs], `_ * 2` - сокращенная версия синтаксиса:
+
+{% tabs fp-anonymous-function-full %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+(i: Int) => i * 2
+```
+{% endtab %}
+
+{% endtabs %}
+
+Такие функции называются “анонимными”, потому что им не присваивается определенное имя.
+Для того чтобы это имя задать, достаточно просто присвоить его переменной:
+
+{% tabs fp-function-assignement %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+val double = (i: Int) => i * 2
+```
+{% endtab %}
+
+{% endtabs %}
+
+Теперь появилась именованная функция, назначенная переменной `double`.
+Можно использовать эту функцию так же, как используется метод:
+
+{% tabs fp-function-used-like-method %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+double(2) // 4
+```
+{% endtab %}
+
+{% endtabs %}
+
+В большинстве случаев не имеет значения, является ли `double` функцией или методом;
+Scala позволяет обращаться с ними одинаково.
+За кулисами технология Scala, которая позволяет обращаться с методами так же,
+как с функциями, известна как [Eta Expansion][eta].
+
+Эта способность беспрепятственно передавать функции в качестве переменных
+является отличительной чертой функциональных языков программирования, таких как Scala.
+И, как было видно на примерах `map` и `filter`,
+возможность передавать функции в другие функции помогает создавать код,
+который является кратким и при этом читабельным — _выразительным_.
+
+Вот еще несколько примеров:
+
+{% tabs fp-function-as-values-example %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+List("bob", "joe").map(_.toUpperCase) // List(BOB, JOE)
+List("bob", "joe").map(_.capitalize) // List(Bob, Joe)
+List("plum", "banana").map(_.length) // List(4, 6)
+
+val fruits = List("apple", "pear")
+fruits.map(_.toUpperCase) // List(APPLE, PEAR)
+fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R)
+
+val nums = List(5, 1, 3, 11, 7)
+nums.map(_ * 2) // List(10, 2, 6, 22, 14)
+nums.filter(_ > 3) // List(5, 11, 7)
+nums.takeWhile(_ < 6) // List(5, 1, 3)
+nums.sortWith(_ < _) // List(1, 3, 5, 7, 11)
+nums.sortWith(_ > _) // List(11, 7, 5, 3, 1)
+
+nums.takeWhile(_ < 6).sortWith(_ < _) // List(1, 3, 5)
+```
+{% endtab %}
+
+{% endtabs %}
+
+
+[hofs]: {% link _overviews/scala3-book/fun-hofs.md %}
+[eta]: {% link _overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_ru/scala3/book/fp-immutable-values.md b/_ru/scala3/book/fp-immutable-values.md
new file mode 100644
index 0000000000..53f63d0b26
--- /dev/null
+++ b/_ru/scala3/book/fp-immutable-values.md
@@ -0,0 +1,109 @@
+---
+layout: multipage-overview
+title: Неизменяемые значения
+scala3: true
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+type: section
+description: В этом разделе рассматривается использование неизменяемых значений в функциональном программировании.
+language: ru
+num: 43
+previous-page: fp-what-is-fp
+next-page: fp-pure-functions
+---
+
+В чистом функциональном программировании используются только неизменяемые значения.
+В Scala это означает:
+
+- все переменные создаются как поля `val`
+- используются только неизменяемые классы коллекций, такие как `List`, `Vector` и неизменяемые классы `Map` и `Set`
+
+Использование только неизменяемых переменных поднимает интересный вопрос: если все статично, как вообще что-то меняется?
+
+Когда дело доходит до использования коллекций, один из ответов заключается в том,
+что существующая коллекция не меняется; вместо этого функция применяется к коллекции, чтобы создать новую.
+Именно здесь вступают в действие функции высшего порядка, такие как `map` и `filter`.
+
+Например, представим, что есть список имен в нижнем регистре — `List[String]`,
+и необходимо найти все имена, начинающиеся с буквы `"j"`, чтобы затем сделать первые буквы заглавными.
+В ФП код будет выглядеть так:
+
+{% tabs fp-list %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+val a = List("jane", "jon", "mary", "joe")
+val b = a.filter(_.startsWith("j"))
+ .map(_.capitalize)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Как показано, исходный список `a` не меняется.
+Вместо этого к `a` применяется функция фильтрации и преобразования, чтобы создать новую коллекцию,
+и результат присваивается неизменяемой переменной `b`.
+
+Точно так же в ФП не используются классы с изменяемыми параметрами конструктора `var`.
+В ФП создание такого класса не привествуется:
+
+{% tabs fp--class-variables %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+// не стоит этого делать в ФП
+class Person(var firstName: String, var lastName: String)
+ --- ---
+```
+{% endtab %}
+
+{% endtabs %}
+
+Вместо этого обычно создаются `case` классы, чьи параметры конструктора по умолчанию неизменяемые (`val`):
+
+{% tabs fp-immutable-case-class %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+case class Person(firstName: String, lastName: String)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Теперь можно создать экземпляр `Person` как поле `val`:
+
+{% tabs fp-case-class-creation %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+val reginald = Person("Reginald", "Dwight")
+```
+{% endtab %}
+
+{% endtabs %}
+
+Затем, при необходимости внести изменения в данные, используется метод `copy`,
+который поставляется с `case` классом, чтобы “обновлять данные через создание копии”,
+например так:
+
+{% tabs fp-case-class-copy %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+val elton = reginald.copy(
+ firstName = "Elton", // обновить имя
+ lastName = "John" // обновить фамилию
+)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Существуют множество других приёмов работы с неизменяемыми коллекциями и переменными.
+
+> В зависимости от задач вместо `case` классов можно создавать перечисления, trait-ы или классы.
+> Для более подробной информации см. главу [“Моделирование данных”][modeling].
+
+
+[modeling]: {% link _overviews/scala3-book/domain-modeling-intro.md %}
diff --git a/_ru/scala3/book/fp-intro.md b/_ru/scala3/book/fp-intro.md
new file mode 100644
index 0000000000..5c9b3f5fad
--- /dev/null
+++ b/_ru/scala3/book/fp-intro.md
@@ -0,0 +1,30 @@
+---
+layout: multipage-overview
+title: Функциональное программирование
+scala3: true
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+type: chapter
+description: В этой главе представлено введение в функциональное программирование в Scala 3.
+language: ru
+num: 41
+previous-page: collections-summary
+next-page: fp-what-is-fp
+---
+
+Scala позволяет писать код в стиле объектно-ориентированного программирования (ООП),
+в стиле функционального программирования (ФП), а также в гибридном стиле, используя оба подхода в комбинации.
+По словам Martin Odersky,
+сущность Scala — это слияние функционального и объектно-ориентированного программирования в типизированной среде:
+
+- Функции для логики
+- Объекты для модульности
+
+В этой главе предполагается, что вы знакомы с ООП и менее знакомы с ФП,
+поэтому в ней представлено краткое введение в несколько основных концепций функционального программирования:
+
+- Что такое функциональное программирование?
+- Неизменяемые значения
+- Чистые функции
+- Функции — это значения
+- Функциональная обработка ошибок
diff --git a/_ru/scala3/book/fp-pure-functions.md b/_ru/scala3/book/fp-pure-functions.md
new file mode 100644
index 0000000000..47a277a858
--- /dev/null
+++ b/_ru/scala3/book/fp-pure-functions.md
@@ -0,0 +1,153 @@
+---
+layout: multipage-overview
+title: Чистые функции
+scala3: true
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+type: section
+description: В этом разделе рассматривается использование чистых функций в функциональном программировании.
+language: ru
+num: 44
+previous-page: fp-immutable-values
+next-page: fp-functions-are-values
+---
+
+
+Еще одна концепция, которую Scala предлагает для помощи в написании функционального кода, — это возможность писать чистые функции.
+_Чистая функция_ (_pure function_) может быть определена следующим образом:
+
+- функция `f` является чистой, если при одних и тех же входных данных `x` она всегда возвращает один и тот же результат `f(x)`
+- результат функции зависит _только_ от входных данных и её реализации
+- чистые функции только вычисляют результат, ничего не меняя за пределами этих функций
+
+Из этого следует:
+
+- чистая функция не изменяет свои входные параметры
+- она не мутирует какое-либо скрытое состояние
+- у неё нет “черных ходов”: он не читает данные из внешнего мира (включая консоль, веб-сервисы, базы данных, файлы и т.д.)
+ и не записывает данные вовне
+
+В результате этого определения каждый раз, когда вызывается чистая функция с одним и тем же входным значением (значениями),
+всегда будет выдаваться один и тот же результат.
+Например, можно вызывать функцию `double` бесконечное число раз с входным значением `2`, и всегда получать результат `4`.
+
+
+## Примеры чистых функций
+
+Учитывая это определение, методы в пакете `scala.math._` являются чистыми функциями:
+
+- `abs`
+- `ceil`
+- `max`
+
+Эти методы `String` также являются чистыми функциями:
+
+- `isEmpty`
+- `length`
+- `substring`
+
+Большинство методов в классах коллекций Scala также работают как чистые функции,
+включая `drop`, `filter`, `map` и многие другие.
+
+> В Scala _функции_ и _методы_ почти полностью взаимозаменяемы,
+> поэтому, хотя здесь используется общепринятый отраслевой термин “чистая функция”,
+> этот термин можно использовать как для описания функций, так и методов.
+> Как методы могут использоваться подобно функциям описано в главе [Eta расширение][eta].
+
+
+## Примеры “грязных” функций
+
+И наоборот, следующие функции “_грязные_” (_impure_), потому что они нарушают определение pure function:
+
+- `println` — методы, взаимодействующие с консолью, файлами, базами данных, веб-сервисами и т.д., “грязные”
+- `currentTimeMillis` — все методы, связанные с датой и временем, “грязные”,
+ потому что их вывод зависит от чего-то другого, кроме входных параметров
+- `sys.error` — методы генерации исключений “грязные”, потому что они не “просто возвращают результат”
+
+“Грязные” функции часто делают одно из следующего:
+
+- читают из скрытого состояния, т.е. обращаются к параметрам и данным,
+ не переданным в функцию явным образом в качестве входных параметров
+- запись в скрытое состояние
+- изменяют заданные им параметры или изменяют скрытые переменные, например, поля в содержащем их классе
+- выполняют какой-либо ввод-вывод с внешним миром
+
+> В общем, следует остерегаться функций с возвращаемым типом `Unit`.
+> Поскольку эти функции ничего не возвращают, логически единственная причина, по которой они когда-либо вызываются, -
+> это достижение какого-то побочного эффекта.
+> Как следствие, часто использование этих функций является “грязным”.
+
+
+## Но грязные функции все же необходимы ...
+
+Конечно, приложение не очень полезно, если оно не может читать или писать во внешний мир, поэтому рекомендуется следующее:
+
+> Напишите ядро вашего приложения, используя только “чистые” функции,
+> а затем напишите “грязную” “оболочку” вокруг этого ядра для взаимодействия с внешним миром.
+> Как кто-то однажды сказал, это все равно, что положить слой нечистой глазури на чистый торт.
+
+Важно отметить, что есть способы сделать “нечистое” взаимодействие с внешним миром более “чистым”.
+Например, можно услышать об использовании `IO` монады для обработки ввода-вывода.
+Эти темы выходят за рамки данного документа, поэтому для простоты можно думать,
+что ФП приложения имеют ядро из “чистых” функций,
+которые объединены с другими функциями для взаимодействия с внешним миром.
+
+
+## Написание “чистых” функций
+
+**Примечание**: в этом разделе для обозначения методов Scala часто используется общепринятый в отрасли термин “чистая функция”.
+
+Для написания чистых функций на Scala, достаточно писать их,
+используя синтаксис методов Scala (хотя также можно использовать и синтаксис функций Scala).
+Например, вот чистая функция, которая удваивает заданное ей входное значение:
+
+{% tabs fp-pure-function %}
+
+{% tab 'Scala 2 и 3' %}
+```scala
+def double(i: Int): Int = i * 2
+```
+{% endtab %}
+
+{% endtabs %}
+
+Вот чистая функция, которая вычисляет сумму списка целых чисел с использованием рекурсии:
+
+{% tabs fp-pure-recursive-function class=tabs-scala-version %}
+
+{% tab 'Scala 2' %}
+```scala
+def sum(xs: List[Int]): Int = xs match {
+ case Nil => 0
+ case head :: tail => head + sum(tail)
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def sum(xs: List[Int]): Int = xs match
+ case Nil => 0
+ case head :: tail => head + sum(tail)
+```
+{% endtab %}
+
+{% endtabs %}
+
+Вышеописанные функции соответствуют определению “чистых”.
+
+
+## Ключевые моменты
+
+Первым ключевым моментом этого раздела является определение чистой функции:
+
+> _Чистая функция_ — это функция, которая зависит только от своих объявленных входных данных
+> и своей реализации для получения результата.
+> Она только вычисляет свой результат, не завися от внешнего мира и не изменяя его.
+
+Второй ключевой момент заключается в том, что каждое реальное приложение взаимодействует с внешним миром.
+Таким образом, упрощенный способ представления о функциональных программах состоит в том,
+что они состоят из ядра чистых функций, которые обернуты другими функциями, взаимодействующими с внешним миром.
+
+
+[eta]: {% link _overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_ru/scala3/book/fp-summary.md b/_ru/scala3/book/fp-summary.md
new file mode 100644
index 0000000000..0e18a20356
--- /dev/null
+++ b/_ru/scala3/book/fp-summary.md
@@ -0,0 +1,31 @@
+---
+layout: multipage-overview
+title: Обзор
+scala3: true
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+type: section
+description: Этот раздел суммирует предыдущие разделы функционального программирования.
+language: ru
+num: 47
+previous-page: fp-functional-error-handling
+next-page: types-introduction
+---
+
+
+В этой главе представлено общее введение в функциональное программирование на Scala.
+Охвачены следующие темы:
+
+- Что такое функциональное программирование?
+- Неизменяемые значения
+- Чистые функции
+- Функции — это значения
+- Функциональная обработка ошибок
+
+Как уже упоминалось, функциональное программирование — обширная тема,
+поэтому все, что мы можем сделать в этой книге, — это коснуться перечисленных вводных понятий.
+Дополнительные сведения см. [в справочной документации][reference].
+
+
+[reference]: {{ site.scala3ref }}/overview.html
+
diff --git a/_ru/scala3/book/fp-what-is-fp.md b/_ru/scala3/book/fp-what-is-fp.md
new file mode 100644
index 0000000000..8b624b5415
--- /dev/null
+++ b/_ru/scala3/book/fp-what-is-fp.md
@@ -0,0 +1,48 @@
+---
+layout: multipage-overview
+title: Что такое функциональное программирование?
+scala3: true
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+type: section
+description: Этот раздел дает ответ на вопрос, что такое функциональное программирование?
+language: ru
+num: 42
+previous-page: fp-intro
+next-page: fp-immutable-values
+---
+
+
+[Wikipedia](https://ru.wikipedia.org/wiki/%D0%A4%D1%83%D0%BD%D0%BA%D1%86%D0%B8%D0%BE%D0%BD%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B5_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)
+определяет _функциональное программирование_ следующим образом:
+
+++ +Также полезно знать, что опытные функциональные программисты рассматривают свой код математически, +что объединение чистых функций вместе похоже на объединение ряда алгебраических уравнений. + +Когда пишется функциональный код, вы чувствуете себя математиком, и как только понимаете парадигму, +то хотите писать только чистые функции, которые всегда возвращают _значения_, а не исключения или null, +чтобы можно было комбинировать чистые функции вместе. +Ощущение, что вы пишете математические уравнения (выражения), является движущим желанием, +заставляющим использовать _только_ чистые функции и неизменяемые значения - +это то, что используется в алгебре и других формах математики. + +Функциональное программирование - это большая тема, и нет простого способа сжать её всю в одну главу. +В следующих разделах будет представлен обзор основных тем и показаны некоторые инструменты, +предоставляемые Scala для написания функционального кода. diff --git a/_ru/scala3/book/fun-anonymous-functions.md b/_ru/scala3/book/fun-anonymous-functions.md new file mode 100644 index 0000000000..98b7158e8f --- /dev/null +++ b/_ru/scala3/book/fun-anonymous-functions.md @@ -0,0 +1,214 @@ +--- +layout: multipage-overview +title: Анонимные функции +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице показано, как использовать анонимные функции в Scala, включая примеры с функциями map и filter класса List. +language: ru +num: 29 +previous-page: fun-intro +next-page: fun-function-variables +--- + +Анонимная функция, также известная как _лямбда_, представляет собой блок кода, +который передается в качестве аргумента функции высшего порядка. +Википедия определяет [анонимную функцию](https://en.wikipedia.org/wiki/Anonymous_function) +как “определение функции, не привязанное к идентификатору”. + +Например, возьмем коллекцию: + +{% tabs fun-anonymous-1 %} +{% tab 'Scala 2 и 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +Можно создать новый список, удвоив каждый элемент в целых числах, используя метод `map` класса `List` +и свою пользовательскую анонимную функцию: + +{% tabs fun-anonymous-2 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map(_ * 2) // List(2, 4, 6) +``` +{% endtab %} +{% endtabs %} + +Как видно из комментария, `doubleInts` содержит список `List(2, 4, 6)`. +В этом примере анонимной функцией является часть кода: + +{% tabs fun-anonymous-3 %} +{% tab 'Scala 2 и 3' %} +```scala +_ * 2 +``` +{% endtab %} +{% endtabs %} + +Это сокращенный способ сказать: “Умножить данный элемент на 2”. + +## Более длинные формы + +Когда вы освоитесь со Scala, то будете постоянно использовать эту форму для написания анонимных функций, +использующих одну переменную в одном месте функции. +Но при желании можете также написать их, используя более длинные формы, +поэтому в дополнение к написанию этого кода: + +{% tabs fun-anonymous-4 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +вы также можете написать его, используя такие формы: + +{% tabs fun-anonymous-5 %} +{% tab 'Scala 2 и 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +val doubledInts = ints.map((i) => i * 2) +val doubledInts = ints.map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +Все эти строки имеют одно и то же значение: удваивайте каждый элемент `ints`, чтобы создать новый список, `doubledInts` +(синтаксис каждой формы объясняется ниже). + +Если вы знакомы с Java, вам будет полезно узнать, что эти примеры `map` эквивалентны следующему Java коду: + +{% tabs fun-anonymous-5-b %} +{% tab 'Java' %} +```java +List+Функциональное программирование — парадигма программирования, +в которой процесс вычисления трактуется как вычисление значений функций в математическом понимании последних. +Функциональное программирование предполагает обходиться вычислением результатов функций от исходных данных +и результатов других функций, и не предполагает явного хранения состояния программы. +Соответственно, не предполагает оно и изменяемость этого состояния. +
++
+В функциональном программировании функции рассматриваются как “граждане первого класса”, +что означает, что они могут быть привязаны к именам (включая локальные идентификаторы), +передаваться в качестве аргументов и возвращаться из других функций, как и любой другой тип данных. +Это позволяет писать программы в декларативном и составном стиле, где небольшие функции объединяются модульным образом. +
+
+ Если вас интересует заархивированное издание книги для Scala 2, +доступ к нему можно получить здесь. +В настоящее время мы находимся в процессе слияния двух книг, и вы можете нам помочь. ++ +В этой книге мы надеемся продемонстрировать, что Scala — это красивый, выразительный язык программирования с чистым современным синтаксисом, +который поддерживает и функциональное программирование (ФП), и объектно-ориентированное программирование (ООП), +а также обеспечивает безопасную статическую систему типов. +Синтаксис, грамматика и функции Scala были переосмыслены, открыто обсуждались и были обновлены в 2020 году, +чтобы стать яснее и проще для понимания, чем когда-либо прежде. + +Книга начинается с беглого обзора возможностей Scala в [разделе “Почувствуй Scala”][taste]. +После этого обзора в следующих разделах содержится более подробная информация о рассмотренных языковых функциях. + +[reference]: {{ site.scala3ref }}/overview.html +[taste]: {% link _overviews/scala3-book/taste-intro.md %} diff --git a/_ru/scala3/book/methods-intro.md b/_ru/scala3/book/methods-intro.md new file mode 100644 index 0000000000..de34fc1166 --- /dev/null +++ b/_ru/scala3/book/methods-intro.md @@ -0,0 +1,22 @@ +--- +layout: multipage-overview +title: Методы +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: chapter +description: В этой главе представлены методы в Scala 3. +language: ru +num: 24 +previous-page: domain-modeling-fp +next-page: methods-most +--- + + +В Scala 2 _методы_ могут быть определены внутри классов, трейтов, объектов, `case` классов и `case` объектов. +Но стало еще лучше: в Scala 3 они также могут быть определены вне любой из этих конструкций; +мы говорим, что это определения "верхнего уровня", поскольку они не вложены в другое определение. +Короче говоря, теперь методы можно определять где угодно. + +Многие особенности методов демонстрируются в следующем разделе. +Поскольку `main` методы требуют немного больше пояснений, они описаны в одном из следующих разделов отдельно. diff --git a/_ru/scala3/book/methods-main-methods.md b/_ru/scala3/book/methods-main-methods.md new file mode 100644 index 0000000000..cd6342216a --- /dev/null +++ b/_ru/scala3/book/methods-main-methods.md @@ -0,0 +1,205 @@ +--- +layout: multipage-overview +title: Main методы в Scala 3 +scala3: true +partof: scala3-book +overview-name: "Scala 3 — Book" +type: section +description: На этой странице описывается, как основные методы и аннотация @main работают в Scala 3. +language: ru +num: 26 +previous-page: methods-most +next-page: methods-summary +--- + +
Написание однострочных программ только в Scala 3
+ +Scala 3 предлагает следующий способ определения программ, которые можно вызывать из командной строки: +добавление аннотации `@main` к методу превращает его в точку входа исполняемой программы: + +{% tabs method_1 %} +{% tab 'Только в Scala 3' for=method_1 %} + +```scala +@main def hello() = println("Hello, World") +``` + +{% endtab %} +{% endtabs %} + +Для запуска программы достаточно сохранить эту строку кода в файле с именем, например, _Hello.scala_ +(имя файла необязательно должно совпадать с именем метода) и запустить с помощью `scala`: + +```bash +$ scala Hello.scala +Hello, World +``` + +Аннотированный метод `@main` может быть написан либо на верхнем уровне (как показано), +либо внутри статически доступного объекта. +В любом случае имя программы - это имя метода без каких-либо префиксов объектов. + +Узнайте больше об аннотации `@main`, прочитав следующие разделы или посмотрев это видео: + +
+
+
+
+### Аргументы командной строки
+
+Метод `@main` может обрабатывать аргументы командной строки с различными типами.
+Например, данный метод `@main`, который принимает параметры `Int`, `String` и дополнительные строковые параметры:
+
+{% tabs method_2 %}
+{% tab 'Только в Scala 3' for=method_2 %}
+
+```scala
+@main def happyBirthday(age: Int, name: String, others: String*) =
+ val suffix = (age % 100) match
+ case 11 | 12 | 13 => "th"
+ case _ => (age % 10) match
+ case 1 => "st"
+ case 2 => "nd"
+ case 3 => "rd"
+ case _ => "th"
+
+ val sb = StringBuilder(s"Happy $age$suffix birthday, $name")
+ for other <- others do sb.append(" and ").append(other)
+ println(sb.toString)
+```
+
+{% endtab %}
+{% endtabs %}
+
+После компиляции кода создается основная программа с именем `happyBirthday`, которая вызывается следующим образом:
+
+```
+$ scala happyBirthday 23 Lisa Peter
+Happy 23rd Birthday, Lisa and Peter!
+```
+
+Как показано, метод `@main` может иметь произвольное количество параметров.
+Для каждого типа параметра должен существовать [given экземпляр][given]
+класса типа `scala.util.CommandLineParser.FromString`, который преобразует аргумент из `String` в требуемый тип параметра.
+Также, как показано, список параметров основного метода может заканчиваться повторяющимся параметром типа `String*`,
+который принимает все оставшиеся аргументы, указанные в командной строке.
+
+Программа, реализованная с помощью метода `@main`, проверяет,
+что в командной строке достаточно аргументов для заполнения всех параметров,
+и что строки аргументов могут быть преобразованы в требуемые типы.
+Если проверка завершается неудачей, программа завершается с сообщением об ошибке:
+
+```
+$ scala happyBirthday 22
+Illegal command line after first argument: more arguments expected
+
+$ scala happyBirthday sixty Fred
+Illegal command line: java.lang.NumberFormatException: For input string: "sixty"
+```
+
+## Пользовательские типы как параметры
+
+Как упоминалось выше, компилятор ищет заданный экземпляр класса типов `scala.util.CommandLineParser.FromString`
+для типа аргумента. Например, предположим, что у вас есть собственный тип `Color`,
+который вы хотите использовать в качестве параметра.
+Вы можете сделать это, как показано ниже:
+
+{% tabs method_3 %}
+{% tab 'Только в Scala 3' for=method_3 %}
+
+```scala
+enum Color:
+ case Red, Green, Blue
+
+given ComamndLineParser.FromString[Color] with
+ def fromString(value: String): Color = Color.valueOf(value)
+
+@main def run(color: Color): Unit =
+ println(s"The color is ${color.toString}")
+```
+
+{% endtab %}
+{% endtabs %}
+
+Это работает одинаково для ваших собственных пользовательских типов в вашей программе,
+а также для типов, которые можно использовать из другой библиотеки.
+
+## Детали
+
+Компилятор Scala генерирует программу из `@main` метода `f` следующим образом:
+
+- он создает класс с именем `f` в пакете, где был найден метод `@main`.
+- класс имеет статический метод `main` с обычной сигнатурой Java `main` метода:
+ принимает `Array[String]` в качестве аргумента и возвращает `Unit`.
+- сгенерированный `main` метод вызывает метод `f` с аргументами,
+ преобразованными с помощью методов в объекте `scala.util.CommandLineParser.FromString`.
+
+Например, приведенный выше метод `happyBirthday` генерирует дополнительный код, эквивалентный следующему классу:
+
+{% tabs method_4 %}
+{% tab 'Только в Scala 3' for=method_4 %}
+
+```scala
+final class happyBirthday {
+ import scala.util.{CommandLineParser as CLP}
+ | Тип переменной | +Описание | +
|---|---|
val |
+ Создает неизменяемую переменную — как final в Java. Вы всегда должны создавать переменную с val, если нет причины, по которой вам нужна изменяемая переменная. |
+
var |
+ Создает изменяемую переменную и должна использоваться только в том случае, если содержимое переменной будет меняться с течением времени. | +
Hello world!
+``` + +С таким простым основным шаблоном, как этот: + +{% raw %} + +```html + + +Hello world!
` в файле `index.html`. +{% endraw %} + +Макеты должны быть размещены в каталоге `_layouts` в корне сайта: + +``` +├── _layouts +│ └── main.html +└── _docs + ├── getting-started.md + └── index.html +``` + +## Ресурсы + +Чтобы рендерить ассеты вместе со статическим сайтом, их нужно поместить в директорию `_assets` в корне сайта: + +``` +├── _assets +│ └── images +│ └── myimage.png +└── _docs + └── getting-started.md +``` + +Чтобы сослаться на ресурс на странице, необходимо создать ссылку относительно каталога `_assets`. + +``` +Take a look at the following image: [My image](images/myimage.png) +``` + +## Боковая панель + +По умолчанию Scaladoc отображает структуру каталогов из каталога `_docs` на визуализируемом сайте. +Существует также возможность переопределить его, предоставив файл `sidebar.yml` в корневом каталоге сайта. +Конфигурационный файл YAML описывает структуру отображаемого статического сайта и оглавление: + +```yaml +index: index.html +subsection: + - title: Usage + index: usage/index.html + directory: usage + subsection: + - title: Dottydoc + page: usage/dottydoc.html + hidden: false + - title: sbt-projects + page: usage/sbt-projects.html + hidden: false +``` + +Корневой элемент должен быть `subsection`. +Вложенные подразделы приведут к древовидной структуре навигации. + +Свойства `subsection`: + +- `title` - Необязательная строка - заголовок подраздела по умолчанию. + Вступительные заголовки имеют более высокий приоритет. +- `index` - Необязательная строка - Путь к индексной странице подраздела. Путь указан относительно каталога `_docs`. +- `directory` - Необязательная строка - Имя каталога, в котором будет находиться подраздел сгенерированного сайта. + По умолчанию именем каталога является имя подраздела, преобразованное в kebab case. +- `subsection` - Массив `subsection` или `page`. + +Либо `index`, либо `subsection` должны быть определены. Подраздел, определенный с `index` и без `subsection`, +будет содержать страницы и каталоги, загружаемые рекурсивно из каталога индексной страницы. + +Свойства `page`: + +- `title` - Необязательная строка - заголовок страницы по умолчанию. Вступительные заголовки имеют более высокий приоритет. +- `page` - Строка - Путь к странице относительно каталога `_docs`. +- `hidden` - Необязательное логическое значение. Флаг, указывающий, должна ли страница отображаться на боковой панели навигации. + По умолчанию установлено значение `false`. + +**Заметка**: Все пути в файле конфигурации YAML относятся к `
+
+
+
+## Путь обучения Scala
+
+На диаграмме ниже показаны возможные пути обучения на наших курсах:
+
+
+
+"Базовые" курсы предназначены для программистов без предварительного опыта работы со Scala,
+тогда как "углубленные" курсы направлены на укрепление навыков программирования на Scala в конкретной области
+(например, параллельном программировании).
+
+Мы рекомендуем начать с "Эффективного программирования на Scala" (Effective Programming in Scala)
+или "Принципов функционального программирования на Scala" (Functional Programming Principles in Scala),
+а затем с "Проектирования функциональных программ" (Functional Program Design).
+Затем вы можете дополнить свои навыки Scala,
+пройдя любой из курсов "Программирование реактивных систем" (Programming Reactive Systems),
+"Параллельное программирование" (Parallel Programming)
+или "Анализ больших данных с помощью Scala и Spark" (Big Data Analysis with Scala and Spark).
+Если вы выберете специализацию Scala, то последним проектом будет Scala Capstone.
+
+## Учебные платформы
+
+В настоящее время все наши МООК доступны на платформе [Coursera](https://coursera.org),
+а некоторые из них доступны на [edX](https://edx.org) или [Extension School](https://extensionschool.ch).
+В этом разделе объясняются различия между этими учебными платформами.
+
+На всех платформах полный материал всегда доступен онлайн.
+Он включает в себя видеолекции, текстовые статьи, опросники и домашние задания с автоматической оценкой.
+Все платформы также предоставляют дискуссионные форумы, где вы можете общаться с другими учащимися.
+
+Отличие Extension School от других платформ заключается в том,
+что она проводит живые встречи с инструкторами и обзоры кода экспертами Scala.
+
+С другой стороны, на Coursera или edX наши курсы можно пройти бесплатно (режим "audit").
+При желании подписка дает вам доступ к сертификату об окончании, подтверждающему ваши результаты.
+
+Узнайте больше о [сертификатах Coursera](https://learners.coursera.help/hc/en-us/articles/209819053-Get-a-Course-Certificate),
+[сертификатах edX](https://support.edx.org/hc/en-us/categories/115002269627-Certificates)
+или [сертификатах Extension School](https://www.extensionschool.ch/faqs#certifying-coursework).
+Обратите внимание, что ваши подписки также поддерживают работу [Scala Center],
+миссией которого является создание качественных учебных материалов.
+
+Если вы предпочитаете самостоятельное обучение, мы рекомендуем вам выбрать платформу Coursera или edX,
+но если вам нужна дополнительная поддержка, рекомендуем вам выбрать Extension School.
+Ниже приведена таблица, в которой сравниваются платформы обучения:
+
+| | Coursera / edX (аудит) | Coursera / edX (подписка) | Extension School |
+| ------------------------------------------------ | ---------------------- | ------------------------- | ---------------- |
+| Видео-лекции, тесты | Да | Да | Да |
+| Домашние задания с автоматической оценкой | Да | Да | Да |
+| Дискуссионные форумы | Да | Да | Да |
+| Самостоятельный темп | Да | Да | Да |
+| Стоимость | $0 | от $50 до $100 за курс | $420 в месяц |
+| Сертификат об окончании | Нет | Да | Да |
+| Поддерживает Scala Center | Нет | Да | Да |
+| 30 минут живого занятия с инструкторами в неделю | Нет | Нет | Да |
+| Code reviews экспертами Scala | Нет | Нет | Да |
+
+## Effective Programming in Scala
+
+Этот курс доступен на [Coursera](https://coursera.org/learn/effective-scala) и [Extension School](https://extensionschool.ch/learn/effective-programming-in-scala).
+Пожалуйста, обратитесь к [этому разделу](#учебные-платформы), чтобы узнать о различиях между обеими учебными платформами.
+
+["Эффективное программирование на Scala"][Effective Programming in Scala] обучает программистов, не владеющих Scala,
+всему, что им нужно для подготовки к работе в Scala.
+В конце этого практического курса вы узнаете, как решать общие задачи программирования на Scala
+(например, моделирование бизнес-областей, реализацию бизнес-логики,
+проектирование больших систем, состоящих из компонентов,
+обработку ошибок, обработка данных, параллельное выполнение задач, тестирование вашего кода).
+Подробнее об этом курсе вы можете узнать из следующего видео:
+
+
+
+
+
+Этот курс также является хорошим способом улучшить свои знания Scala 2 до Scala 3.
+
+После прохождения этого курса вам может быть интересно улучшить свои навыки в конкретных областях,
+пройдя курсы ["Параллельное программирование"][Parallel Programming],
+["Анализ больших данных с помощью Scala и Spark"][Big Data Analysis with Scala and Spark]
+или ["Программирование реактивных систем"][Programming Reactive Systems].
+
+## Специализация Scala
+
+[Специализация Scala][Scala Specialization] обеспечивает практическое введение в функциональное программирование с использованием Scala.
+Вы можете получить доступ к материалам и упражнениям курса, зарегистрировавшись на специализацию или прослушав курсы индивидуально.
+Специализация состоит из следующих курсов:
+
+- [Принципы функционального программирования на Scala][Functional Programming Principles in Scala],
+- [Функциональный дизайн программ на Scala][Functional Program Design in Scala],
+- [Параллельное программирование][Parallel programming],
+- [Анализ больших данных с помощью Scala и Spark][Big Data Analysis with Scala and Spark],
+- [Функциональное программирование в Scala Capstone][Functional Programming in Scala Capstone].
+
+Эти курсы обеспечивают глубокое понимание самого языка Scala, а также погружаются в более конкретные темы,
+такие как параллельное программирование и Spark.
+
+## Программирование реактивных систем
+
+[Программирование реактивных систем][Programming Reactive Systems]
+(также доступно на [edX](https://www.edx.org/course/scala-akka-reactive))
+обучает писать адаптивные, масштабируемые и отказоустойчивые системы с помощью библиотеки Akka.
+
+## Курсы по Скала 2
+
+Все вышеперечисленные курсы используют Scala 3.
+При необходимости вы можете найти (устаревшую) версию наших курсов Scala 2 здесь:
+
+- [Принципы функционального программирования на Scala (версия Scala 2)](https://www.coursera.org/learn/scala2-functional-programming)
+- [Функциональный дизайн программ на Scala (версия Scala 2)](https://www.coursera.org/learn/scala2-functional-program-design)
+- [Параллельное программирование (версия Scala 2)](https://www.coursera.org/learn/scala2-parallel-programming)
+- [Анализ больших данных с помощью Scala и Spark (версия Scala 2)](https://www.coursera.org/learn/scala2-spark-big-data)
+- [Программирование реактивных систем (версия Scala 2)](https://www.coursera.org/learn/scala2-akka-reactive)
+
+## Отзывы
+
+{% include carousel.html images=page.testimonials number=0 height="50" unit="%" duration="10" %}
+
+## Другие онлайн-ресурсы
+
+[На этой странице]({% link online-courses.md %}) вы можете найти другие онлайн-ресурсы, предоставленные сообществом.
+
+[Scala Center]: https://scala.epfl.ch
+[Scala Specialization]: https://www.coursera.org/specializations/scala
+[Effective Programming in Scala]: https://www.coursera.org/learn/effective-scala
+[Functional Programming Principles in Scala]: https://www.coursera.org/learn/scala-functional-programming
+[Functional Program Design in Scala]: https://www.coursera.org/learn/scala-functional-program-design
+[Parallel programming]: https://www.coursera.org/learn/scala-parallel-programming
+[Big Data Analysis with Scala and Spark]: https://www.coursera.org/learn/scala-spark-big-data
+[Functional Programming in Scala Capstone]: https://www.coursera.org/learn/scala-capstone
+[Programming Reactive Systems]: https://www.coursera.org/learn/scala-akka-reactive
diff --git a/_ru/toolkit/OrderedListOfMdFiles b/_ru/toolkit/OrderedListOfMdFiles
new file mode 100644
index 0000000000..b2790bd58a
--- /dev/null
+++ b/_ru/toolkit/OrderedListOfMdFiles
@@ -0,0 +1,36 @@
+introduction.md
+testing-intro.md
+testing-suite.md
+testing-run.md
+testing-run-only.md
+testing-exceptions.md
+testing-asynchronous.md
+testing-resources.md
+testing-what-else.md
+os-intro.md
+os-read-directory.md
+os-read-file.md
+os-write-file.md
+os-run-process.md
+os-what-else.md
+json-intro.md
+json-parse.md
+json-modify.md
+json-deserialize.md
+json-serialize.md
+json-files.md
+json-what-else.md
+http-client-intro.md
+http-client-request.md
+http-client-uris.md
+http-client-request-body.md
+http-client-json.md
+http-client-upload-file.md
+http-client-what-else.md
+web-server-intro.md
+web-server-static.md
+web-server-dynamic.md
+web-server-query-parameters.md
+web-server-input.md
+web-server-websockets.md
+web-server-cookies-and-decorators.md
diff --git a/_ru/toolkit/http-client-intro.md b/_ru/toolkit/http-client-intro.md
new file mode 100644
index 0000000000..6e552acecd
--- /dev/null
+++ b/_ru/toolkit/http-client-intro.md
@@ -0,0 +1,24 @@
+---
+layout: multipage-overview
+partof: toolkit
+overview-name: "Scala инструментарий"
+title: Отправка HTTP-запросов с помощью sttp
+type: chapter
+description: Введение в библиотеку sttp
+language: ru
+num: 23
+previous-page:
+next-page:
+---
+
+sttp — популярная и многофункциональная библиотека для выполнения HTTP-запросов к веб-серверам.
+
+Она предоставляет как синхронный API, так и асинхронный API, основанный на `Future`. Она также поддерживает WebSockets.
+
+Доступны расширения, добавляющие такие возможности, как потоковая передача, логирование, телеметрия и сериализация.
+
+sttp предлагает одинаковые API на всех платформах (JVM, Scala.js и Scala Native).
+
+sttp — хороший выбор для небольших синхронных скриптов, а также для крупномасштабных, высококонкурентных, асинхронных приложений.
+
+{% include markdown.html path="_markdown/_ru/install-sttp.md" %}
diff --git a/_ru/toolkit/introduction.md b/_ru/toolkit/introduction.md
new file mode 100644
index 0000000000..f6a216e298
--- /dev/null
+++ b/_ru/toolkit/introduction.md
@@ -0,0 +1,88 @@
+---
+layout: multipage-overview
+partof: toolkit
+overview-name: "Scala инструментарий"
+title: Введение
+type: chapter
+description: Знакомство с учебными пособиями по Scala инструментариям
+language: ru
+num: 1
+previous-page:
+next-page: testing-intro
+toolkit-index:
+ - title: Тесты
+ description: Тестирование кода с помощью MUnit.
+ icon: "fa fa-vial-circle-check"
+ link: /ru/toolkit/testing-intro.html
+ - title: Файлы и процессы
+ description: Запись файлов и запуск процессов с помощью OS-Lib.
+ icon: "fa fa-folder-open"
+ link: /ru/toolkit/os-intro.html
+ - title: JSON
+ description: Парсинг JSON и сериализация объектов в JSON с помощью uPickle.
+ icon: "fa fa-file-code"
+ link: /ru/toolkit/json-intro.html
+ - title: HTTP-запросы
+ description: Отправка HTTP-запросов и загрузка файлов с помощью sttp.
+ icon: "fa fa-globe"
+ link: /ru/toolkit/http-client-intro.html
+ - title: Веб-серверы
+ description: Создание веб-серверов с помощью Cask.
+ icon: "fa fa-server"
+ link: /ru/toolkit/web-server-intro.html
+---
+
+## Что такое набор инструментов Scala?
+
+Scala Toolkit — это набор библиотек, предназначенных для эффективного выполнения типичных задач программирования.
+Он включает в себя инструменты для работы с файлами и процессами, парсинга JSON, отправки HTTP-запросов и модульного тестирования.
+
+Инструментарий поддерживает:
+
+- Scala 3 и Scala 2
+- JVM, Scala.js и Scala Native
+
+Варианты использования набора инструментов включают в себя:
+
+- кратковременные программы, работающие на JVM, для сканирования веб-сайта, сбора и преобразования данных
+ или для извлечения и обработки некоторых файлов,
+- скрипты интерфейса, которые запускаются в браузере и обеспечивают работу ваших веб-сайтов,
+- инструменты командной строки, упакованные в виде собственных двоичных файлов для мгновенного запуска
+
+{% include inner-documentation-sections.html links=page.toolkit-index %}
+
+## Что это за руководства?
+
+В этой серии руководств основное внимание уделяется кратким примерам кода, которые помогут вам быстро приступить к работе.
+
+Если вам нужна более подробная информация, в руководствах содержатся ссылки на дополнительную документацию
+по всем библиотекам в наборе инструментов.
+
+## Как запустить код?
+
+Вы можете следовать руководствам независимо от того, как решите запустить свой Scala код.
+Руководства фокусируются на самом коде, а не на процессе его запуска.
+
+Способы запуска кода на Scala включают:
+
+- В вашем **браузере** с помощью [Scastie](https://scastie.scala-lang.org)
+ - Плюсы: не требует установки, возможность делиться кодом онлайн
+ - Минусы: только один файл, доступно только онлайн
+- Интерактивно в **REPL** Scala (Read/Eval/Print/Loop)
+ - Плюсы: интерактивное исследование в терминале
+ - Минусы: не сохраняет ваш код
+- Интерактивно в **worksheet** в вашей IDE, например [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) или [Metals](http://scalameta.org/metals/)
+ - Плюсы: интерактивное исследование в графическом интерфейсе
+ - Минусы: требует для запуска среды worksheet
+- В **скриптах** с использованием [Scala CLI](https://scala-cli.virtuslab.com)
+ - Плюсы: рабочий процесс в терминале с минимальной настройкой
+ - Минусы: может не подходить для крупных проектов
+- С использованием **инструмента сборки** (например, [sbt](https://www.scala-sbt.org) или [mill](https://com-lihaoyi.github.io/mill/))
+ - Плюсы: рабочий процесс в терминале для проектов любого размера
+ - Минусы: требует дополнительной настройки и обучения
+- С использованием **IDE**, например [IntelliJ](https://www.jetbrains.com/help/idea/discover-intellij-idea-for-scala.html) или [Metals](http://scalameta.org/metals/)
+ - Плюсы: рабочий процесс в графическом интерфейсе для проектов любого размера
+ - Минусы: требует дополнительной настройки и обучения
+
+Эти варианты, с их плюсами и минусами, характерны для большинства языков программирования.
+Вы можете использовать любой из них, в зависимости от того варианта, который вам удобен.
diff --git a/_ru/toolkit/json-intro.md b/_ru/toolkit/json-intro.md
new file mode 100644
index 0000000000..c91f04b075
--- /dev/null
+++ b/_ru/toolkit/json-intro.md
@@ -0,0 +1,23 @@
+---
+layout: multipage-overview
+partof: toolkit
+overview-name: "Scala инструментарий"
+title: Обработка JSON с помощью uPickle
+type: chapter
+description: Описание библиотеки uPickle.
+language: ru
+num: 16
+previous-page:
+next-page:
+---
+
+uPickle — это облегченная библиотека сериализации для Scala.
+
+В его состав входит uJson — библиотека для работы с JSON, которая может анализировать строки JSON,
+получать доступ к их значениям в памяти или изменять их, а также записывать их обратно.
+
+uPickle может сериализовать и десериализовать объекты Scala напрямую в JSON и из него.
+Он знает, как обрабатывать коллекции Scala, такие как `Map` и `Seq`,
+а также ваши собственные типы данных, такие как case class-ы и перечисления Scala 3.
+
+{% include markdown.html path="_markdown/_ru/install-upickle.md" %}
diff --git a/_ru/toolkit/os-intro.md b/_ru/toolkit/os-intro.md
new file mode 100644
index 0000000000..4e5cb4fd2a
--- /dev/null
+++ b/_ru/toolkit/os-intro.md
@@ -0,0 +1,25 @@
+---
+layout: multipage-overview
+partof: toolkit
+overview-name: "Scala инструментарий"
+title: Работа с файлами и процессами с помощью OS-Lib
+type: chapter
+description: Введение в библиотеку OS-lib
+language: ru
+num: 10
+previous-page:
+next-page:
+---
+
+OS-Lib — это библиотека для работы с файлами и процессами. Она является частью Scala Toolkit.
+
+OS-Lib стремится заменить API `java.nio.file` и `java.lang.ProcessBuilder`.
+Скорее всего, вам не понадобиться напрямую использовать какие-либо низкоуровневые Java API.
+
+OS-Lib также нацелена на то, чтобы вытеснить устаревшие API `scala.io` и `scala.sys` из стандартной библиотеки Scala.
+
+OS-Lib не имеет зависимостей.
+
+Весь функционал OS-Lib находится в пространстве имён `os.*`.
+
+{% include markdown.html path="_markdown/_ru/install-os-lib.md" %}
diff --git a/_ru/toolkit/testing-intro.md b/_ru/toolkit/testing-intro.md
new file mode 100644
index 0000000000..3fa905ddb3
--- /dev/null
+++ b/_ru/toolkit/testing-intro.md
@@ -0,0 +1,28 @@
+---
+layout: multipage-overview
+partof: toolkit
+overview-name: "Scala инструментарий"
+title: Тестирование с помощью MUnit
+type: chapter
+description: Введение в библиотеку MUnit
+language: ru
+num: 2
+previous-page: introduction
+next-page:
+---
+
+MUnit — легковесная библиотека для тестирования. Она предоставляет единый стиль написания тестов, который можно быстро освоить.
+
+Несмотря на свою простоту, MUnit обладает такими полезными функциями, как:
+
+- **утверждения (assertions)** для проверки поведения программы,
+- **фикстуры (fixtures)**, чтобы гарантировать, что тесты имеют доступ ко всем необходимым ресурсам,
+- **поддержка асинхронности** для тестирования параллельных (concurrent) и распределённых приложений.
+
+MUnit создаёт полезные отчёты об ошибках с указанием различий и местоположения в исходном коде, что помогает быстро понять причины сбоев.
+
+Тестирование является важной частью любого процесса разработки программного обеспечения,
+так как оно помогает находить ошибки на ранних этапах,
+улучшает качество кода и облегчает совместную работу.
+
+{% include markdown.html path="_markdown/_ru/install-munit.md" %}
diff --git a/_ru/toolkit/web-server-intro.md b/_ru/toolkit/web-server-intro.md
new file mode 100644
index 0000000000..6afdebab4f
--- /dev/null
+++ b/_ru/toolkit/web-server-intro.md
@@ -0,0 +1,30 @@
+---
+layout: multipage-overview
+partof: toolkit
+overview-name: "Scala инструментарий"
+title: Создание веб-серверов с помощью Cask
+type: chapter
+description: Введение в библиотеку Cask
+language: ru
+num: 30
+previous-page:
+next-page:
+---
+
+Cask — это микрофреймворк HTTP, предоставляющий простой и гибкий способ создания веб-приложений.
+
+Основное внимание уделяется простоте использования, что делает его идеальным для новичков,
+но при этом приходится отказываться от некоторых функций, предоставляемых другими фреймворками, например, асинхронности.
+
+Чтобы определить endpoint, достаточно аннотировать функцию аннотацией, указывающей путь запроса.
+Cask позволяет вручную строить ответ с помощью инструментов, предоставляемых библиотекой,
+указывая содержимое, заголовки, код статуса и т.д.
+Функция endpoint также может возвращать строку, JSON тип [uPickle](https://com-lihaoyi.github.io/upickle/)
+или шаблон [Scalatags](https://com-lihaoyi.github.io/scalatags/).
+В этом случае Cask автоматически создаст ответ с соответствующими заголовками.
+
+Cask поставляется в комплекте с библиотекой uPickle для обработки JSON, поддерживает WebSockets
+и позволяет расширять конечные точки с помощью декораторов,
+которые можно использовать для обработки аутентификации или ограничения скорости.
+
+{% include markdown.html path="_markdown/_ru/install-cask.md" %}
diff --git a/_ru/tour/abstract-type-members.md b/_ru/tour/abstract-type-members.md
index 849286419f..537ebf80f4 100644
--- a/_ru/tour/abstract-type-members.md
+++ b/_ru/tour/abstract-type-members.md
@@ -1,9 +1,6 @@
---
layout: tour
title: Члены Абстрактного Типа
-
-discourse: true
-
partof: scala-tour
num: 23
language: ru
@@ -11,20 +8,38 @@ next-page: compound-types
previous-page: inner-classes
topics: abstract type members
prerequisite-knowledge: variance, upper-type-bound
-
---
-Абстрактные типы, такие как трейты и абстрактные классы, могут содержать членов абстрактного типа.
+Абстрактные типы, такие как трейты и абстрактные классы, могут содержать члены абстрактного типа.
Абстрактный означает, что только конкретный экземпляр определяет, каким именно будет тип.
Вот пример:
+{% tabs abstract-types_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=abstract-types_1 %}
+
```scala mdoc
trait Buffer {
type T
val element: T
}
```
-Здесь мы определили абстрактный тип `T`, который используется для описания типа члена `element`. Мы можем расширить его в абстрактном классе, добавив верхнюю границу нового типа `U` связанного с `T`, делая описание типа более конкретным.
+
+{% endtab %}
+{% tab 'Scala 3' for=abstract-types_1 %}
+
+```scala
+trait Buffer:
+ type T
+ val element: T
+```
+
+{% endtab %}
+{% endtabs %}
+
+Здесь мы определили абстрактный тип `T`, который используется для описания типа члена `element`. Мы можем расширить его в абстрактном классе, добавив верхнюю границу нового типа `U`, связанного с `T`, делая описание типа более конкретным.
+
+{% tabs abstract-types_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=abstract-types_2 %}
```scala mdoc
abstract class SeqBuffer extends Buffer {
@@ -33,28 +48,68 @@ abstract class SeqBuffer extends Buffer {
def length = element.length
}
```
+
+{% endtab %}
+{% tab 'Scala 3' for=abstract-types_2 %}
+
+```scala
+abstract class SeqBuffer extends Buffer:
+ type U
+ type T <: Seq[U]
+ def length = element.length
+```
+
+{% endtab %}
+{% endtabs %}
+
Обратите внимание, как мы можем использовать новый абстрактный тип `U` в качестве верхней границы типа. Класс `SeqBuffer` позволяет хранить в буфере только последовательности, указывая, что тип `T` должен быть подтипом `Seq[U]` для нового абстрактного типа `U`.
-[Трейты](traits.html) или [классы](classes.html) с членами абстрактного типа часто используются в сочетании с анонимными экземплярами классов. Чтобы проиллюстрировать это рассмотрим программу, которая имеет дело с буфером, который ссылается на список целых чисел:
+[Трейты](traits.html) или [классы](classes.html) с членами абстрактного типа часто используются в сочетании с анонимными экземплярами классов. Чтобы проиллюстрировать это рассмотрим программу, имеющую дело с буфером, который ссылается на список целых чисел:
+
+{% tabs abstract-types_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=abstract-types_3 %}
```scala mdoc
abstract class IntSeqBuffer extends SeqBuffer {
type U = Int
}
-
def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer =
new IntSeqBuffer {
- type T = List[U]
- val element = List(elem1, elem2)
- }
+ type T = List[U]
+ val element = List(elem1, elem2)
+ }
+val buf = newIntSeqBuf(7, 8)
+println("length = " + buf.length)
+println("content = " + buf.element)
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=abstract-types_3 %}
+
+```scala
+abstract class IntSeqBuffer extends SeqBuffer:
+ type U = Int
+
+def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer =
+ new IntSeqBuffer:
+ type T = List[U]
+ val element = List(elem1, elem2)
+
val buf = newIntSeqBuf(7, 8)
println("length = " + buf.length)
println("content = " + buf.element)
```
-Здесь класс `newIntSeqBuf` создает экземпляры `IntSeqBuffer`, используя анонимную реализацию класса `IntSeqBuffer` (т.е. `new IntSeqBuffer`), устанавливая тип `T` как `List[Int]`.
-Мы можем вывести тип класса из типа его членов и наоборот. Приведем версию кода, в которой выводится тип класса из типа его члена:
+{% endtab %}
+{% endtabs %}
+
+Здесь метод `newIntSeqBuf` создает экземпляры `IntSeqBuffer`, используя анонимную реализацию класса `IntSeqBuffer` (т.е. `new IntSeqBuffer`), устанавливая тип `T` как `List[Int]`.
+
+Мы можем вывести тип класса из типа его членов и наоборот. Приведем версию кода, в которой выводится тип класса из типов его члена:
+
+{% tabs abstract-types_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=abstract-types_4 %}
```scala mdoc:nest
abstract class Buffer[+T] {
@@ -74,4 +129,26 @@ println("length = " + buf.length)
println("content = " + buf.element)
```
-Обратите внимание, что здесь необходимо использовать [вариантность в описании типа](variances.html) (`+T <: Seq[U]`) для того, чтобы скрыть конкретный тип реализации списка, возвращаемого из метода `newIntSeqBuf`.
+{% endtab %}
+{% tab 'Scala 3' for=abstract-types_4 %}
+
+```scala
+abstract class Buffer[+T]:
+ val element: T
+
+abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T]:
+ def length = element.length
+
+def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] =
+ new SeqBuffer[Int, List[Int]]:
+ val element = List(e1, e2)
+
+val buf = newIntSeqBuf(7, 8)
+println("length = " + buf.length)
+println("content = " + buf.element)
+```
+
+{% endtab %}
+{% endtabs %}
+
+Обратите внимание, что здесь необходимо использовать [вариантность в описании типа](variances.html) (`+T <: Seq[U]`) для того, чтобы скрыть конкретный тип реализации списка, возвращаемого из метода `newIntSeqBuf`.
diff --git a/_ru/tour/annotations.md b/_ru/tour/annotations.md
index 99a668acb0..0af144139d 100644
--- a/_ru/tour/annotations.md
+++ b/_ru/tour/annotations.md
@@ -1,34 +1,52 @@
---
layout: tour
title: Аннотации
-
-discourse: true
-
partof: scala-tour
-
num: 32
language: ru
next-page: packages-and-imports
previous-page: by-name-parameters
-
---
Аннотации используются для передачи метаданных при объявлении. Например, аннотация `@deprecated` перед объявлением метода, заставит компилятор вывести предупреждение, если этот метод будет использован.
-```
+
+{% tabs annotations_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=annotations_1 %}
+
+```scala mdoc:fail
object DeprecationDemo extends App {
@deprecated("deprecation message", "release # which deprecates method")
def hello = "hola"
- hello
+ hello
}
```
+
+{% endtab %}
+{% tab 'Scala 3' for=annotations_1 %}
+
+```scala
+object DeprecationDemo extends App:
+ @deprecated("deprecation message", "release # which deprecates method")
+ def hello = "hola"
+
+ hello
+```
+
+{% endtab %}
+{% endtabs %}
+
Такой код скомпилируется, но компилятор выдаст предупреждение: "there was one deprecation warning".
Аннотация применяется к первому идущему после нее объявлению или определению. Допускается использование сразу нескольких аннотаций следующих друг за другом. Порядок, в котором приводятся аннотации, не имеет значения.
## Аннотации, обеспечивающие корректность работы кода
+
Некоторые аннотации приводят к невозможности компиляции, если условие (условия) не выполняется. Например, аннотация `@tailrec` гарантирует, что метод является [хвостовой рекурсией](https://ru.wikipedia.org/wiki/%D0%A5%D0%B2%D0%BE%D1%81%D1%82%D0%BE%D0%B2%D0%B0%D1%8F_%D1%80%D0%B5%D0%BA%D1%83%D1%80%D1%81%D0%B8%D1%8F). Хвостовая рекурсия помогает держать потребление памяти на постоянном уровне. Вот как она используется в методе, который вычисляет факториал:
+{% tabs annotations_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=annotations_2 %}
+
```scala mdoc
import scala.annotation.tailrec
@@ -41,8 +59,30 @@ def factorial(x: Int): Int = {
factorialHelper(x, 1)
}
```
-Метод `factorialHelper` имеет аннотацию `@tailrec`, которая гарантирует, что метод действительно является хвостовой рекурсией. Если бы мы изменили реализацию `factorialHelper` так как указано далее, то компиляция бы провалилась:
+
+{% endtab %}
+{% tab 'Scala 3' for=annotations_2 %}
+
+```scala
+import scala.annotation.tailrec
+
+def factorial(x: Int): Int =
+
+ @tailrec
+ def factorialHelper(x: Int, accumulator: Int): Int =
+ if x == 1 then accumulator else factorialHelper(x - 1, accumulator * x)
+ factorialHelper(x, 1)
```
+
+{% endtab %}
+{% endtabs %}
+
+Метод `factorialHelper` имеет аннотацию `@tailrec`, которая гарантирует, что метод действительно является хвостовой рекурсией. Если бы мы изменили реализацию `factorialHelper` так как указано далее, то компиляция бы провалилась:
+
+{% tabs annotations_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=annotations_3 %}
+
+```scala mdoc:fail
import scala.annotation.tailrec
def factorial(x: Int): Int = {
@@ -53,77 +93,155 @@ def factorial(x: Int): Int = {
factorialHelper(x)
}
```
-Мы бы получили сообщение "Recursive call not in tail position"(Рекурсивный вызов не в хвостовой позиции).
+{% endtab %}
+{% tab 'Scala 3' for=annotations_3 %}
+
+```scala
+import scala.annotation.tailrec
+
+def factorial(x: Int): Int =
+ @tailrec
+ def factorialHelper(x: Int): Int =
+ if x == 1 then 1 else x * factorialHelper(x - 1)
+ factorialHelper(x)
+```
+
+{% endtab %}
+{% endtabs %}
+
+Мы бы получили сообщение "Recursive call not in tail position"(Рекурсивный вызов не в хвостовой позиции).
## Аннотации, влияющие на генерацию кода
+
+{% tabs annotations_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=annotations_4 %}
+
Некоторые аннотации типа `@inline` влияют на сгенерированный код (т.е. в результате сам код вашего jar-файл может отличаться). Такая аннотация означает вставку всего кода в тело метода вместо вызова. Полученный байт-код длиннее, но, надеюсь, работает быстрее. Использование аннотации `@inline` не гарантирует, что метод будет встроен, но заставит компилятор сделать это, если и только если будут соблюдены некоторые разумные требования к размеру сгенерированного кода.
-### Java аннотации ###
+{% endtab %}
+{% tab 'Scala 3' for=annotations_4 %}
+
+Некоторые аннотации типа `@main` влияют на сгенерированный код (т.е. в результате сам код вашего jar-файл может отличаться).
+Аннотация `@main` к методу создает исполняемую программу, которая вызывает метод как точку входа.
+
+{% endtab %}
+{% endtabs %}
+
+### Java аннотации
+
Есть некоторые отличия синтаксиса аннотаций, если пишется Scala код, который взаимодействует с Java.
**Примечание:**Убедитесь, что вы используете опцию `-target:jvm-1.8` с аннотациями Java.
Java имеет определяемые пользователем метаданные в виде [аннотаций](https://docs.oracle.com/javase/tutorial/java/annotations/). Ключевой особенностью аннотаций является то, что они задаются в виде пар ключ-значение для инициализации своих элементов. Например, если нам нужна аннотация для отслеживания источника какого-то класса, мы можем определить её как
-```
+{% tabs annotations_5 %}
+{% tab 'Java' for=annotations_5 %}
+
+```java
@interface Source {
- public String URL();
+ public String url();
public String mail();
}
```
+{% endtab %}
+{% endtabs %}
+
А затем использовать следующим образом
-```
-@Source(URL = "https://coders.com/",
+{% tabs annotations_6 %}
+{% tab 'Java' for=annotations_6 %}
+
+```java
+@Source(url = "https://coders.com/",
mail = "support@coders.com")
-public class MyClass extends HisClass ...
+public class MyJavaClass extends TheirClass ...
```
+{% endtab %}
+{% endtabs %}
+
Использование аннотации в Scala похоже на вызов конструктора. Для создания экземпляра из Java аннотации необходимо использовать именованные аргументы:
-```
-@Source(URL = "https://coders.com/",
+{% tabs annotations_7 %}
+{% tab 'Scala 2 и 3' for=annotations_7 %}
+
+```scala
+@Source(url = "https://coders.com/",
mail = "support@coders.com")
class MyScalaClass ...
```
+{% endtab %}
+{% endtabs %}
+
Этот синтаксис достаточно перегруженный, если аннотация содержит только один элемент (без значения по умолчанию), поэтому, если имя указано как `value`, оно может быть применено в Java с помощью конструктора-подобного синтаксиса:
-```
+{% tabs annotations_8 %}
+{% tab 'Java' for=annotations_8 %}
+
+```java
@interface SourceURL {
public String value();
public String mail() default "";
}
```
+{% endtab %}
+{% endtabs %}
+
А затем можно использовать следующим образом
-```
+{% tabs annotations_9 %}
+{% tab 'Java' for=annotations_9 %}
+
+```java
@SourceURL("https://coders.com/")
-public class MyClass extends HisClass ...
+public class MyJavaClass extends TheirClass ...
```
+{% endtab %}
+{% endtabs %}
+
В этом случае Scala предоставляет такую же возможность
-```
+{% tabs annotations_10 %}
+{% tab 'Scala 2 и 3' for=annotations_10 %}
+
+```scala
@SourceURL("https://coders.com/")
class MyScalaClass ...
```
+{% endtab %}
+{% endtabs %}
+
Элемент `mail` был указан со значением по умолчанию, поэтому нам не нужно явно указывать его значение. Мы не можем смешивать эти два стиля в Java:
-```
+{% tabs annotations_11 %}
+{% tab 'Java' for=annotations_11 %}
+
+```java
@SourceURL(value = "https://coders.com/",
mail = "support@coders.com")
-public class MyClass extends HisClass ...
+public class MyJavaClass extends TheirClass ...
```
+{% endtab %}
+{% endtabs %}
+
Scala обеспечивает большую гибкость в этом отношении
-```
+{% tabs annotations_12 %}
+{% tab 'Scala 2 и 3' for=annotations_12 %}
+
+```scala
@SourceURL("https://coders.com/",
mail = "support@coders.com")
- class MyScalaClass ...
+class MyScalaClass ...
```
+
+{% endtab %}
+{% endtabs %}
diff --git a/_ru/tour/automatic-closures.md b/_ru/tour/automatic-closures.md
deleted file mode 100644
index 7de83279d8..0000000000
--- a/_ru/tour/automatic-closures.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-layout: tour
-title: Конструкция Автоматического Замыкания Зависимого Типа
-
-discourse: true
-language: ru
-partof: scala-tour
-num: 14
----
-
-Scala допускает использование в качестве параметров методов имена беспараметрических функций. При вызове такого метода фактические параметры для беспараметрических функций не вычисляются, а передается функция с нулем аргументов, которая захватывает вычисление соответствующего параметра (так называемый *вызов по имени*).
-
-Следующий код демонстрирует этот механизм:
-
- object TargetTest1 extends Application {
- def whileLoop(cond: => Boolean)(body: => Unit): Unit =
- if (cond) {
- body
- whileLoop(cond)(body)
- }
- var i = 10
- whileLoop (i > 0) {
- println(i)
- i -= 1
- }
- }
-
-Функция whileLoop принимает два параметра `cond` и `body`. При использовании функции значения этих параметров не вычисляются. Но всякий раз, когда параметры используются в теле `whileLoop`, их значение будет вычисляться заново через использование автоматически созданных неявно вызываемых функций. Таким образом, наш метод `whileLoop` реализует Java-подобный цикл while-loop со схемой рекурсивной реализации.
-
-Мы можем комбинировать использование [инфиксных/постфиксных операторов](operators.html) с этим механизмом для создания более сложных выражений (с хорошим синтаксисом).
-
-Вот реализация loop-unless выражения:
-
- object TargetTest2 extends Application {
- def loop(body: => Unit): LoopUnlessCond =
- new LoopUnlessCond(body)
- protected class LoopUnlessCond(body: => Unit) {
- def unless(cond: => Boolean) {
- body
- if (!cond) unless(cond)
- }
- }
- var i = 10
- loop {
- println("i = " + i)
- i -= 1
- } unless (i == 0)
- }
-Функция `loop` принимает только тело цикла и возвращает экземпляр класса `LoopUnlessCond` (который захватывает это тело цикла). Обратите внимание, что тело еще не вычислено. Класс `LoopUnlessCond` имеет метод `unless`, который мы можем использовать как *инфиксный оператор*. Таким образом, мы получаем вполне естественный синтаксис для нашего нового цикла: `loop { < выражение > } unless ( < условие > )`.
-
-
-Ниже приведен вывод выполнения `TargetTest2`:
-
- i = 10
- i = 9
- i = 8
- i = 7
- i = 6
- i = 5
- i = 4
- i = 3
- i = 2
- i = 1
diff --git a/_ru/tour/basics.md b/_ru/tour/basics.md
index f6c3788f4c..3d8590bfe7 100644
--- a/_ru/tour/basics.md
+++ b/_ru/tour/basics.md
@@ -1,92 +1,125 @@
---
layout: tour
title: Основы
-
-discourse: true
-
partof: scala-tour
-
num: 2
language: ru
next-page: unified-types
previous-page: tour-of-scala
-
---
На этой странице мы расскажем об основах Scala.
## Попробовать Scala в браузере.
-Вы можете запустить Scala в браузере с помощью ScalaFiddle.
+Вы можете запустить Scala в браузере с помощью Scastie.
-1. Зайдите на [https://scalafiddle.io](https://scalafiddle.io).
+1. Зайдите на [Scastie](https://scastie.scala-lang.org/).
2. Вставьте `println("Hello, world!")` в левую панель.
3. Нажмите кнопку "Run". Вывод отобразится в правой панели.
Это простой способ поэкспериментировать со Scala кодом без всяких настроек.
-Большинство примеров кода в этой документации также интегрированы с ScalaFiddle,
-поэтому вы можете поэкспериментировать с ними, просто нажав кнопку Run.
-
## Выражения
Выражения — это вычислимые утверждения.
+
+{% tabs expression %}
+{% tab 'Scala 2 и 3' for=expression %}
+
```scala mdoc
1 + 1
```
+
+{% endtab %}
+{% endtabs %}
+
Вы можете выводить результаты выражений, используя `println`.
-{% scalafiddle %}
+{% tabs println %}
+{% tab 'Scala 2 и 3' for=println %}
+
```scala mdoc
println(1) // 1
println(1 + 1) // 2
println("Hello!") // Hello!
println("Hello," + " world!") // Hello, world!
```
-{% endscalafiddle %}
+
+{% endtab %}
+{% endtabs %}
### Значения
Результаты выражений можно присваивать именам с помощью ключевого слова `val`.
+{% tabs val %}
+{% tab 'Scala 2 и 3' for=val %}
+
```scala mdoc
val x = 1 + 1
println(x) // 2
```
-Названные результаты, такие как `x` в примере, называются значениями.
+{% endtab %}
+{% endtabs %}
+
+Названные результаты, такие как `x` в примере, называются значениями.
Вызов значения не приводит к его повторному вычислению.
Значения не изменяемы и не могут быть переназначены.
+{% tabs val-error %}
+{% tab 'Scala 2 и 3' for=val-error %}
+
```scala mdoc:fail
x = 3 // Не компилируется.
```
+{% endtab %}
+{% endtabs %}
+
Типы значений могут быть выведены автоматически, но можно и явно указать тип, как показано ниже:
+{% tabs type-inference %}
+{% tab 'Scala 2 и 3' for=type-inference %}
+
```scala mdoc:nest
val x: Int = 1 + 1
```
-Обратите внимание, что объявление типа `Int` происходит после идентификатора `x`, следующим за `:`.
+{% endtab %}
+{% endtabs %}
+
+Обратите внимание, что объявление типа `Int` происходит после идентификатора `x`, следующим за `:`.
### Переменные
Переменные похожи на значения константы, за исключением того, что их можно присваивать заново. Вы можете объявить переменную с помощью ключевого слова `var`.
+{% tabs var %}
+{% tab 'Scala 2 и 3' for=var %}
+
```scala mdoc:nest
var x = 1 + 1
x = 3 // Компилируется потому что "x" объявлен с ключевым словом "var".
println(x * x) // 9
```
+{% endtab %}
+{% endtabs %}
+
Как и в случае со значениями, вы можете явно указать тип, если захотите:
+{% tabs type-inference-2 %}
+{% tab 'Scala 2 и 3' for=type-inference-2 %}
+
```scala mdoc:nest
var x: Int = 1 + 1
```
+{% endtab %}
+{% endtabs %}
## Блоки
@@ -94,6 +127,9 @@ var x: Int = 1 + 1
Результат последнего выражения в блоке будет результатом всего блока в целом.
+{% tabs blocks %}
+{% tab 'Scala 2 и 3' for=blocks %}
+
```scala mdoc
println({
val x = 1 + 1
@@ -101,79 +137,119 @@ println({
}) // 3
```
+{% endtab %}
+{% endtabs %}
+
## Функции
Функции — это выражения, которые принимают параметры.
Вы можете определить анонимную функцию (т.е. без имени), которая возвращает переданное число, прибавив к нему единицу:
+{% tabs anonymous-function %}
+{% tab 'Scala 2 и 3' for=anonymous-function %}
+
```scala mdoc
(x: Int) => x + 1
```
+{% endtab %}
+{% endtabs %}
+
Слева от `=>` находится список параметров. Справа — выражение, связанное с параметрами.
Вы также можете назвать функции.
-{% scalafiddle %}
+{% tabs named-function %}
+{% tab 'Scala 2 и 3' for=named-function %}
+
```scala mdoc
val addOne = (x: Int) => x + 1
println(addOne(1)) // 2
```
-{% endscalafiddle %}
+
+{% endtab %}
+{% endtabs %}
Функции могут принимать множество параметров.
-{% scalafiddle %}
+{% tabs multiple-parameters %}
+{% tab 'Scala 2 и 3' for=multiple-parameters %}
+
```scala mdoc
val add = (x: Int, y: Int) => x + y
println(add(1, 2)) // 3
```
-{% endscalafiddle %}
+
+{% endtab %}
+{% endtabs %}
Или вообще не принимать никаких параметров.
+{% tabs no-parameters %}
+{% tab 'Scala 2 и 3' for=no-parameters %}
+
```scala mdoc
val getTheAnswer = () => 42
println(getTheAnswer()) // 42
```
+{% endtab %}
+{% endtabs %}
+
## Методы
Методы выглядят и ведут себя очень похоже на функции, но между ними есть несколько принципиальных различий.
-Методы задаются ключевым словом `def`. За `def` следует имя, список параметров, возвращаемый тип и тело.
+Методы задаются ключевым словом `def`. За `def` следует имя, список параметров, возвращаемый тип и тело.
+
+{% tabs method %}
+{% tab 'Scala 2 и 3' for=method %}
-{% scalafiddle %}
```scala mdoc:nest
def add(x: Int, y: Int): Int = x + y
println(add(1, 2)) // 3
```
-{% endscalafiddle %}
+
+{% endtab %}
+{% endtabs %}
Обратите внимание, как объявлен возвращаемый тип сразу _после_ списка параметров и двоеточия `: Int`.
Методы могут принимать несколько списков параметров.
-{% scalafiddle %}
+{% tabs multiple-parameter-lists %}
+{% tab 'Scala 2 и 3' for=multiple-parameter-lists %}
+
```scala mdoc
def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier
println(addThenMultiply(1, 2)(3)) // 9
```
-{% endscalafiddle %}
+
+{% endtab %}
+{% endtabs %}
Или вообще ни одного списка параметров.
+{% tabs no-parameter-lists %}
+{% tab 'Scala 2 и 3' for=no-parameter-lists %}
+
```scala mdoc
def name: String = System.getProperty("user.name")
println("Hello, " + name + "!")
```
+{% endtab %}
+{% endtabs %}
+
Есть некоторые отличия от функций, но пока что их можно рассматривать как нечто похожее.
Методы также могут иметь многострочные выражения.
-{% scalafiddle %}
+{% tabs get-square-string class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=get-square-string %}
+
```scala mdoc
def getSquareString(input: Double): String = {
val square = input * input
@@ -181,7 +257,22 @@ def getSquareString(input: Double): String = {
}
println(getSquareString(2.5)) // 6.25
```
-{% endscalafiddle %}
+
+{% endtab %}
+
+{% tab 'Scala 3' for=get-square-string %}
+
+```scala
+def getSquareString(input: Double): String =
+ val square = input * input
+ square.toString
+
+println(getSquareString(2.5)) // 6.25
+```
+
+{% endtab %}
+
+{% endtabs %}
Последнее выражение в теле становится возвращаемым значением метода (у Scala есть ключевое слово `return`, но оно практически не используется).
@@ -189,55 +280,129 @@ println(getSquareString(2.5)) // 6.25
Вы можете объявлять классы используя ключевое слово `class`, за которым следует его имя и параметры конструктора.
+{% tabs greeter-definition class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=greeter-definition %}
+
```scala mdoc
class Greeter(prefix: String, suffix: String) {
def greet(name: String): Unit =
println(prefix + name + suffix)
}
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=greeter-definition %}
+
+```scala
+class Greeter(prefix: String, suffix: String):
+ def greet(name: String): Unit =
+ println(prefix + name + suffix)
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Возвращаемый тип метода `greet` это `Unit`, используется тогда, когда не имеет смысла что-либо возвращать. Аналогично `void` в Java и C. Поскольку каждое выражение Scala должно иметь какое-то значение, то при отсутствии возвращающегося значения возвращается экземпляр типа Unit. Явным образом его можно задать как `()`, он не несет какой-либо информации.
Вы можете создать экземпляр класса, используя ключевое слово `new`.
-```scala mdoc
+{% tabs greeter-usage class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=greeter-usage %}
+
+```scala mdoc:nest
val greeter = new Greeter("Hello, ", "!")
greeter.greet("Scala developer") // Hello, Scala developer!
```
+{% endtab %}
+
+{% tab 'Scala 3' for=greeter-usage %}
+
+```scala
+val greeter = Greeter("Hello, ", "!")
+greeter.greet("Scala developer") // Hello, Scala developer!
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Позже мы рассмотрим классы [подробнее](classes.html).
## Классы-образцы (Case Class)
В Scala есть специальный тип класса, который называется классом-образцом (case class). По умолчанию такие классы неизменны и сравниваются по значению из конструктора. Вы можете объявлять классы-образцы с помощью ключевых слов `case class`.
+{% tabs case-class-definition %}
+{% tab 'Scala 2 и 3' for=case-class-definition %}
+
```scala mdoc
case class Point(x: Int, y: Int)
```
+{% endtab %}
+{% endtabs %}
+
Можно создавать экземпляры класса-образца без использования ключевого слова `new`.
+{% tabs case-class-creation %}
+{% tab 'Scala 2 и 3' for=case-class-creation %}
+
```scala mdoc
val point = Point(1, 2)
val anotherPoint = Point(1, 2)
val yetAnotherPoint = Point(2, 2)
```
+{% endtab %}
+{% endtabs %}
+
Они сравниваются по значению.
+{% tabs compare-case-class-equality class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=compare-case-class-equality %}
+
```scala mdoc
if (point == anotherPoint) {
- println(point + " and " + anotherPoint + " are the same.")
+ println(s"$point and $anotherPoint are the same.")
} else {
- println(point + " and " + anotherPoint + " are different.")
+ println(s"$point and $anotherPoint are different.")
} // Point(1,2) и Point(1,2) одни и те же.
if (point == yetAnotherPoint) {
- println(point + " and " + yetAnotherPoint + " are the same.")
+ println(s"$point and $yetAnotherPoint are the same.")
} else {
- println(point + " and " + yetAnotherPoint + " are different.")
+ println(s"$point and $yetAnotherPoint are different.")
} // Point(1,2) и Point(2,2) разные.
```
+{% endtab %}
+
+{% tab 'Scala 3' for=compare-case-class-equality %}
+
+```scala
+if point == anotherPoint then
+ println(s"$point and $anotherPoint are the same.")
+else
+ println(s"$point and $anotherPoint are different.")
+// Point(1,2) и Point(1,2) одни и те же.
+
+if point == yetAnotherPoint then
+ println(s"$point and $yetAnotherPoint are the same.")
+else
+ println(s"$point and $yetAnotherPoint are different.")
+// Point(1,2) и Point(2,2) разные.
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Есть еще много деталей, которые мы бы хотели рассказать про классы-образцы; мы уверены, что вы влюбитесь в них! Обязательно рассмотрим их [позже](case-classes.html).
## Объекты
@@ -246,6 +411,10 @@ if (point == yetAnotherPoint) {
Вы можете задать объекты при помощи ключевого слова `object`.
+{% tabs id-factory-definition class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=id-factory-definition %}
+
```scala mdoc
object IdFactory {
private var counter = 0
@@ -256,8 +425,27 @@ object IdFactory {
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=id-factory-definition %}
+
+```scala
+object IdFactory:
+ private var counter = 0
+ def create(): Int =
+ counter += 1
+ counter
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Вы можете сразу получить доступ к объекту, ссылаясь на его имя.
+{% tabs id-factory-usage %}
+{% tab 'Scala 2 и 3' for=id-factory-usage %}
+
```scala mdoc
val newId: Int = IdFactory.create()
println(newId) // 1
@@ -265,6 +453,9 @@ val newerId: Int = IdFactory.create()
println(newerId) // 2
```
+{% endtab %}
+{% endtabs %}
+
Позже мы рассмотрим объекты [подробнее](singleton-objects.html).
## Трейты
@@ -273,15 +464,35 @@ println(newerId) // 2
Объявить трейт можно с помощью ключевого слова `trait`.
+{% tabs greeter-trait-def class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=greeter-trait-def %}
+
```scala mdoc:nest
trait Greeter {
def greet(name: String): Unit
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=greeter-trait-def %}
+
+```scala
+trait Greeter:
+ def greet(name: String): Unit
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Трейты также могут иметь реализации методов и полей, которые предполагается использовать умолчанию.
-{% scalafiddle %}
+{% tabs greeter-trait-def-impl class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=greeter-trait-def-impl %}
+
```scala mdoc:reset
trait Greeter {
def greet(name: String): Unit =
@@ -289,8 +500,26 @@ trait Greeter {
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=greeter-trait-def-impl %}
+
+```scala
+trait Greeter:
+ def greet(name: String): Unit =
+ println("Hello, " + name + "!")
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Вы можете наследовать свойства трейтов, используя ключевое слово `extends` и переопределять реализацию с помощью ключевого слова `override`.
+{% tabs greeter-implementations class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=greeter-implementations %}
+
```scala mdoc
class DefaultGreeter extends Greeter
@@ -306,7 +535,28 @@ greeter.greet("Scala developer") // Hello, Scala developer!
val customGreeter = new CustomizableGreeter("How are you, ", "?")
customGreeter.greet("Scala developer") // How are you, Scala developer?
```
-{% endscalafiddle %}
+
+{% endtab %}
+
+{% tab 'Scala 3' for=greeter-implementations %}
+
+```scala
+class DefaultGreeter extends Greeter
+
+class CustomizableGreeter(prefix: String, postfix: String) extends Greeter:
+ override def greet(name: String): Unit =
+ println(prefix + name + postfix)
+
+val greeter = DefaultGreeter()
+greeter.greet("Scala developer") // Hello, Scala developer!
+
+val customGreeter = CustomizableGreeter("How are you, ", "?")
+customGreeter.greet("Scala developer") // How are you, Scala developer?
+```
+
+{% endtab %}
+
+{% endtabs %}
Здесь `DefaultGreeter` наследуется только от одного трейта, но можно наследоваться от нескольких.
@@ -314,14 +564,38 @@ customGreeter.greet("Scala developer") // How are you, Scala developer?
## Главный метод
-Главный метод является отправной точкой в программе.
+Главный метод является отправной точкой в программе.
Для Виртуальной Машины Java требуется, чтобы главный метод назывался `main` и принимал один аргумент, массив строк.
Используя объект, можно задать главный метод следующим образом:
+{% tabs hello-world-demo class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=hello-world-demo %}
+
+In Scala 2 you must define a main method manually. Using an object, you can define the main method as follows:
+
```scala mdoc
object Main {
def main(args: Array[String]): Unit =
println("Hello, Scala developer!")
}
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=hello-world-demo %}
+
+In Scala 3, with the `@main` annotation, a main method is automatically generated from a method as follows:
+
+```scala
+@main def hello() = println("Hello, Scala developer!")
+```
+
+{% endtab %}
+
+{% endtabs %}
+
+## Дополнительные ресурсы
+
+- Обзор [Scala book](/ru/scala3/book/taste-intro.html)
diff --git a/_ru/tour/by-name-parameters.md b/_ru/tour/by-name-parameters.md
index 4a1a4d4417..06c9a32063 100644
--- a/_ru/tour/by-name-parameters.md
+++ b/_ru/tour/by-name-parameters.md
@@ -1,26 +1,32 @@
---
layout: tour
title: Вызов по имени
-
-discourse: true
-
partof: scala-tour
-
num: 31
language: ru
next-page: annotations
previous-page: operators
-
---
_Вызов параметров по имени_ - это когда значение параметра вычисляется только в момент вызова параметра. Этот способ противоположен _вызову по значению_. Чтоб вызов параметра был по имени, необходимо просто указать `=>` перед его типом.
+
+{% tabs by-name-parameters_1 %}
+{% tab 'Scala 2 и 3' for=by-name-parameters_1 %}
+
```scala mdoc
def calculate(input: => Int) = input * 37
```
+
+{% endtab %}
+{% endtabs %}
+
Преимущество вызова параметров по имени заключается в том, что они не вычисляются если не используются в теле функции. С другой стороны плюсы вызова параметров по значению в том, что они вычисляются только один раз.
Вот пример того, как мы можем реализовать условный цикл:
+{% tabs by-name-parameters_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=by-name-parameters_2 %}
+
```scala mdoc
def whileLoop(condition: => Boolean)(body: => Unit): Unit =
if (condition) {
@@ -35,8 +41,29 @@ whileLoop (i > 0) {
i -= 1
} // выведет 2 1
```
-Метод `whileLoop` использует несколько списков параметров - условие и тело цикла. Если `condition` является верным, выполняется `body`, а затем выполняется рекурсивный вызов whileLoop. Если `condition` является ложным, то тело никогда не вычисляется, тк у нас стоит `=>` перед типом `body`.
+
+{% endtab %}
+{% tab 'Scala 3' for=by-name-parameters_2 %}
+
+```scala
+def whileLoop(condition: => Boolean)(body: => Unit): Unit =
+ if condition then
+ body
+ whileLoop(condition)(body)
+
+var i = 2
+
+whileLoop (i > 0) {
+ println(i)
+ i -= 1
+} // выведет 2 1
+```
+
+{% endtab %}
+{% endtabs %}
+
+Метод `whileLoop` использует несколько списков параметров - условие и тело цикла. Если `condition` является верным, выполняется `body`, а затем выполняется рекурсивный вызов whileLoop. Если `condition` является ложным, то тело никогда не вычисляется, тк у нас стоит `=>` перед типом `body`.
Теперь, когда мы передаем `i > 0` как наше условие `condition` и `println(i); i-= 1` как тело `body`, код ведет себя также как обычный цикл в большинстве языков программирования.
-Такая возможность откладывать вычисления параметра до его использования может помочь повысить производительность, отсекая не нужные вычисления при определенных условиях.
+Такая возможность откладывать вычисления параметра до его использования может помочь повысить производительность, отсекая не нужные вычисления при определенных условиях.
diff --git a/_ru/tour/case-classes.md b/_ru/tour/case-classes.md
index 9a49c560dd..467fc0655e 100644
--- a/_ru/tour/case-classes.md
+++ b/_ru/tour/case-classes.md
@@ -1,53 +1,90 @@
---
layout: tour
title: Классы Образцы
-
-discourse: true
-
partof: scala-tour
-
num: 11
language: ru
next-page: pattern-matching
previous-page: multiple-parameter-lists
prerequisite-knowledge: classes, basics, mutability
-
---
-Классы образцы (Case classes) похожи на обычные классы с несколькими ключевыми отличиями, о которых мы поговорим ниже. Классы образцы хороши для моделирования неизменяемых данных. На следующей странице обзора вы увидите, насколько они полезны для участия в [сопоставлении с примером](pattern-matching.html).
+Классы образцы (Case classes) похожи на обычные классы с несколькими ключевыми отличиями, о которых мы поговорим ниже.
+Классы образцы хороши для моделирования неизменяемых данных.
+На следующей странице обзора вы увидите, насколько они полезны для участия в [сопоставлении с примером](pattern-matching.html).
## Объявление класса образца
+
Минимальный вариант объявления класса образца: указание ключевого слова `case class`, название и список параметров (которые могут быть пустыми). Пример:
+
+{% tabs case-classe_Book %}
+
+{% tab 'Scala 2 и 3' for=case-classe_Book %}
+
```scala mdoc
case class Book(isbn: String)
val frankenstein = Book("978-0486282114")
```
-Обратите внимание, что ключевое слово `new` не было использовано для создания экземпляра класса `Book`. Это связано с тем, что классы образцы по умолчанию имеют объект компаньон с методом `apply`, который берет на себя заботу о создании экземпляра класса.
+
+{% endtab %}
+
+{% endtabs %}
+
+Обратите внимание, что ключевое слово `new` не было использовано для создания экземпляра класса `Book`.
+Это связано с тем, что классы образцы по умолчанию имеют объект компаньон с методом `apply`,
+который берет на себя заботу о создании экземпляра класса.
При создании класса образца с параметрами, эти параметры являются публичными и неизменяемыми.
+
+{% tabs case-classe_Message_define %}
+
+{% tab 'Scala 2 и 3' for=case-classe_Message_define %}
+
```
case class Message(sender: String, recipient: String, body: String)
val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?")
-println(message1.sender) // prints guillaume@quebec.ca
+println(message1.sender) // печатает guillaume@quebec.ca
message1.sender = "travis@washington.us" // эта строка не компилируется
```
+
+{% endtab %}
+
+{% endtabs %}
+
Вы не можете переназначить `message1.sender`, потому что это `val` (т.е. константа). Возможно использовать `var` в классах образцах, но это не рекомендуется.
## Сравнение
+
Классы образцы сравниваются по структуре, а не по ссылкам:
-```
+
+{% tabs case-classe_Message_compare %}
+
+{% tab 'Scala 2 и 3' for=case-classe_Message_compare %}
+
+```scala mdoc
case class Message(sender: String, recipient: String, body: String)
val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?")
val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?")
val messagesAreTheSame = message2 == message3 // true
```
+
+{% endtab %}
+
+{% endtabs %}
+
Даже если `message2` и `message3` ссылаются на разные объекты, значения каждого из них равны.
## Копирование
+
Вы можете создать копию экземпляра класса образца, просто воспользовавшись методом `copy`. При этом по желанию можно изменить аргументы конструктора.
+
+{% tabs case-classe_Message_copy %}
+
+{% tab 'Scala 2 и 3' for=case-classe_Message_copy %}
+
```
case class Message(sender: String, recipient: String, body: String)
val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg")
@@ -56,4 +93,13 @@ message5.sender // travis@washington.us
message5.recipient // claire@bourgogne.fr
message5.body // "Me zo o komz gant ma amezeg"
```
+
+{% endtab %}
+
+{% endtabs %}
+
Получатель `message4` использует в качестве отправителя `message5`, кроме параметра `body` который был скопирован из `message4`.
+
+## Дополнительные ресурсы
+
+- Дополнительная информация о классах образцах доступна в [Scala Book](/ru/scala3/book/domain-modeling-tools.html#case-class-ы)
diff --git a/_ru/tour/classes.md b/_ru/tour/classes.md
index db66150841..75701bb107 100644
--- a/_ru/tour/classes.md
+++ b/_ru/tour/classes.md
@@ -1,30 +1,53 @@
---
layout: tour
title: Классы
-
-discourse: true
-
partof: scala-tour
-
num: 4
language: ru
next-page: traits
previous-page: unified-types
topics: classes
prerequisite-knowledge: no-return-keyword, type-declaration-syntax, string-interpolation, procedures
-
---
Классы в Scala являются основами для создания объектов. Они могут содержать методы, константы, переменные, типы, объекты, трейты и классы, которые в совокупности называются _членами_. Типы, объекты и трейты будут рассмотрены позже в ходе нашего обзора.
## Объявление класса
+
Минимальное объявление класса - это просто ключевое слово `class` и его имя. Имена классов должны быть написаны с заглавной буквы.
+
+{% tabs class-minimal-user class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=class-minimal-user %}
+
```scala mdoc
class User
val user1 = new User
```
-Ключевое слово `new` используется для создания экземпляра класса. `User` имеет конструктор по умолчанию, который не принимает аргументов, так как конструктор не был определен. Однако обычно используется и конструктор, и тело класса. Пример объявления класса Point приведен ниже:
+
+Ключевое слово `new` используется для создания экземпляра класса.
+{% endtab %}
+
+{% tab 'Scala 3' for=class-minimal-user %}
+
+```scala
+class User
+
+val user1 = User()
+```
+
+Чтобы создать экземпляр класса, мы вызываем его как функцию: `User()`.
+Также можно явно использовать ключевое слово `new`: `new User()` - хотя обычно это опускается.
+{% endtab %}
+
+{% endtabs %}
+
+`User` имеет конструктор по умолчанию, который не принимает аргументов, так как конструктор не был определен. Однако обычно используется и конструктор, и тело класса. Пример объявления класса Point приведен ниже:
+
+{% tabs class-point-example class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=class-point-example %}
```scala mdoc
class Point(var x: Int, var y: Int) {
@@ -39,10 +62,34 @@ class Point(var x: Int, var y: Int) {
}
val point1 = new Point(2, 3)
-point1.x // 2
-println(point1) // prints (2, 3)
+println(point1.x) // выводит 2
+println(point1) // выводит (2, 3)
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=class-point-example %}
+
+```scala
+class Point(var x: Int, var y: Int):
+
+ def move(dx: Int, dy: Int): Unit =
+ x = x + dx
+ y = y + dy
+
+ override def toString: String =
+ s"($x, $y)"
+end Point
+
+val point1 = Point(2, 3)
+println(point1.x) // выводит 2
+println(point1) // выводит (2, 3)
```
+{% endtab %}
+
+{% endtabs %}
+
В этом классе у `Point` есть четыре члена: переменные `x` и `y` и методы `move` и `toString`.
В отличие от многих других языков, основной конструктор находится в сигнатуре класса `(var x: Int, var y: Int)`. Метод `move` принимает два целочисленных аргумента и возвращает значение Unit `()` - это пустое множество, которое не содержит никакой информации. Примерно соответствует `void` в Java-подобных языках. С другой стороны, `toString` не принимает никаких аргументов, а возвращает значение `String`. Поскольку `toString` переопределяет `toString` из [`AnyRef`](unified-types.html), он помечается ключевым словом `override`.
@@ -50,61 +97,193 @@ println(point1) // prints (2, 3)
Конструкторы могут иметь необязательные параметры, если указать их значения по умолчанию как в примере:
+{% tabs class-point-with-default-values class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=class-point-with-default-values %}
+
```scala mdoc:nest
class Point(var x: Int = 0, var y: Int = 0)
-val origin = new Point // x и y оба равны 0
-val point1 = new Point(1)
-println(point1.x) // выводит 1
+val origin = new Point // x и y оба равны 0
+val point1 = new Point(1) // x равен 1, а y равен 0
+println(point1) // выводит (1, 0)
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=class-point-with-default-values %}
+
+```scala
+class Point(var x: Int = 0, var y: Int = 0)
+
+val origin = Point() // x и y оба равны 0
+val point1 = Point(1) // x равен 1, а y равен 0
+println(point1) // выводит (1, 0)
```
+{% endtab %}
+
+{% endtabs %}
+
В этой версии класса `Point`, `x` и `y` имеют значение по умолчанию `0`, поэтому аргументов не требуется. Однако, поскольку конструктор считывает аргументы слева направо, если вы просто хотите передать значение `y`, то вам нужно будет указать задаваемый параметр.
+
+{% tabs class-point-named-argument class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=class-point-named-argument %}
+
```scala mdoc:nest
class Point(var x: Int = 0, var y: Int = 0)
-val point2 = new Point(y=2)
-println(point2.y) // выводит 2
+val point2 = new Point(y = 2)
+println(point2) // выводит (0, 2)
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=class-point-named-argument %}
+
+```scala
+class Point(var x: Int = 0, var y: Int = 0)
+val point2 = Point(y = 2)
+println(point2) // выводит (0, 2)
```
+{% endtab %}
+
+{% endtabs %}
+
Что также является хорошей практикой для повышения ясности кода.
## Скрытые члены и синтаксис Геттер/Сеттер (получатель/установщик значений)
+
По умолчанию члены класса являются открытыми для внешнего доступа (публичными). Используйте модификатор `private`, чтобы скрыть их от внешнего доступа.
-```scala mdoc:nest
+
+{% tabs class-point-private-getter-setter class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=class-point-private-getter-setter %}
+
+```scala mdoc:reset
class Point {
private var _x = 0
private var _y = 0
private val bound = 100
- def x = _x
- def x_= (newValue: Int): Unit = {
- if (newValue < bound) _x = newValue else printWarning
+ def x: Int = _x
+ def x_=(newValue: Int): Unit = {
+ if (newValue < bound)
+ _x = newValue
+ else
+ printWarning()
}
- def y = _y
- def y_= (newValue: Int): Unit = {
- if (newValue < bound) _y = newValue else printWarning
+ def y: Int = _y
+ def y_=(newValue: Int): Unit = {
+ if (newValue < bound)
+ _y = newValue
+ else
+ printWarning()
}
- private def printWarning = println("WARNING: Out of bounds")
+ private def printWarning(): Unit =
+ println("WARNING: Out of bounds")
}
val point1 = new Point
point1.x = 99
point1.y = 101 // выводит предупреждение (printWarning)
```
-В данной версии класса `Point` данные хранятся в скрытых переменных `_x` и `_y`. Существуют методы `def x` и `def y` для доступа к скрытым данным. Методы `def x_=` и `def y_=` (сеттеры) предназначены для проверки и установки значения `_x` и `_y`. Обратите внимание на специальный синтаксис для сеттеров: метод `_=` применяется к имени геттера.
+
+{% endtab %}
+
+{% tab 'Scala 3' for=class-point-private-getter-setter %}
+
+```scala
+class Point:
+ private var _x = 0
+ private var _y = 0
+ private val bound = 100
+
+ def x: Int = _x
+ def x_=(newValue: Int): Unit =
+ if newValue < bound then
+ _x = newValue
+ else
+ printWarning()
+
+ def y: Int = _y
+ def y_=(newValue: Int): Unit =
+ if newValue < bound then
+ _y = newValue
+ else
+ printWarning()
+
+ private def printWarning(): Unit =
+ println("WARNING: Out of bounds")
+end Point
+
+val point1 = Point()
+point1.x = 99
+point1.y = 101 // выводит предупреждение (printWarning)
+```
+
+{% endtab %}
+
+{% endtabs %}
+
+В данной версии класса `Point` данные хранятся в скрытых переменных `_x` и `_y`. Существуют методы `def x` и `def y` для доступа к скрытым данным. Методы `def x_=` и `def y_=` (сеттеры) предназначены для проверки и установки значения `_x` и `_y`. Обратите внимание на специальный синтаксис для сеттеров: метод `_=` применяется к имени геттера.
Первичные параметры конструктора с параметрами `val` и `var` являются общедоступными. Однако, поскольку `val` - это константа, то нельзя писать следующее.
+
+{% tabs class-point-cannot-set-val class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=class-point-cannot-set-val %}
+
```scala mdoc:fail
class Point(val x: Int, val y: Int)
val point = new Point(1, 2)
point.x = 3 // <-- не компилируется
```
+{% endtab %}
+
+{% tab 'Scala 3' for=class-point-cannot-set-val %}
+
+```scala
+class Point(val x: Int, val y: Int)
+val point = Point(1, 2)
+point.x = 3 // <-- не компилируется
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Параметры без `val` или `var` являются скрытыми от внешнего доступа и видимы только внутри класса.
+
+{% tabs class-point-non-val-ctor-param class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=class-point-non-val-ctor-param %}
+
```scala mdoc:fail
class Point(x: Int, y: Int)
val point = new Point(1, 2)
point.x // <-- не компилируется
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=class-point-non-val-ctor-param %}
+
+```scala
+class Point(x: Int, y: Int)
+val point = Point(1, 2)
+point.x // <-- не компилируется
+```
+
+{% endtab %}
+
+{% endtabs %}
+
+## Дополнительные ресурсы
+
+- Узнайте больше о классах в [Scala Book](/ru/scala3/book/domain-modeling-tools.html#классы)
+- Как использовать [вспомогательные конструкторы классов](/ru/scala3/book/domain-modeling-tools.html#вспомогательные-конструкторы)
diff --git a/_ru/tour/compound-types.md b/_ru/tour/compound-types.md
index eb861afbfd..876bbaf42a 100644
--- a/_ru/tour/compound-types.md
+++ b/_ru/tour/compound-types.md
@@ -1,25 +1,26 @@
---
layout: tour
title: Составные Типы
-
-discourse: true
-
partof: scala-tour
-
num: 24
language: ru
next-page: self-types
previous-page: abstract-type-members
-
---
-Иногда необходимо выразить, то что тип объекта является подтипом нескольких других типов. В Scala это можно выразить с помощью *составных типов*, которые являются объединением нескольких типов объектов.
+Иногда необходимо выразить, то что тип объекта является подтипом нескольких других типов.
+
+В Scala это можно выразить с помощью _типов пересечений_ (или _составных типов_ в Scala 2),
+которые являются объединением нескольких типов объектов.
Предположим, у нас есть два трейта: `Cloneable` и `Resetable`:
+{% tabs compound-types_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=compound-types_1 %}
+
```scala mdoc
trait Cloneable extends java.lang.Cloneable {
- override def clone(): Cloneable = {
+ override def clone(): Cloneable = { // создает публичный метод 'clone'
super.clone().asInstanceOf[Cloneable]
}
}
@@ -28,9 +29,26 @@ trait Resetable {
}
```
-Теперь предположим, что мы хотим написать функцию `cloneAndReset`, которая берет объект, клонирует его и сбрасывает (Reset) состояние исходного объекта:
+{% endtab %}
+{% tab 'Scala 3' for=compound-types_1 %}
+```scala
+trait Cloneable extends java.lang.Cloneable:
+ override def clone(): Cloneable = // создает публичный метод 'clone'
+ super.clone().asInstanceOf[Cloneable]
+trait Resetable:
+ def reset: Unit
```
+
+{% endtab %}
+{% endtabs %}
+
+Теперь предположим, что мы хотим написать функцию `cloneAndReset`, которая берет объект, клонирует его и сбрасывает (Reset) состояние исходного объекта:
+
+{% tabs compound-types_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=compound-types_2 %}
+
+```scala mdoc:fail
def cloneAndReset(obj: ?): Cloneable = {
val cloned = obj.clone()
obj.reset
@@ -38,17 +56,49 @@ def cloneAndReset(obj: ?): Cloneable = {
}
```
-Возникает вопрос, какой тип параметр `obj` должна принимать наша объединённая функция. Если это `Cloneable`, то объект может использовать метод `clone`, но не `reset`; если это `Resetable` мы можем использовать метод `reset`, но нет операции `clone`. Чтобы избежать приведения типа в такой ситуации, мы можем указать, что тип `obj` является и `Cloneable`, и `Resetable`. Этот совместный тип в Scala записывается как: `Cloneable with Resetable`.
+{% endtab %}
+{% tab 'Scala 3' for=compound-types_2 %}
+
+```scala
+def cloneAndReset(obj: ?): Cloneable =
+ val cloned = obj.clone()
+ obj.reset
+ cloned
+```
+
+{% endtab %}
+{% endtabs %}
+
+Возникает вопрос, какой тип параметра `obj` должна принимать наша объединённая функция. Если это `Cloneable`, то объект может использовать метод `clone`, но не `reset`; если это `Resetable` мы можем использовать метод `reset`, но нет операции `clone`. Чтобы избежать приведения типа в такой ситуации, мы можем указать, что тип `obj` является и `Cloneable`, и `Resetable`.
+
+{% tabs compound-types_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=compound-types_3 %}
+Этот совместный тип в Scala записывается как: `Cloneable with Resetable`.
Вот обновленная функция:
-```
+```scala mdoc:fail
def cloneAndReset(obj: Cloneable with Resetable): Cloneable = {
//...
}
```
-Составные типы могут состоять из нескольких типов объектов, и они могут содержать единый доработанный объект, в котором будут доработаны характеристики существующих членов объекта.
-Общая форма записи: `A with B with C ... { доработанный объект }`
+Обратите внимание, что у вас может быть более двух типов: `A with B with C with ...`.
+Это означает то же самое, что и: `(...(A with B) with C) with ... )`
+
+{% endtab %}
+{% tab 'Scala 3' for=compound-types_3 %}
+Этот совместный тип в Scala записывается как: `Cloneable & Resetable`.
+
+Вот обновленная функция:
+
+```scala
+def cloneAndReset(obj: Cloneable & Resetable): Cloneable = {
+ //...
+}
+```
-Пример использования таких доработок приведен на странице об [объединении классов с примесями](mixin-class-composition.html).
+Обратите внимание, что у вас может быть более двух типов: `A & B & C & ...`.
+`&` является ассоциативным, поэтому скобки могут быть добавлены вокруг любой части без изменения значения.
+{% endtab %}
+{% endtabs %}
diff --git a/_ru/tour/default-parameter-values.md b/_ru/tour/default-parameter-values.md
index 72ab55e786..c45b5dd419 100644
--- a/_ru/tour/default-parameter-values.md
+++ b/_ru/tour/default-parameter-values.md
@@ -1,20 +1,18 @@
---
layout: tour
title: Значения Параметров По умолчанию
-
-discourse: true
-
partof: scala-tour
-
num: 33
language: ru
next-page: named-arguments
previous-page: classes
prerequisite-knowledge: named-arguments, function syntax
-
---
-Scala предоставляет возможность задавать значения параметров по умолчанию, что позволяет лишний раз не указывать параметры.
+Scala предоставляет возможность задавать значения параметров по умолчанию, что позволяет лишний раз не указывать параметры.
+
+{% tabs default-parameter-values-1 %}
+{% tab 'Scala 2 и 3' for=default-parameter-values-1 %}
```scala mdoc
def log(message: String, level: String = "INFO") = println(s"$level: $message")
@@ -23,22 +21,41 @@ log("System starting") // выведет "INFO: System starting"
log("User not found", "WARNING") // выведет "WARNING: User not found"
```
+{% endtab %}
+{% endtabs %}
+
У параметра `level` есть значение по умолчанию, поэтому он необязателен. В последней строке аргумент `"WARNING"` переназначает аргумент по умолчанию `"INFO"`. Вместо того чтоб использовать перегруженные методы в Java, вы можете просто указать дополнительные параметры как параметры по умолчанию для достижения того же эффекта. Однако, если при вызове пропущен хотя бы один аргумент, все остальные аргументы должны вызываться с указанием конкретного имени аргумента.
+{% tabs default-parameter-values-2 %}
+{% tab 'Scala 2 и 3' for=default-parameter-values-2 %}
+
```scala mdoc
class Point(val x: Double = 0, val y: Double = 0)
val point1 = new Point(y = 1)
```
+
+{% endtab %}
+{% endtabs %}
+
Так мы можем указать что `y = 1`.
Обратите внимание, что параметры по умолчанию в Scala, при вызове из Java кода, являются обязательными:
+{% tabs default-parameter-values-3 %}
+{% tab 'Scala 2 и 3' for=default-parameter-values-3 %}
+
```scala mdoc:reset
// Point.scala
class Point(val x: Double = 0, val y: Double = 0)
```
+{% endtab %}
+{% endtabs %}
+
+{% tabs default-parameter-values-4 %}
+{% tab 'Java' for=default-parameter-values-4 %}
+
```java
// Main.java
public class Main {
@@ -47,3 +64,37 @@ public class Main {
}
}
```
+
+{% endtab %}
+{% endtabs %}
+
+### Параметры по умолчанию для перегруженных методов
+
+Scala не позволяет определять два метода с параметрами по умолчанию и с одинаковым именем (перегруженные методы).
+Важная причина этого - избежание двусмысленности, которая может быть вызвана наличием параметров по умолчанию.
+Чтобы проиллюстрировать проблему, давайте рассмотрим определение методов, представленных ниже:
+
+{% tabs default-parameter-values-5 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+
+```scala mdoc:fail
+object A {
+ def func(x: Int = 34): Unit
+ def func(y: String = "abc"): Unit
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' %}
+
+```scala
+object A:
+ def func(x: Int = 34): Unit
+ def func(y: String = "abc"): Unit
+```
+
+{% endtab %}
+{% endtabs %}
+
+Если мы вызываем `A.func()`, компилятор не может узнать,
+намеревался ли программист вызвать `func(x: Int = 34)` или `func(y: String = "abc")`.
diff --git a/_ru/tour/extractor-objects.md b/_ru/tour/extractor-objects.md
index 0c968f36cd..f93981cd6c 100644
--- a/_ru/tour/extractor-objects.md
+++ b/_ru/tour/extractor-objects.md
@@ -1,26 +1,25 @@
---
layout: tour
title: Объект Экстрактор
-
-discourse: true
-
partof: scala-tour
-
num: 16
language: ru
next-page: for-comprehensions
previous-page: regular-expression-patterns
-
---
Объект Экстрактор (объект распаковщик или extractor object) - это объект с методом `unapply`. В то время как метод `apply` обычно действует как конструктор, который принимает аргументы и создает объект, метод `unapply` действует обратным образом, он принимает объект и пытается извлечь и вернуть аргументы из которых он (возможно) был создан. Чаще всего этот метод используется в функциях сопоставления с примером и в частично определенных функциях.
+{% tabs extractor-objects_definition class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=extractor-objects_definition %}
+
```scala mdoc
import scala.util.Random
object CustomerID {
- def apply(name: String) = s"$name--${Random.nextLong}"
+ def apply(name: String) = s"$name--${Random.nextLong()}"
def unapply(customerID: String): Option[String] = {
val stringArray: Array[String] = customerID.split("--")
@@ -34,32 +33,82 @@ customer1ID match {
case _ => println("Could not extract a CustomerID")
}
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=extractor-objects_definition %}
+
+```scala
+import scala.util.Random
+
+object CustomerID:
+
+ def apply(name: String) = s"$name--${Random.nextLong()}"
+
+ def unapply(customerID: String): Option[String] =
+ val stringArray: Array[String] = customerID.split("--")
+ if stringArray.tail.nonEmpty then Some(stringArray.head) else None
+
+val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908
+customer1ID match
+ case CustomerID(name) => println(name) // выведет Sukyoung
+ case _ => println("Could not extract a CustomerID")
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Метод `apply` создает `CustomerID` из строки `name`. `unapply` делает обратное, чтобы вернуть `name` обратно. Когда мы вызываем `CustomerID("Sukyoung")`, это сокращенный синтаксис вызова `CustomerID.apply("Sukyoung")`. Когда мы вызываем `case CustomerID(name) => println(name)`, мы на самом деле вызываем метод `unapply`.
При объявлении нового значения можно использовать пример, в котором значение для инициализации переменной получается через извлечение, используя метод `unapply`.
+{% tabs extractor-objects_use-case-1 %}
+
+{% tab 'Scala 2 и 3' for=extractor-objects_use-case-1 %}
+
```scala mdoc
val customer2ID = CustomerID("Nico")
val CustomerID(name) = customer2ID
println(name) // выведет Nico
```
+{% endtab %}
+
+{% endtabs %}
+
Что эквивалентно `val name = CustomerID.unapply(customer2ID).get`.
+{% tabs extractor-objects_use-case-2 %}
+
+{% tab 'Scala 2 и 3' for=extractor-objects_use-case-2 %}
+
```scala mdoc
val CustomerID(name2) = "--asdfasdfasdf"
```
+{% endtab %}
+
+{% endtabs %}
+
Если совпадений нет, то бросается `scala.MatchError`:
+{% tabs extractor-objects_use-case-3 %}
+
+{% tab 'Scala 2 и 3' for=extractor-objects_use-case-3 %}
+
```scala mdoc:crash
val CustomerID(name3) = "-asdfasdfasdf"
```
+{% endtab %}
+
+{% endtabs %}
+
Возвращаемый тип `unapply` выбирается следующим образом:
-* Если это всего лишь тест, возвращается `Boolean`. Например `case even()`.
-* Если в результате найдено одно значение типа `T`, то возвращается `Option[T]`.
-* Если вы хотите получить несколько значений `T1,..., Tn`, то ответ необходимо группировать в дополнительный кортеж `Option[(T1,..., Tn)]`.
+- Если это всего лишь тест, возвращается `Boolean`. Например `case even()`.
+- Если в результате найдено одно значение типа `T`, то возвращается `Option[T]`.
+- Если вы хотите получить несколько значений `T1,..., Tn`, то ответ необходимо группировать в дополнительный кортеж `Option[(T1,..., Tn)]`.
-Иногда количество извлекаемых значений не является фиксированным. Если в зависимости от входа мы хотим вернуть произвольное количество значений, то для этого случая мы можем определить экстрактор методом `unapplySeq`, который возвращает `Option[Seq[T]]`. Характерным примером такого подхода является разложение `List` с помощью `case List(x, y, z) =>` и разложение `String` с помощью регулярного выражения `Regex`, такого как `case r(name, remainingFields @ _*) =>`.
+Иногда количество извлекаемых значений не является фиксированным. Если в зависимости от входа мы хотим вернуть произвольное количество значений, то для этого случая мы можем определить экстрактор методом `unapplySeq`, который возвращает `Option[Seq[T]]`. Характерным примером такого подхода является разложение `List` с помощью `case List(x, y, z) =>` и разложение `String` с помощью регулярного выражения `Regex`, такого как `case r(name, remainingFields @ _*) =>`.
diff --git a/_ru/tour/for-comprehensions.md b/_ru/tour/for-comprehensions.md
index cd091ad6a1..8f6ae91bba 100644
--- a/_ru/tour/for-comprehensions.md
+++ b/_ru/tour/for-comprehensions.md
@@ -1,54 +1,97 @@
---
layout: tour
title: Сложные for-выражения
-
-discourse: true
-
partof: scala-tour
-
num: 17
language: ru
next-page: generic-classes
previous-page: extractor-objects
-
---
-Scala предлагает простую запись для выражения *последовательных преобразований*. Эти преобразования можно упростить используя специальный синтаксис `for выражения` (for comprehension), который записывается как `for (enumerators) yield e`, где `enumerators` относятся к списку перечислителей, разделенных точкой с запятой. Где отдельный такой "перечислитель" (*enumerator*) является либо генератором, который вводит новые переменные, либо фильтром. For-выражение вычисляет тело `e` (которое связанно с тем что генерирует *enumerator*) и возвращает последовательность вычислений.
+Scala предлагает простую запись для выражения _последовательных преобразований_. Эти преобразования можно упростить используя специальный синтаксис `for выражения` (for comprehension), который записывается как `for (enumerators) yield e`, где `enumerators` относятся к списку перечислителей, разделенных точкой с запятой. Где отдельный такой "перечислитель" (_enumerator_) является либо генератором, который вводит новые переменные, либо фильтром. For-выражение вычисляет тело `e` (которое связанно с тем что генерирует _enumerator_) и возвращает последовательность вычислений.
Вот пример:
+{% tabs for-comprehensions-01 class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-comprehensions-01 %}
+
```scala mdoc
case class User(name: String, age: Int)
-val userBase = List(User("Travis", 28),
+val userBase = List(
+ User("Travis", 28),
User("Kelly", 33),
User("Jennifer", 44),
User("Dennis", 23))
-val twentySomethings = for (user <- userBase if (user.age >=20 && user.age < 30))
- yield user.name // т. е. добавить результат к списку
+val twentySomethings =
+ for (user <- userBase if user.age >=20 && user.age < 30)
+ yield user.name // т. е. добавить результат к списку
-twentySomethings.foreach(name => println(name)) // выводит "Travis Dennis"
+twentySomethings.foreach(println) // выводит "Travis Dennis"
```
- `for`-выражение, используется с оператором `yield`, на самом деле создает `List`. Потому что мы указали `yield user.name` (то есть вывести имя пользователя), получаем `List[String]`. `user <- userBase` и есть наш генератор, а `if (user.age >=20 && user.age < 30)` - это фильтр который отфильтровывает пользователей, не достигших 20-летнего возраста.
+
+{% endtab %}
+{% tab 'Scala 3' for=for-comprehensions-01 %}
+
+```scala
+case class User(name: String, age: Int)
+
+val userBase = List(
+ User("Travis", 28),
+ User("Kelly", 33),
+ User("Jennifer", 44),
+ User("Dennis", 23))
+
+val twentySomethings =
+ for user <- userBase if user.age >=20 && user.age < 30
+ yield user.name // т. е. добавить результат к списку
+
+twentySomethings.foreach(println) // выводит "Travis Dennis"
+```
+
+{% endtab %}
+{% endtabs %}
+
+`for`-выражение, используется с оператором `yield`, на самом деле создает `List`. Потому что мы указали `yield user.name` (то есть вывести имя пользователя), получаем `List[String]`. `user <- userBase` и есть наш генератор, а `if (user.age >=20 && user.age < 30)` - это фильтр который отфильтровывает пользователей, не достигших 30-летнего возраста.
Ниже приведен более сложный пример использования двух генераторов. Он вычисляет все пары чисел между `0` и `n-1`, сумма которых равна заданному значению `v`:
+{% tabs for-comprehensions-02 class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-comprehensions-02 %}
+
```scala mdoc
def foo(n: Int, v: Int) =
for (i <- 0 until n;
- j <- i until n if i + j == v)
+ j <- 0 until n if i + j == v)
yield (i, j)
-foo(10, 10) foreach {
+foo(10, 10).foreach {
case (i, j) =>
- println(s"($i, $j) ") // выводит (1, 9) (2, 8) (3, 7) (4, 6) (5, 5)
+ println(s"($i, $j) ") // выводит (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1)
}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=for-comprehensions-02 %}
+```scala
+def foo(n: Int, v: Int) =
+ for i <- 0 until n
+ j <- 0 until n if i + j == v
+ yield (i, j)
+
+foo(10, 10).foreach {
+ (i, j) => println(s"($i, $j) ") // выводит (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1)
+}
```
+
+{% endtab %}
+{% endtabs %}
+
Здесь `n == 10` и `v == 10`. На первой итерации `i == 0` и `j == 0` так `i + j != v` и поэтому ничего не выдается. `j` увеличивается еще в 9 раз, прежде чем `i` увеличивается до `1`. Без фильтра `if` будет просто напечатано следующее:
-```scala
+```scala
(0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ...
```
@@ -56,11 +99,34 @@ foo(10, 10) foreach {
Вы можете обойтись без `yield` в for-выражении. В таком случае, результатом будет `Unit`. Это может быть полезным для выполнения кода основанного на побочных эффектах. Вот программа, эквивалентная предыдущей, но без использования `yield`:
+{% tabs for-comprehensions-03 class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-comprehensions-03 %}
+
```scala mdoc:nest
def foo(n: Int, v: Int) =
for (i <- 0 until n;
- j <- i until n if i + j == v)
+ j <- 0 until n if i + j == v)
println(s"($i, $j)")
foo(10, 10)
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-comprehensions-03 %}
+
+```scala
+def foo(n: Int, v: Int) =
+ for i <- 0 until n
+ j <- 0 until n if i + j == v
+ do println(s"($i, $j)")
+
+foo(10, 10)
+```
+
+{% endtab %}
+{% endtabs %}
+
+## Дополнительные ресурсы
+
+- Другие примеры "For comprehension" доступны [в книге Scala](/ru/scala3/book/control-structures.html#выражение-for)
diff --git a/_ru/tour/generic-classes.md b/_ru/tour/generic-classes.md
index fafc2fd13e..591f810cfd 100644
--- a/_ru/tour/generic-classes.md
+++ b/_ru/tour/generic-classes.md
@@ -1,22 +1,23 @@
---
layout: tour
title: Обобщенные Классы
-
-discourse: true
-
partof: scala-tour
-
num: 18
language: ru
next-page: variances
previous-page: for-comprehensions
assumed-knowledge: classes unified-types
-
---
+
Обобщенные классы (Generic classes) - это классы, обладающие параметрическим полиморфизмом (т. е. классы, которые изменяют свое поведение в зависимости от приписываемого им типа. Этот тип указывается в квадратных скобках `[]` сразу после имени класса). Они особенно полезны для создания коллекций.
## Объявление обобщенного класса
+
Для объявления обобщенного класса необходимо после имени добавить тип в квадратных скобках `[]` как еще один параметр класса. По соглашению обычно используют заглавные буквы `A`, хотя можно использовать любые имена.
+
+{% tabs generic-classes-1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=generic-classes-1 %}
+
```scala mdoc
class Stack[A] {
private var elements: List[A] = Nil
@@ -30,20 +31,64 @@ class Stack[A] {
}
}
```
-Данная реализация класса `Stack` принимает в качестве параметра любой тип `A`. Это означает что список, `var elements: List[A] = Nil`, может хранить только элементы типа `A`. Процедура `def push` принимает только объекты типа `A` (примечание: `elements = x :: elements` переназначает `elements` в новый список, созданный путем добавления `x`а к текущим `elements`).
+
+{% endtab %}
+{% tab 'Scala 3' for=generic-classes-1 %}
+
+```scala
+class Stack[A]:
+ private var elements: List[A] = Nil
+ def push(x: A): Unit =
+ elements = x :: elements
+ def peek: A = elements.head
+ def pop(): A =
+ val currentTop = peek
+ elements = elements.tail
+ currentTop
+```
+
+{% endtab %}
+{% endtabs %}
+
+Данная реализация класса `Stack` принимает в качестве параметра любой тип `A`. Это означает что список, `var elements: List[A] = Nil`, может хранить только элементы типа `A`. Процедура `def push` принимает только объекты типа `A` (примечание: `elements = x :: elements` переназначает `elements` в новый список, созданный путем добавления `x` к текущим `elements`).
+
+Здесь `Nil` — это пустой `List`, и его не следует путать с `null`.
## Использование
Чтобы использовать обобщенный класс, поместите конкретный тип в квадратные скобки вместо `A`.
-```
+
+{% tabs generic-classes-2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=generic-classes-2 %}
+
+```scala mdoc
val stack = new Stack[Int]
stack.push(1)
stack.push(2)
-println(stack.pop) // выведет 2
-println(stack.pop) // выведет 1
+println(stack.pop()) // выведет 2
+println(stack.pop()) // выведет 1
```
-Экземпляр `stack` может принимать только Intы. Однако, если тип имеет подтипы, то они также могут быть приняты:
+
+{% endtab %}
+{% tab 'Scala 3' for=generic-classes-2 %}
+
+```scala
+val stack = Stack[Int]
+stack.push(1)
+stack.push(2)
+println(stack.pop()) // выведет 2
+println(stack.pop()) // выведет 1
```
+
+{% endtab %}
+{% endtabs %}
+
+Экземпляр `stack` может принимать элементы типа `Int`. Однако, если тип имеет подтипы, то они также могут быть приняты:
+
+{% tabs generic-classes-3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=generic-classes-3 %}
+
+```scala mdoc:nest
class Fruit
class Apple extends Fruit
class Banana extends Fruit
@@ -55,6 +100,25 @@ val banana = new Banana
stack.push(apple)
stack.push(banana)
```
+
+{% endtab %}
+{% tab 'Scala 3' for=generic-classes-3 %}
+
+```scala
+class Fruit
+class Apple extends Fruit
+class Banana extends Fruit
+
+val stack = Stack[Fruit]
+val apple = Apple()
+val banana = Banana()
+
+stack.push(apple)
+stack.push(banana)
+```
+
+{% endtab %}
+{% endtabs %}
Классы `Apple` и `Banana` наследуются от `Fruit` так, что мы можем засунуть экземпляры `Apple` и `Banana` в пачку `Fruit`.
_Примечание: подтипы обобщенных типов - *инвариантны*. Это означает, что если у нас есть стэк символов типа `Stack[Char]`, то он не может быть использован как стек интов типа `Stack[Int]`. Это нежелательное поведение, потому как позволило бы нам добавлять в стек символов целые числа. В заключение, `Stack[A]` является подтипом `Stack[B]` тогда и только тогда, когда `B = A`. Поскольку это может быть довольно строгим ограничением, Scala предлагает [механизм вариативного описания параметров типа](variances.html) для контроля за поведением подтипов._
diff --git a/_ru/tour/higher-order-functions.md b/_ru/tour/higher-order-functions.md
index 0b4416ed4b..b55b4d9b24 100644
--- a/_ru/tour/higher-order-functions.md
+++ b/_ru/tour/higher-order-functions.md
@@ -1,46 +1,80 @@
---
layout: tour
title: Функции Высшего Порядка
-
-discourse: true
-
partof: scala-tour
-
num: 8
language: ru
next-page: nested-functions
previous-page: mixin-class-composition
-
---
-Функции высшего порядка могут принимать другие функции в качестве параметров или возвращать функцию в качестве результата
-Такое возможно поскольку функции являются объектами первого класса в Scala.
-На текущем этапе терминология может казаться немного запутанной, мы используем следующую фразу "функция высшего порядка" как для методов, так и для функций, которые могут принимать другие функции в качестве параметров, или возвращать функции в качестве результата.
+Функции высшего порядка могут принимать другие функции в качестве параметров или возвращать функцию в качестве результата.
+Такое возможно поскольку функции являются объектами первого класса в Scala.
+На текущем этапе терминология может казаться немного запутанной, мы используем следующую фразу "функция высшего порядка" как для методов, так и для функций, которые могут принимать другие функции в качестве параметров, или возвращать функции в качестве результата.
+
+В чисто объектно-ориентированном мире рекомендуется избегать раскрытия методов,
+параметризованных функциями, которые могут привести к утечке внутреннего состояния объекта.
+Утечка внутреннего состояния может нарушить инварианты самого объекта, тем самым нарушив инкапсуляцию.
-Одним из наиболее распространенных примеров функции высшего порядка
+Одним из наиболее распространенных примеров функции высшего порядка
является функция `map`, которая доступна в коллекциях Scala.
-```scala mdoc
-val salaries = Seq(20000, 70000, 40000)
+
+{% tabs map_example_1 %}
+
+{% tab 'Scala 2 и 3' for=map_example_1 %}
+
+```scala mdoc:nest
+val salaries = Seq(20_000, 70_000, 40_000)
val doubleSalary = (x: Int) => x * 2
val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000)
```
+
+{% endtab %}
+
+{% endtabs %}
+
`doubleSalary` - это функция, которая принимает один Int `x` и возвращает `x * 2`. В общем случае, кортеж (список имен в скобках) слева от стрелки `=>` - это список параметров, а значение выражения следует справа. Это же значение возвращается в качестве результата. В строке 3 к каждому элементу списка зарплат (salaries) применяется функция `doubleSalary`.
Чтобы сократить код, мы можем сделать функцию анонимной и передать ее напрямую в качестве аргумента в map:
+
+{% tabs map_example_2 %}
+
+{% tab 'Scala 2 и 3' for=map_example_2 %}
+
```scala mdoc:nest
-val salaries = Seq(20000, 70000, 40000)
+val salaries = Seq(20_000, 70_000, 40_000)
val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000)
```
+
+{% endtab %}
+
+{% endtabs %}
+
Обратите внимание, что в приведенном выше примере `x`не объявлен как `Int`. Это потому, что компилятор может вывести тип, основываясь на типе который ожидает функция map. Еще более элегантным способом написания этого же кода было бы таким:
+{% tabs map_example_3 %}
+
+{% tab 'Scala 2 и 3' for=map_example_3 %}
+
```scala mdoc:nest
-val salaries = Seq(20000, 70000, 40000)
+val salaries = Seq(20_000, 70_000, 40_000)
val newSalaries = salaries.map(_ * 2)
```
+
+{% endtab %}
+
+{% endtabs %}
+
Поскольку компилятор Scala уже знает тип параметров (Int), вам нужно только указать правую часть функции. Единственное условие заключается в том, что вместо имени параметра необходимо использовать `_` (в предыдущем примере это было `x`).
## Преобразование методов в функции
+
Также возможно передавать методы в качестве аргументов функциям более высокого порядка, поскольку компилятор Scala может преобразовать метод в функцию.
+
+{% tabs Coercing_methods_into_functions class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=Coercing_methods_into_functions %}
+
```scala mdoc
case class WeeklyWeatherForecast(temperatures: Seq[Double]) {
@@ -49,11 +83,33 @@ case class WeeklyWeatherForecast(temperatures: Seq[Double]) {
def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- передается метод convertCtoF
}
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=Coercing_methods_into_functions %}
+
+```scala
+case class WeeklyWeatherForecast(temperatures: Seq[Double]):
+
+ private def convertCtoF(temp: Double) = temp * 1.8 + 32
+
+ def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- передается метод convertCtoF
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Здесь метод `convertCtoF` передается в `forecastInFahrenheit`. Это возможно, потому что компилятор преобразовывает `convertCtoF` в функцию `x => ConvertCtoF(x)` (примечание: `x` будет сгенерированным именем, которое гарантированно будет уникальным в рамках своей области видимости).
## Функции, которые принимают функции
+
Одной из причин использования функций высшего порядка является сокращение избыточного кода. Допустим, вам нужны какие-то методы, которые могли бы повышать чью-то зарплату по разным условиям. Без создания функции высшего порядка это могло бы выглядеть примерно так:
+{% tabs Functions_that_accept_functions_1 class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=Functions_that_accept_functions_1 %}
+
```scala mdoc
object SalaryRaiser {
@@ -68,8 +124,33 @@ object SalaryRaiser {
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=Functions_that_accept_functions_1 %}
+
+```scala
+object SalaryRaiser:
+
+ def smallPromotion(salaries: List[Double]): List[Double] =
+ salaries.map(salary => salary * 1.1)
+
+ def greatPromotion(salaries: List[Double]): List[Double] =
+ salaries.map(salary => salary * math.log(salary))
+
+ def hugePromotion(salaries: List[Double]): List[Double] =
+ salaries.map(salary => salary * salary)
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Обратите внимание, что каждый из этих трех методов отличается только коэффициентом умножения. Для упрощения можно перенести повторяющийся код в функцию высшего порядка:
+{% tabs Functions_that_accept_functions_2 class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=Functions_that_accept_functions_2 %}
+
```scala mdoc:nest
object SalaryRaiser {
@@ -79,7 +160,7 @@ object SalaryRaiser {
def smallPromotion(salaries: List[Double]): List[Double] =
promotion(salaries, salary => salary * 1.1)
- def bigPromotion(salaries: List[Double]): List[Double] =
+ def greatPromotion(salaries: List[Double]): List[Double] =
promotion(salaries, salary => salary * math.log(salary))
def hugePromotion(salaries: List[Double]): List[Double] =
@@ -87,12 +168,44 @@ object SalaryRaiser {
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=Functions_that_accept_functions_2 %}
+
+```scala
+object SalaryRaiser:
+
+ private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] =
+ salaries.map(promotionFunction)
+
+ def smallPromotion(salaries: List[Double]): List[Double] =
+ promotion(salaries, salary => salary * 1.1)
+
+ def greatPromotion(salaries: List[Double]): List[Double] =
+ promotion(salaries, salary => salary * math.log(salary))
+
+ def hugePromotion(salaries: List[Double]): List[Double] =
+ promotion(salaries, salary => salary * salary)
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Новый метод, `promotion`, берет зарплату и функцию типа `Double => Double` (т.е. функция, которая берет Double и возвращает Double) и возвращает их произведение.
+Методы и функции обычно выражают поведение или преобразование данных, поэтому наличие функций,
+которые компонуются на основе других функций, может помочь в создании общих механизмов.
+Эти типовые функции откладывают блокировку всего поведения операции,
+предоставляя клиентам возможность контролировать или дополнительно настраивать части самой операции.
## Функции, возвращающие функции
Есть определенные случаи, когда вы хотите сгенерировать функцию. Вот пример метода, который возвращает функцию.
+{% tabs Functions_that_return_functions class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=Functions_that_return_functions %}
+
```scala mdoc
def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = {
val schema = if (ssl) "https://" else "http://"
@@ -106,4 +219,24 @@ val query = "id=1"
val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String
```
+{% endtab %}
+
+{% tab 'Scala 3' for=Functions_that_return_functions %}
+
+```scala
+def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String =
+ val schema = if ssl then "https://" else "http://"
+ (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query"
+
+val domainName = "www.example.com"
+def getURL = urlBuilder(ssl=true, domainName)
+val endpoint = "users"
+val query = "id=1"
+val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Обратите внимание, что возвращаемый тип urlBuilder`(String, String) => String`. Это означает, что возвращаемая анонимная функция принимает две строки и возвращает строку. В нашем случае возвращаемая анонимная функция `(endpoint: String, query: String) => s"https://www.example.com/$endpoint?$query"`.
diff --git a/_ru/tour/implicit-conversions.md b/_ru/tour/implicit-conversions.md
index bd36a9e749..5e3001862d 100644
--- a/_ru/tour/implicit-conversions.md
+++ b/_ru/tour/implicit-conversions.md
@@ -1,63 +1,52 @@
---
layout: tour
title: Неявные Преобразования
-
-discourse: true
-
partof: scala-tour
-
num: 27
language: ru
next-page: polymorphic-methods
previous-page: implicit-parameters
-
---
-Неявные преобразование типа `S` к типу `T` задается неявным значением функционального типа `S =>T`, или неявным методом, который способен преобразовывать к значению требуемого типа.
+Неявные преобразования — это мощная функция Scala, применяемая в двух распространенных вариантах:
-Неявное преобразование применяются в двух случаях:
+- разрешить пользователям предоставлять аргумент одного типа так, как если бы это был другой тип, чтобы избежать шаблонного.
+- в Scala 2 для предоставления дополнительных членов запечатанным классам (заменены [методами расширения][exts] в Scala 3).
-* Если выражение `e` типа `S` не подходит под ожидаемый тип выражения `T`.
-* Если мы выбирая член `e.m`, где `e` является представителем типа `S`, при этом выбранное имя `m` не найдено среди доступных селекторов принадлежащих типу `S`.
-
-В первом случае выполняется поиск приведения `c`, которое можно применить к `e` чтоб тип результата стал соответствовать ожидаемому `T`.
-Во втором случае выполняется поиск преобразования `c`, которое применимо к `e` и результат которого бы содержал член с именем `m`.
+### Детальный разбор
-Если неявный метод `List[A] => Ordered[List[A]]` находится в области видимости, также как и неявный метод `Int => Ordered[Int]`, то следующая операция с двумя списками типа `List[Int]` является допустимой:
+{% tabs implicit-conversion-defn class=tabs-scala-version %}
+{% tab 'Scala 2' %}
-```
-List(1, 2, 3) <= List(4, 5)
-```
+В Scala 2 неявное преобразование из типа `S` в тип `T` определяется либо [неявным классом]({% link _overviews/core/implicit-classes.md %}) `T`
+с одним параметром типа `S`, [неявным значением](implicit-parameters.html), которое имеет тип функции `S => T`,
+либо неявным методом, преобразуемым в значение этого типа.
-Неявный метод `Int => Ordered[Int]` предоставляется автоматически через `scala.Predef.intWrapper`. Ниже приведен пример объявления неявного метода `List[A] => Ordered[List[A]]`.
+{% endtab %}
+{% tab 'Scala 3' %}
-```scala mdoc
-import scala.language.implicitConversions
+В Scala 3 неявное преобразование из типа `S` в тип `T` определяется [экземпляром `given`](implicit-parameters.html), который имеет тип `scala.Conversion[S, T]`.
+Для совместимости со Scala 2 их также можно определить неявным методом (подробнее читайте во вкладке Scala 2).
-implicit def list2ordered[A](x: List[A])
- (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] =
- new Ordered[List[A]] {
- //заменить на более полезную реализацию
- def compare(that: List[A]): Int = 1
- }
-```
+{% endtab %}
+{% endtabs %}
-Неявно импортируемый объект `scala.Predef` объявляет ряд псевдонимов для часто используемым типов (например, `scala.collection.immutable.Map` использует псевдоним `Map`) и методов (например, `assert`), а также делает доступным целую серию неявных преобразований.
+Неявные преобразования применяются в двух случаях:
-Например, при вызове Java метода, который ожидает `java.lang.Integer`, вместо него вы можете свободно использовать `scala.Int`. Потому что Predef включает в себя следующие неявные преобразования:
+1. Если выражение `e` имеет тип `S` и `S` не соответствует ожидаемому типу выражения `T`.
+2. При выборе `e.m`, где `e` типа `S`, если селектор `m` не указывает на элемент `S`.
-```scala mdoc
-import scala.language.implicitConversions
+В первом случае ищется конверсия `c`, применимая к `e` и тип результата которой соответствует `T`.
-implicit def int2Integer(x: Int) =
- java.lang.Integer.valueOf(x)
-```
+Примером является передача `scala.Int`, например `x`, методу, который ожидает `scala.Long`.
+В этом случае вставляется неявное преобразование `Int.int2long(x)`.
-Компилятор предупреждает при компиляции об обнаружении неявных преобразований, тк неявные преобразования могут иметь разные подводные камни (особенно если использовать их без разбора).
+Во втором случае ищется преобразование `c`, применимое к `e` и результат которого содержит элемент с именем `m`.
-Чтоб отключить предупреждения выполните одно из следующих действий:
+Примером является сравнение двух строк `"foo" < "bar"`.
+В этом случае `String` не имеет члена `<`, поэтому вставляется неявное преобразование `Predef.augmentString("foo") < "bar"`
+(`scala.Predef` автоматически импортируется во все программы Scala).
-* Импортируйте `scala.language.implicitConversions` в области видимости, где объявлены неявные преобразования.
-* Вызывайте компилятор с ключом `-language:implicitConversions`.
+Дополнительная литература: [Неявные преобразования (в книге Scala)](/ru/scala3/book/ca-implicit-conversions.html).
-В таком случае при преобразовании компилятором не будет выдаваться никаких предупреждений.
+[exts]: /ru/scala3/book/ca-extension-methods.html
diff --git a/_ru/tour/implicit-parameters.md b/_ru/tour/implicit-parameters.md
index cf58ded10e..14f11c299c 100644
--- a/_ru/tour/implicit-parameters.md
+++ b/_ru/tour/implicit-parameters.md
@@ -1,73 +1,111 @@
---
layout: tour
-title: Неявные Параметры
-
-discourse: true
-
+title: Контекстные параметры, также известные, как неявные параметры
partof: scala-tour
-
num: 26
language: ru
next-page: implicit-conversions
previous-page: self-types
-
---
-Метод может иметь список _неявных_ параметров, помеченный ключевым словом _implicit_ в начале списка параметров. Если параметры в этом списке не передаются как обычно, то Scala будет искать, где можно получить неявное значение требуемого типа, и если найдет, то передаст его автоматически.
-
-Места, где Scala будет искать эти параметры, делятся на две категории:
+Метод может иметь список _контекстных параметров_ (_contextual parameters_),
+также называемых _неявными параметрами_ (_implicit parameters_) или, точнее, _имплицитами_ (_implicits_).
+Списки параметров, начинающиеся с ключевого слова `using` (или `implicit` в Scala 2), задают контекстные параметры.
+Если сторона вызова явно не предоставляет аргументы для таких параметров,
+Scala будет искать неявно доступные `given` (или `implicit` в Scala 2) значения правильного типа.
+Если можно найти подходящие значения, то они автоматически передаются.
-* Скала сначала будет искать неявные параметры, доступ к которым можно получить напрямую (без префикса) в месте вызова метода в котором запрошены неявные параметры.
-* Затем он ищет членов, помеченных как implicit во всех объектах компаньонах, связанных с типом неявного параметра.
+Лучше всего вначале показать это на небольшом примере.
+Мы определяем интерфейс `Comparator[A]`, который может сравнивать элементы типа `A`,
+и предоставляем две реализации для `Int`-ов и `String`-ов.
+Затем мы определяем метод `max[A](x: A, y: A)`, который возвращает больший из двух аргументов.
+Так как `x` и `y` имеют абстрактный тип, в общем случае мы не знаем, как их сравнивать, но можем запросить соответствующий компаратор.
+Поскольку обычно для любого заданного типа существует канонический компаратор `A`,
+то мы можем объявить их как _заданные_ (_given_) или _неявно_ (_implicitly_) доступные.
-Более подробное руководство, о том где scala ищет неявные значения можно найти в [FAQ](//docs.scala-lang.org/tutorials/FAQ/finding-implicits.html)
+{% tabs implicits-comparator class=tabs-scala-version %}
-В следующем примере мы определяем метод `sum`, который вычисляет сумму элементов списка, используя операции `add` и `unit` моноида. Обратите внимание, что неявные значения не могут находится выше уровнем.
+{% tab 'Scala 2' for=implicits-comparator %}
```scala mdoc
-abstract class Monoid[A] {
- def add(x: A, y: A): A
- def unit: A
+trait Comparator[A] {
+ def compare(x: A, y: A): Int
}
-object ImplicitTest {
- implicit val stringMonoid: Monoid[String] = new Monoid[String] {
- def add(x: String, y: String): String = x concat y
- def unit: String = ""
- }
-
- implicit val intMonoid: Monoid[Int] = new Monoid[Int] {
- def add(x: Int, y: Int): Int = x + y
- def unit: Int = 0
+object Comparator {
+ implicit object IntComparator extends Comparator[Int] {
+ def compare(x: Int, y: Int): Int = Integer.compare(x, y)
}
-
- def sum[A](xs: List[A])(implicit m: Monoid[A]): A =
- if (xs.isEmpty) m.unit
- else m.add(xs.head, sum(xs.tail))
-
- def main(args: Array[String]): Unit = {
- println(sum(List(1, 2, 3))) // использует intMonoid неявно
- println(sum(List("a", "b", "c"))) // использует stringMonoid неявно
+
+ implicit object StringComparator extends Comparator[String] {
+ def compare(x: String, y: String): Int = x.compareTo(y)
}
}
+
+def max[A](x: A, y: A)(implicit comparator: Comparator[A]): A =
+ if (comparator.compare(x, y) >= 0) x
+ else y
+
+println(max(10, 6)) // 10
+println(max("hello", "world")) // world
```
-`Monoid` определяет здесь операцию под названием `add`, которая сочетает два элемента типа `A` и возвращает сумму типа `A`, операция `unit` позволяет вернуть отдельный (специфичный) элемент типа `A`.
+```scala mdoc:fail
+// не компилируется:
+println(max(false, true))
+// ^
+// error: could not find implicit value for parameter comparator: Comparator[Boolean]
+```
+
+Параметр `comparator` автоматически заполняется значением `Comparator.IntComparator` для `max(10, 6)`
+и `Comparator.StringComparator` для `max("hello", "world")`.
+Поскольку нельзя найти неявный `Comparator[Boolean]`, вызов `max(false, true)` не компилируется.
-Чтобы показать, как работают неявные параметры, сначала определим моноиды `stringMonoid` и `intMonoid` для строк и целых чисел, соответственно. Ключевое слово `implicit` указывает на то, что этот объект может быть использован неявно.
+{% endtab %}
-Метод `sum` принимает `List[A]` и возвращает `A`, который берет начальное `A` из `unit` и объединяет каждое следующее `A` в списке используя `add` метод. Указание параметра `m` в качестве неявного параметра подразумевает, что `xs` параметр будет обеспечен тогда, когда при вызове параметра метода Scala сможет найти неявный `Monoid[A]` чтоб его передать в качестве параметра `m`.
+{% tab 'Scala 3' for=implicits-comparator %}
-В нашем `main` методе мы вызываем `sum` дважды и предоставляем только `xs` параметр. Теперь Scala будет искать неявное значение в указанных ранее областях видимости. Первый вызов `sum` проходит с использованием `List[Int]` в качестве `xs`, это означает, что элемент `A` имеет тип `Int`. Неявный список параметров с `m` опущен, поэтому Scala будет искать неявное значение типа `Monoid[Int]`. Первое правило поиска гласит
+```scala
+trait Comparator[A]:
+def compare(x: A, y: A): Int
-> Скала сначала будет искать неявные параметры, доступ к которым можно получить напрямую (без префикса) в месте вызова метода в котором запрошены неявные параметры.
+object Comparator:
+given Comparator[Int] with
+def compare(x: Int, y: Int): Int = Integer.compare(x, y)
-`intMonoid` - это задание неявного значения, доступ к которому можно получить непосредственно в `main`. Оно имеет подходящий тип, поэтому передается методу `sum` автоматически.
+given Comparator[String] with
+def compare(x: String, y: String): Int = x.compareTo(y)
+end Comparator
-Второй вызов `sum` проходит используя `List[String]`, что означает, что `A` - это `String`. Неявный поиск будет идти так же, как и в случае с `Int`, но на этот раз будет найден `stringMonoid`, и передан автоматически в качестве `m`.
+def max[A](x: A, y: A)(using comparator: Comparator[A]): A =
+ if comparator.compare(x, y) >= 0 then x
+ else y
-Программа выведет на экран
+println(max(10, 6)) // 10
+println(max("hello", "world")) // world
```
-6
-abc
+
+```scala
+// не компилируется:
+println(max(false, true))
+-- Error: ----------------------------------------------------------------------
+1 |println(max(false, true))
+ | ^
+ |no given instance of type Comparator[Boolean] was found for parameter comparator of method max
```
+
+Параметр `comparator` автоматически заполняется значением `given Comparator[Int]` для `max(10, 6)`
+и `given Comparator[String]` для `max("hello", "world")`.
+Поскольку нельзя найти `given Comparator[Boolean]`, вызов `max(false, true)` не компилируется.
+
+{% endtab %}
+
+{% endtabs %}
+
+Места, где Scala будет искать эти параметры, делятся на две категории:
+
+- Вначале Scala будет искать `given` параметры, доступ к которым можно получить напрямую (без префикса) в месте вызова `max`.
+- Затем он ищет членов, помеченных как given/implicit во всех объектах компаньонах,
+ связанных с типом неявного параметра (например: `object Comparator` для типа-кандидата `Comparator[Int]`).
+
+Более подробное руководство, о том где scala ищет неявные значения можно найти в [FAQ](/tutorials/FAQ/finding-implicits.html)
diff --git a/_ru/tour/inner-classes.md b/_ru/tour/inner-classes.md
index 736677ceff..15a1a2882d 100644
--- a/_ru/tour/inner-classes.md
+++ b/_ru/tour/inner-classes.md
@@ -1,27 +1,25 @@
---
layout: tour
title: Внутренние классы
-
-discourse: true
-
partof: scala-tour
-
num: 22
language: ru
next-page: abstract-type-members
previous-page: lower-type-bounds
-
---
-В Scala классам можно иметь в качестве членов другие классы. В отличие от Java-подобных языков, где такие внутренние классы являются членами окружающего класса, в Scala такие внутренние классы привязаны к содержащему его объекту. Предположим, мы хотим, чтобы компилятор не позволял нам на этапе компиляции смешивать узлы этого графа. Для решения этой задачи нам подойдут типы, зависящие от своего расположения.
+В Scala классам можно иметь в качестве членов другие классы. В отличие от Java-подобных языков, где такие внутренние классы являются членами окружающего класса, в Scala такие внутренние классы привязаны к содержащему его объекту. Предположим, мы хотим, чтобы компилятор не позволял нам на этапе компиляции смешивать узлы этого графа. Для решения этой задачи нам подойдут типы, зависящие от своего расположения.
Чтобы проиллюстрировать суть подхода, мы быстро набросаем реализацию такого графа:
+{% tabs inner-classes_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=inner-classes_1 %}
+
```scala mdoc
class Graph {
class Node {
var connectedNodes: List[Node] = Nil
- def connectTo(node: Node) {
+ def connectTo(node: Node): Unit = {
if (!connectedNodes.exists(node.equals)) {
connectedNodes = node :: connectedNodes
}
@@ -35,8 +33,33 @@ class Graph {
}
}
```
+
+{% endtab %}
+{% tab 'Scala 3' for=inner-classes_1 %}
+
+```scala
+class Graph:
+ class Node:
+ var connectedNodes: List[Node] = Nil
+ def connectTo(node: Node): Unit =
+ if !connectedNodes.exists(node.equals) then
+ connectedNodes = node :: connectedNodes
+
+ var nodes: List[Node] = Nil
+ def newNode: Node =
+ val res = Node()
+ nodes = res :: nodes
+ res
+```
+
+{% endtab %}
+{% endtabs %}
+
Данная программа представляет собой граф в составленного из списка узлов (`List[Node]`). Каждый узел имеет список других узлов, с которым он связан (`connectedNodes`). Класс `Node` является _зависимым от месторасположения типом_, поскольку он вложен в `Class Graph`. Поэтому все узлы в `connectedNodes` должны быть созданы с использованием `newNode` из одного и того же экземпляра `Graph`.
+{% tabs inner-classes_2 %}
+{% tab 'Scala 2 и 3' for=inner-classes_2 %}
+
```scala mdoc
val graph1: Graph = new Graph
val node1: graph1.Node = graph1.newNode
@@ -45,12 +68,19 @@ val node3: graph1.Node = graph1.newNode
node1.connectTo(node2)
node3.connectTo(node1)
```
+
+{% endtab %}
+{% endtabs %}
+
Мы явно объявили тип `node1`, `node2` и `node3` как `graph1.Node` для ясности, хотя компилятор мог определить это самостоятельно. Это потому, что когда мы вызываем `graph1.newNode`, вызывающий `new Node`, метод использует экземпляр `Node`, специфичный экземпляру `graph1`.
Если у нас есть два графа, то система типов Scala не позволит смешивать узлы, определенные в рамках одного графа, с узлами другого, так как узлы другого графа имеют другой тип.
Вот некорректная программа:
-```scala:nest
+{% tabs inner-classes_3 %}
+{% tab 'Scala 2 и 3' for=inner-classes_3 %}
+
+```scala mdoc:fail
val graph1: Graph = new Graph
val node1: graph1.Node = graph1.newNode
val node2: graph1.Node = graph1.newNode
@@ -59,13 +89,20 @@ val graph2: Graph = new Graph
val node3: graph2.Node = graph2.newNode
node1.connectTo(node3) // не работает!
```
+
+{% endtab %}
+{% endtabs %}
+
Тип `graph1.Node` отличается от типа `graph2.Node`. В Java последняя строка в предыдущем примере программы была бы правильной. Для узлов обоих графов Java будет присваивать один и тот же тип `Graph.Node`, т.е. `Node` имеет префикс класса `Graph`. В Скале такой тип также может быть выражен, он записывается `Graph#Node`. Если мы хотим иметь возможность соединять узлы разных графов, то вам нужно изменить описание первоначальной реализации графов следующим образом:
+{% tabs inner-classes_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=inner-classes_4 %}
+
```scala mdoc:nest
class Graph {
class Node {
var connectedNodes: List[Graph#Node] = Nil
- def connectTo(node: Graph#Node) {
+ def connectTo(node: Graph#Node): Unit = {
if (!connectedNodes.exists(node.equals)) {
connectedNodes = node :: connectedNodes
}
@@ -79,3 +116,24 @@ class Graph {
}
}
```
+
+{% endtab %}
+{% tab 'Scala 3' for=inner-classes_4 %}
+
+```scala
+class Graph:
+ class Node:
+ var connectedNodes: List[Graph#Node] = Nil
+ def connectTo(node: Graph#Node): Unit =
+ if !connectedNodes.exists(node.equals) then
+ connectedNodes = node :: connectedNodes
+
+ var nodes: List[Node] = Nil
+ def newNode: Node =
+ val res = Node()
+ nodes = res :: nodes
+ res
+```
+
+{% endtab %}
+{% endtabs %}
diff --git a/_ru/tour/lower-type-bounds.md b/_ru/tour/lower-type-bounds.md
index 8351695a72..3d3b22edb9 100644
--- a/_ru/tour/lower-type-bounds.md
+++ b/_ru/tour/lower-type-bounds.md
@@ -1,70 +1,115 @@
---
layout: tour
title: Нижнее Ограничение Типа
-
-discourse: true
-
partof: scala-tour
-
num: 21
language: ru
next-page: inner-classes
previous-page: upper-type-bounds
prerequisite-knowledge: upper-type-bounds, generics, variance
-
---
-В то время как [верхнее ограничение типа](upper-type-bounds.html) ограничивает тип до подтипа стороннего типа, *нижнее ограничение типа* объявляют тип супертипом стороннего типа. Термин `B >: A` выражает, то что параметр типа `B` или абстрактный тип `B` относится к супертипу типа `A`. В большинстве случаев `A` будет задавать тип класса, а `B` задавать тип метода.
+В то время как [верхнее ограничение типа](upper-type-bounds.html) ограничивает тип до подтипа стороннего типа, _нижнее ограничение типа_ объявляют тип супертипом стороннего типа. Термин `B >: A` выражает, то что параметр типа `B` или абстрактный тип `B` относится к супертипу типа `A`. В большинстве случаев `A` будет задавать тип класса, а `B` задавать тип метода.
Вот пример, где это полезно:
+{% tabs upper-type-bounds_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds_1 %}
+
```scala mdoc:fail
-trait Node[+B] {
- def prepend(elem: B): Node[B]
+trait List[+A] {
+ def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this)
}
-case class ListNode[+B](h: B, t: Node[B]) extends Node[B] {
- def prepend(elem: B): ListNode[B] = ListNode(elem, this)
- def head: B = h
- def tail: Node[B] = t
-}
+case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A]
-case class Nil[+B]() extends Node[B] {
- def prepend(elem: B): ListNode[B] = ListNode(elem, this)
-}
+object Nil extends List[Nothing]
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds_1 %}
+
+```scala
+trait List[+A]:
+ def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this)
+
+case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A]
+
+object Nil extends List[Nothing]
```
-В данной программе реализован связанный список. `Nil` представляет пустой список. Класс `ListNode` - это узел, который содержит элемент типа `B` (`head`) и ссылку на остальную часть списка (`tail`). Класс `Node` и его подтипы ковариантны, потому что у нас указанно `+B`.
+{% endtab %}
+{% endtabs %}
-Однако эта программа _не компилируется_, потому что параметр `elem` в `prepend` имеет тип `B`, который мы объявили *ко*вариантным. Так это не работает, потому что функции *контр*вариантны в типах своих параметров и *ко*вариантны в типах своих результатов.
+В данной программе реализован связанный список. `Nil` представляет пустой список. Класс `NonEmptyList` - это узел, который содержит элемент типа `A` (`head`) и ссылку на остальную часть списка (`tail`). `trait List` и его подтипы ковариантны, потому что у нас указанно `+A`.
-Чтобы исправить это, необходимо перевернуть вариантность типа параметра `elem` в `prepend`. Для этого мы вводим новый тип для параметра `U`, у которого тип `B` указан в качестве нижней границы типа.
+Однако эта программа _не компилируется_, потому что параметр `elem` в `prepend` имеет тип `A`, который мы объявили *ко*вариантным. Так это не работает, потому что функции *контр*вариантны в типах своих параметров и *ко*вариантны в типах своих результатов.
+
+Чтобы исправить это, необходимо перевернуть вариантность типа параметра `elem` в `prepend`. Для этого мы вводим новый тип для параметра `B`, у которого тип `A` указан в качестве нижней границы типа.
+
+{% tabs upper-type-bounds_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds_2 %}
```scala mdoc
-trait Node[+B] {
- def prepend[U >: B](elem: U): Node[U]
+trait List[+A] {
+ def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this)
}
-case class ListNode[+B](h: B, t: Node[B]) extends Node[B] {
- def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this)
- def head: B = h
- def tail: Node[B] = t
-}
+case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A]
-case class Nil[+B]() extends Node[B] {
- def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this)
-}
+object Nil extends List[Nothing]
```
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds_2 %}
+
+```scala
+trait List[+A]:
+ def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this)
+
+case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A]
+
+object Nil extends List[Nothing]
+```
+
+{% endtab %}
+{% endtabs %}
+
Теперь мы можем сделать следующее:
+
+{% tabs upper-type-bounds_3 %}
+{% tab 'Scala 2 и 3' for=upper-type-bounds_3 %}
+
```scala mdoc
trait Bird
case class AfricanSwallow() extends Bird
case class EuropeanSwallow() extends Bird
+val africanSwallows: List[AfricanSwallow] = Nil.prepend(AfricanSwallow())
+val swallowsFromAntarctica: List[Bird] = Nil
+val someBird: Bird = EuropeanSwallow()
-val africanSwallowList= ListNode[AfricanSwallow](AfricanSwallow(), Nil())
-val birdList: Node[Bird] = africanSwallowList
-birdList.prepend(EuropeanSwallow())
+// присвоить птицам (birds) африканских ласточек (swallows)
+val birds: List[Bird] = africanSwallows
+
+// добавляем новую птицу к африканским ласточкам, `B` - это `Bird`
+val someBirds = africanSwallows.prepend(someBird)
+
+// добавляем европейскую ласточку к птицам
+val moreBirds = birds.prepend(EuropeanSwallow())
+
+// соединяем вместе различных ласточек, `B` - это `Bird`, потому что это общий супертип для обоих типов ласточек
+val allBirds = africanSwallows.prepend(EuropeanSwallow())
+
+// но тут ошибка! добавление списка птиц слишком расширяет тип аргументов. -Xlint предупредит!
+val error = moreBirds.prepend(swallowsFromAntarctica) // List[Object]
```
-`Node[Bird]` может быть присвоен `africanSwallowList` , но затем может добавлять и `EuropeanSwallow`.
+
+{% endtab %}
+{% endtabs %}
+
+Параметр ковариантного типа позволяет `birds` получать значение `africanSwallows`.
+
+Тип, связанный с параметром типа `prepend`, позволяет добавлять различные разновидности ласточек и получать более абстрактный тип: вместо `List[AfricanSwallow]`, мы получаем `List[Bird]`.
+
+Используйте `-Xlint`, чтобы предупредить, если аргумент предполагаемого типа слишком абстрактен.
diff --git a/_ru/tour/mixin-class-composition.md b/_ru/tour/mixin-class-composition.md
index ff7c1d60d9..d8cbb24f30 100644
--- a/_ru/tour/mixin-class-composition.md
+++ b/_ru/tour/mixin-class-composition.md
@@ -1,20 +1,20 @@
---
layout: tour
-title: Композиция классов с примесями
-
-discourse: true
-
+title: Композиция классов с трейтами
partof: scala-tour
-
num: 7
language: ru
next-page: higher-order-functions
previous-page: tuples
prerequisite-knowledge: inheritance, traits, abstract-classes, unified-types
-
---
+
Примеси (Mixin) - это трейты, которые используются для создания класса.
+{% tabs mixin-first-exemple class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=mixin-first-exemple %}
+
```scala mdoc
abstract class A {
val message: String
@@ -31,10 +31,44 @@ val d = new D
println(d.message) // I'm an instance of class B
println(d.loudMessage) // I'M AN INSTANCE OF CLASS B
```
-У класса `D` есть суперкласс `B` и примесь `C`. Классы могут иметь только один суперкласс, но много примесей (используя ключевыое слово `extends` и `with` соответственно). Примеси и суперкласс могут иметь один и тот же супертип.
+
+У класса `D` есть суперкласс `B` и трейт `C`.
+Классы могут иметь только один суперкласс, но много трейтов (используя ключевое слово `extends` и `with` соответственно).
+Трейты и суперкласс могут иметь один и тот же супертип.
+
+{% endtab %}
+
+{% tab 'Scala 3' for=mixin-first-exemple %}
+
+```scala
+abstract class A:
+ val message: String
+class B extends A:
+ val message = "I'm an instance of class B"
+trait C extends A:
+ def loudMessage = message.toUpperCase()
+class D extends B, C
+
+val d = D()
+println(d.message) // I'm an instance of class B
+println(d.loudMessage) // I'M AN INSTANCE OF CLASS B
+```
+
+У класса `D` есть суперкласс `B` и трейт `C`.
+Классы могут иметь только один суперкласс, но много трейтов
+(используя ключевое слово `extends` и разделитель `,` соответственно).
+Трейты и суперкласс могут иметь один и тот же супертип.
+
+{% endtab %}
+
+{% endtabs %}
Теперь давайте рассмотрим более интересный пример, начиная с абстрактного класса:
+{% tabs mixin-abstract-iterator class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=mixin-abstract-iterator %}
+
```scala mdoc
abstract class AbsIterator {
type T
@@ -42,10 +76,30 @@ abstract class AbsIterator {
def next(): T
}
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=mixin-abstract-iterator %}
+
+```scala
+abstract class AbsIterator:
+ type T
+ def hasNext: Boolean
+ def next(): T
+```
+
+{% endtab %}
+
+{% endtabs %}
+
Класс имеет абстрактный тип `T` и методы стандартного итератора.
Далее создаем конкретную реализацию класса (все абстрактные члены `T`, `hasNext`, и `next` должны быть реализованы):
+{% tabs mixin-concrete-string-iterator class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=mixin-concrete-string-iterator %}
+
```scala mdoc
class StringIterator(s: String) extends AbsIterator {
type T = Char
@@ -58,26 +112,87 @@ class StringIterator(s: String) extends AbsIterator {
}
}
```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=mixin-concrete-string-iterator %}
+
+```scala
+class StringIterator(s: String) extends AbsIterator:
+ type T = Char
+ private var i = 0
+ def hasNext = i < s.length
+ def next() =
+ val ch = s charAt i
+ i += 1
+ ch
+```
+
+{% endtab %}
+
+{% endtabs %}
+
`StringIterator` принимает `String` и может быть использован для обхода по строке (например, чтоб проверить содержит ли строка определенный символ).
Теперь давайте создадим трейт который тоже наследуется от `AbsIterator`.
+{% tabs mixin-extended-abstract-iterator class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=mixin-extended-abstract-iterator %}
+
```scala mdoc
trait RichIterator extends AbsIterator {
def foreach(f: T => Unit): Unit = while (hasNext) f(next())
}
```
-У этого трейта реализован метод `foreach` который постоянно вызывает переданную ему функцию `f: T => Unit` на каждом новом элементе (`next()`) до тех пор пока в итераторе содержатся элементы (`while (hasNext)`). Поскольку `RichIterator` это трейт, ему не нужно реализовывать членов абстрактного класса `AbsIterator`.
-Мы бы хотели объединить функциональность `StringIterator` и `RichIterator` в один класс.
+У этого трейта реализован метод `foreach`, который постоянно вызывает переданную ему функцию `f: T => Unit`
+на каждом новом элементе (`next()`) до тех пор пока в итераторе содержатся элементы (`while (hasNext)`).
+Поскольку `RichIterator` - это трейт, ему не нужно реализовывать элементы абстрактного класса `AbsIterator`.
+
+{% endtab %}
+
+{% tab 'Scala 3' for=mixin-extended-abstract-iterator %}
+
+```scala
+trait RichIterator extends AbsIterator:
+ def foreach(f: T => Unit): Unit = while hasNext do f(next())
+```
+
+У этого трейта реализован метод `foreach`, который постоянно вызывает переданную ему функцию `f: T => Unit`
+на каждом новом элементе (`next()`) до тех пор пока в итераторе содержатся элементы (`while hasNext`).
+Поскольку `RichIterator` - это трейт, ему не нужно реализовывать элементы абстрактного класса `AbsIterator`.
+
+{% endtab %}
+
+{% endtabs %}
+
+Мы бы хотели объединить функциональность `StringIterator` и `RichIterator` в один класс.
+
+{% tabs mixin-combination-class class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=mixin-combination-class %}
```scala mdoc
-object StringIteratorTest extends App {
- class RichStringIter extends StringIterator("Scala") with RichIterator
- val richStringIter = new RichStringIter
- richStringIter foreach println
-}
+class RichStringIter extends StringIterator("Scala") with RichIterator
+val richStringIter = new RichStringIter
+richStringIter.foreach(println)
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=mixin-combination-class %}
+
+```scala
+class RichStringIter extends StringIterator("Scala"), RichIterator
+val richStringIter = RichStringIter()
+richStringIter.foreach(println)
```
-Новый класс `RichStringIter` включает `StringIterator` как суперкласс и `RichIterator` как примесь.
-Используя только одиночное наследование мы бы не могли добиться того же уровня гибкости.
+{% endtab %}
+
+{% endtabs %}
+
+Новый класс `RichStringIter` включает `StringIterator` как суперкласс и `RichIterator` как трейт.
+
+Используя только одиночное наследование мы бы не смогли добиться того же уровня гибкости.
diff --git a/_ru/tour/multiple-parameter-lists.md b/_ru/tour/multiple-parameter-lists.md
index c4656f5193..99f84700d5 100644
--- a/_ru/tour/multiple-parameter-lists.md
+++ b/_ru/tour/multiple-parameter-lists.md
@@ -1,89 +1,231 @@
---
layout: tour
title: Множественные списки параметров (Каррирование)
-
-discourse: true
-
partof: scala-tour
-
num: 10
language: ru
next-page: case-classes
previous-page: nested-functions
-
---
-Методы могут объявляться с несколькими списками параметров. При этом когда такой метод вызывается с меньшим количеством списков параметров, это приводит к созданию новой функции, которая ожидает на вход не достающий список параметров. Формально это называется [частичное применение](https://en.wikipedia.org/wiki/Partial_application).
+Методы могут объявляться с несколькими списками параметров.
-Например,
-
-```scala mdoc
-val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
-val numberFunc = numbers.foldLeft(List[Int]()) _
+### Пример
-val squares = numberFunc((xs, x) => xs :+ x*x)
-print(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100)
+Вот пример, определенный для трейта `Iterable` из API Scala коллекций:
-val cubes = numberFunc((xs, x) => xs :+ x*x*x)
-print(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000)
+{% tabs foldLeft_definition class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=foldLeft_definition %}
+
+```scala
+trait Iterable[A] {
+ ...
+ def foldLeft[B](z: B)(op: (B, A) => B): B
+ ...
+}
```
-Рассмотрим такие примеры из класса [Traversable](/overviews/collections/trait-traversable.html) коллекции Scala:
+{% endtab %}
-```scala mdoc:fail
+{% tab 'Scala 3' for=foldLeft_definition %}
+
+```scala
+trait Iterable[A]:
+...
def foldLeft[B](z: B)(op: (B, A) => B): B
+...
```
-`foldLeft` применяет бинарный оператор `op` к начальному значению `z` и ко всем остальным элементам коллекции слева направо. Ниже приведен пример его использования.
+{% endtab %}
-Начиная с начального значения 0, `foldLeft` применяет функцию `(m, n) => m + n` к каждому элементу списка и предыдущему накопленному значению.
+{% endtabs %}
-```scala mdoc:nest
+`foldLeft` применяет бинарный оператор `op` к начальному значению `z` и ко всем остальным элементам коллекции слева направо.
+Ниже приведен пример его использования.
+
+Начиная с начального значения `0`, `foldLeft` применяет функцию `(m, n) => m + n` к каждому элементу списка
+и предыдущему накопленному значению.
+
+{% tabs foldLeft_use %}
+
+{% tab 'Scala 2 и 3' for=foldLeft_use %}
+
+```scala mdoc
val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
val res = numbers.foldLeft(0)((m, n) => m + n)
-print(res) // 55
+println(res) // 55
```
-Множественные списки параметров имеют избыточный синтаксис, поэтому их следует использовать экономно. Можем предложить следующие варианты для использования множественных списков (каррирования):
+{% endtab %}
-#### Отдельный функциональный параметр
- Функцию `op` можно выделить в отдельный функциональный параметр у `foldLeft`, благодаря такому выделению становится возможен более элегантный стиль передачи анонимной функции в метод. Без такого выделения код выглядел бы следующим образом:
-```scala
-numbers.foldLeft(0, {(m: Int, n: Int) => m + n})
+{% endtabs %}
+
+### Варианты для использования
+
+Предлагаемые варианты для использования множественных списков параметров включают:
+
+#### Вывод типа
+
+Исторически сложилось, что в Scala вывод типов происходит по одному списку параметров за раз.
+Скажем, у вас есть следующий метод:
+
+{% tabs foldLeft1_definition %}
+
+{% tab 'Scala 2 и 3' for=foldLeft1_definition %}
+
+```scala mdoc
+def foldLeft1[A, B](as: List[A], b0: B, op: (B, A) => B) = ???
+```
+
+{% endtab %}
+
+{% endtabs %}
+
+Затем при желании вызвать его следующим образом, можно обнаружить, что метод не компилируется:
+
+{% tabs foldLeft1_wrong_use %}
+
+{% tab 'Scala 2 и 3' for=foldLeft1_wrong_use %}
+
+```scala mdoc:fail
+def notPossible = foldLeft1(numbers, 0, _ + _)
```
-
- Обратите внимание, что использование отдельного функционального параметра позволяет нам использовать автоматическое выведение типа для него, что делает код еще более кратким, это было бы невозможно без каррирования.
-
+
+{% endtab %}
+
+{% endtabs %}
+
+вам нужно будет вызвать его одним из следующих способов:
+
+{% tabs foldLeft1_good_use %}
+
+{% tab 'Scala 2 и 3' for=foldLeft1_good_use %}
+
```scala mdoc
-numbers.foldLeft(0)(_ + _)
+def firstWay = foldLeft1[Int, Int](numbers, 0, _ + _)
+def secondWay = foldLeft1(numbers, 0, (a: Int, b: Int) => a + b)
```
- Если в утверждении `numbers.foldLeft(0)(_ + _)` зафиксировать отдельный параметр `z`, мы получим частично определенную функцию, которую можно переиспользовать, как показано ниже:
-```scala mdoc:nest
-val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
-val numberFunc = numbers.foldLeft(List[Int]())_ // z = Empty.List[Int]
-val squares = numberFunc((xs, x) => xs:+ x*x)
-print(squares.toString()) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100)
+{% endtab %}
+
+{% endtabs %}
-val cubes = numberFunc((xs, x) => xs:+ x*x*x)
-print(cubes.toString()) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000)
+Это связано с тем, что Scala не может вывести тип функции `_ + _`, так как она все еще выводит `A` и `B`.
+Путем перемещения параметра `op` в собственный список параметров, `A` и `B` выводятся в первом списке.
+Затем эти предполагаемые типы будут доступны для второго списка параметров
+и `_ + _` станет соответствовать предполагаемому типу `(Int, Int) => Int`.
+
+{% tabs foldLeft2_definition_and_use %}
+
+{% tab 'Scala 2 и 3' for=foldLeft2_definition_and_use %}
+
+```scala mdoc
+def foldLeft2[A, B](as: List[A], b0: B)(op: (B, A) => B) = ???
+def possible = foldLeft2(numbers, 0)(_ + _)
+```
+
+{% endtab %}
+
+{% endtabs %}
+
+Последнее определение метода не нуждается в подсказках типа и может вывести все типы своих параметров.
+
+#### Неявные параметры
+
+Чтоб указать что параметр используется [_неявно_ (_implicit_)](/ru/tour/implicit-parameters.html)
+необходимо задавать несколько списков параметров.
+Примером может служить следующее:
+
+{% tabs execute_definition class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=execute_definition %}
+
+```scala mdoc
+def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ???
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=execute_definition %}
+
+```scala
+def execute(arg: Int)(using ec: scala.concurrent.ExecutionContext) = ???
```
- `foldLeft` и `foldRight` может быть использован в любой из следующих вариаций,
+{% endtab %}
+
+{% endtabs %}
+
+#### Частичное применение
+
+Методы могут объявляться с несколькими списками параметров.
+При этом когда такой метод вызывается с меньшим количеством списков параметров,
+это приводит к созданию новой функции,
+которая ожидает на вход недостающий список параметров.
+Формально это называется [частичное применение](https://ru.wikipedia.org/wiki/%D0%A7%D0%B0%D1%81%D1%82%D0%B8%D1%87%D0%BD%D0%BE%D0%B5_%D0%BF%D1%80%D0%B8%D0%BC%D0%B5%D0%BD%D0%B5%D0%BD%D0%B8%D0%B5).
+
+Например,
+
+{% tabs foldLeft_partial %}
+
+{% tab 'Scala 2 и 3' for=foldLeft_partial %}
+
```scala mdoc:nest
val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+val numberFunc = numbers.foldLeft(List[Int]()) _
-numbers.foldLeft(0)((sum, item) => sum + item) // Общая Форма
-numbers.foldRight(0)((sum, item) => sum + item) // Общая Форма
+val squares = numberFunc((xs, x) => xs :+ x*x)
+println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100)
-numbers.foldLeft(0)(_+_) // Форма с каррированием
-numbers.foldRight(0)(_+_) // Форма с каррированием
+val cubes = numberFunc((xs, x) => xs :+ x*x*x)
+println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000)
```
-
-#### Неявные параметры
- Чтоб указать что параметр используется неявно (`implicit`) необходимо задавать несколько списков параметров. Примером может служить следующее:
+{% endtab %}
-```scala
-def execute(arg: Int)(implicit ec: ExecutionContext) = ???
+{% endtabs %}
+
+### Сравнение с «каррированием»
+
+Иногда можно встретить, что метод с несколькими списками параметров называется «каррированный».
+
+Как говорится [в статье на Википедии о каррировании](https://ru.wikipedia.org/wiki/%D0%9A%D0%B0%D1%80%D1%80%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5),
+
+> Каррирование — преобразование функции от многих аргументов в набор вложенных функций,
+> каждая из которых является функцией от одного аргумента.
+
+Мы не рекомендуем использовать слово «каррирование» в отношении множественных списков параметров Scala по двум причинам:
+
+1. В Scala множественные параметры и множественные списки параметров задаются
+ и реализуются непосредственно как часть языка, а не преобразуются из функций с одним параметром.
+
+2. Существует опасность путаницы с методами из стандартной Scala библиотеки
+ [`curried`](
-## Иерархия типов Scala ##
+## Иерархия типов Scala
[`Any`](https://www.scala-lang.org/api/2.12.1/scala/Any.html) это супертип всех типов, также называемый верхним типом. Он определяет несколько универсальных методов, таких как `equals`, `hashCode` и `toString`. У `Any` есть два прямых подкласса: `AnyVal` и `AnyRef`.
@@ -28,6 +23,9 @@ prerequisite-knowledge: classes, basics
Вот пример, демонстрирующий, что строки, целые числа, символы, логические значения и функции являются объектами, как и любой другой объект:
+{% tabs unified-types-1 %}
+{% tab 'Scala 2 и 3' for=unified-types-1 %}
+
```scala mdoc
val list: List[Any] = List(
"a string",
@@ -40,6 +38,9 @@ val list: List[Any] = List(
list.foreach(element => println(element))
```
+{% endtab %}
+{% endtabs %}
+
Объявляем переменную `list` типа `List[Any]`. Список инициализируется элементами различных типов, но все они являются экземпляром `scala.Any`, так что вы можете добавить их в список.
Ниже приведен вывод программы:
@@ -53,30 +54,44 @@ true
```
## Приведение типа
+
Числовые типы могут быть приведены следующим образом:
Например:
+{% tabs unified-types-2 %}
+{% tab 'Scala 2 и 3' for=unified-types-2 %}
+
```scala mdoc
val x: Long = 987654321
-val y: Float = x // 9.8765434E8 (заметьте, что некоторая точность теряется в этом случае.)
+val y: Float = x.toFloat // 9.8765434E8 (заметьте, что некоторая точность теряется в этом случае.)
val face: Char = '☺'
val number: Int = face // 9786
```
+{% endtab %}
+{% endtabs %}
+
Приведение типа - однонаправленно. Следующий пример не скомпилируется:
+{% tabs unified-types-3 %}
+{% tab 'Scala 2 и 3' for=unified-types-3 %}
+
```
val x: Long = 987654321
-val y: Float = x // 9.8765434E8
+val y: Float = x.toFloat // 9.8765434E8
val z: Long = y // обратно не подходит
```
+{% endtab %}
+{% endtabs %}
+
Вы также можете приводить к своему подтипу. Об этом мы поговорим позже в ходе нашего обзора.
## Nothing и Null
-`Nothing` является подтипом всех типов, также называемым нижним типом. Нет значения, которое имеет тип `Nothing`. Обычно он используется чтоб дать сигнал о не вычислимости, например брошено исключение, выход из программы, бесконечное зацикливание (т.е. это тип выражения, которое не вычисляется).
+
+`Nothing` является подтипом всех типов, также называемым нижним типом. Нет значения, которое имеет тип `Nothing`. Обычно он используется чтоб дать сигнал о не вычислимости, например брошено исключение, выход из программы, бесконечное зацикливание (т.е. это тип выражения, которое не вычисляется).
`Null` подтип всех ссылочных типов (т.е. любой подтип AnyRef). Он имеет одно значение, определяемое ключевым словом литерала `null`. `Null` предоставляется в основном для функциональной совместимости с другими языками JVM и почти никогда не должен использоваться в коде Scala. Об альтернативах `null` мы поговорим позднее.
diff --git a/_ru/tour/upper-type-bounds.md b/_ru/tour/upper-type-bounds.md
index 60ca550d59..7a9238016e 100644
--- a/_ru/tour/upper-type-bounds.md
+++ b/_ru/tour/upper-type-bounds.md
@@ -1,21 +1,20 @@
---
layout: tour
title: Верхнее Ограничение Типа
-
-discourse: true
-
partof: scala-tour
categories: tour
num: 20
language: ru
next-page: lower-type-bounds
previous-page: variances
-
---
В Scala [параметры типа](generic-classes.html) и [члены абстрактного типа](abstract-type-members.html) могут быть ограничены определенными диапазонами. Такие диапазоны ограничивают конкретные значение типа и, возможно, предоставляют больше информации о членах таких типов. _Верхнее ограничение типа_ `T <: A` указывает на то что тип `T` относится к подтипу типа `A`.
Приведем пример, демонстрирующий верхнее ограничение для типа класса `PetContainer`:
+{% tabs upper-type-bounds class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds %}
+
```scala mdoc
abstract class Animal {
def name: String
@@ -43,10 +42,53 @@ val dogContainer = new PetContainer[Dog](new Dog)
val catContainer = new PetContainer[Cat](new Cat)
```
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds %}
+
+```scala
+abstract class Animal:
+ def name: String
+
+abstract class Pet extends Animal
+
+class Cat extends Pet:
+ override def name: String = "Cat"
+
+class Dog extends Pet:
+ override def name: String = "Dog"
+
+class Lion extends Animal:
+ override def name: String = "Lion"
+
+class PetContainer[P <: Pet](p: P):
+ def pet: P = p
+
+val dogContainer = PetContainer[Dog](Dog())
+val catContainer = PetContainer[Cat](Cat())
+```
+
+{% endtab %}
+{% endtabs %}
+
+{% tabs upper-type-bounds_error class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds_error %}
+
```scala mdoc:fail
// это не скомпилируется
val lionContainer = new PetContainer[Lion](new Lion)
```
+
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds_error %}
+
+```scala
+// это не скомпилируется
+val lionContainer = PetContainer[Lion](Lion())
+```
+
+{% endtab %}
+{% endtabs %}
+
Класс `PetContainer` принимает тип `P`, который должен быть подтипом `Pet`. `Dog` и `Cat` - это подтипы `Pet`, поэтому мы можем создать новые `PetContainer[Dog]` и `PetContainer[Cat]`. Однако, если мы попытаемся создать `PetContainer[Lion]`, то получим следующую ошибку:
`type arguments [Lion] do not conform to class PetContainer's type parameter bounds [P <: Pet]`
diff --git a/_ru/tour/variances.md b/_ru/tour/variances.md
index c59549f340..c122728f51 100644
--- a/_ru/tour/variances.md
+++ b/_ru/tour/variances.md
@@ -1,31 +1,50 @@
---
layout: tour
title: Вариантность
-
-discourse: true
-
partof: scala-tour
-
num: 19
language: ru
next-page: upper-type-bounds
previous-page: generic-classes
-
---
-Вариантность (Variances) - это указание определенной специфики взаимосвязи между связанными типам. Scala поддерживает вариантную аннотацию типов у [обобщенных классов](generic-classes.html), что позволяет им быть ковариантными, контрвариантными или инвариантными (если нет никакого указание на вариантность). Использование вариантности в системе типов позволяет устанавливать понятные взаимосвязи между сложными типами, в то время как отсутствие вариантности может ограничить повторное использование абстракции класса.
+Вариантность (Variances) - это указание определенной специфики взаимосвязи между связанными типами.
+Scala поддерживает вариантную аннотацию типов у [обобщенных классов](generic-classes.html),
+что позволяет им быть ковариантными, контрвариантными или инвариантными (если нет никакого указания на вариантность).
+Использование вариантности в системе типов позволяет устанавливать понятные взаимосвязи между сложными типами,
+в то время как отсутствие вариантности может ограничить повторное использование абстракции класса.
+
+{% tabs variances_1 %}
+{% tab 'Scala 2 и 3' for=variances_1 %}
```scala mdoc
class Foo[+A] // ковариантный класс
-class Bar[-A] // контрвариантный класс
-class Baz[A] // инвариантными класс
+class Bar[-A] // контравариантный класс
+class Baz[A] // инвариантный класс
```
-### Ковариантность
+{% endtab %}
+{% endtabs %}
+
+### Инвариантность
+
+По умолчанию параметры типа в Scala инвариантны: отношения подтипа между параметрами типа не отражаются в параметризованном типе.
+Чтобы понять, почему это работает именно так, рассмотрим простой параметризованный тип, изменяемый контейнер.
-Параметр типа `A` обобщенного класса можно сделать ковариантным с помощью аннотации `+A`. Для некоторого класса `List[+A]`, указание `A` в виде коварианта подразумевает, что для двух типов `A` и `B`, где `A` является подтипом `B`, `List[A]` представляет собой подтип `List[B]`. Что позволяет нам создавать очень полезные и интуитивно понятные взаимоотношения между типами с использованием обобщений (generics).
+{% tabs invariance_1 %}
+{% tab 'Scala 2 и 3' for=invariance_1 %}
-Рассмотрим простую структуру классов:
+```scala mdoc
+class Box[A](var content: A)
+```
+
+{% endtab %}
+{% endtabs %}
+
+Мы собираемся поместить в него значения типа `Animal` (животное). Этот тип определяется следующим образом:
+
+{% tabs invariance_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=invariance_2 %}
```scala mdoc
abstract class Animal {
@@ -35,120 +54,241 @@ case class Cat(name: String) extends Animal
case class Dog(name: String) extends Animal
```
-И `Cat` (кошка) и `Dog`(собака) являются подтипами `Animal`(животное). Стандартная библиотека Scala имеет обобщенный неизменяемый тип `List[+A]`, где параметр типа `A` является ковариантным. Это означает, что `List[Cat]` - это `List[Animal]`, а `List[Dog]` - это также `List[Animal]`. Интуитивно понятно, что список кошек и список собак - это список животных и вы должны быть в состоянии заменить любого из них на `List[Animal]`.
+{% endtab %}
+{% tab 'Scala 3' for=invariance_2 %}
+
+```scala
+abstract class Animal:
+ def name: String
+
+case class Cat(name: String) extends Animal
+case class Dog(name: String) extends Animal
+```
+
+{% endtab %}
+{% endtabs %}
-В следующем примере метод `printAnimalNames` принимает в качестве аргумента список животных и выводит их имена в новой строке. Если бы `List[A]` не был ковариантным, последние два вызова метода не компилировались бы, что сильно ограничило бы полезность метода `printAnimalNames`.
+Можно сказать, что `Cat` (кот) - это подтип `Animal`, `Dog` (собака) - также подтип `Animal`.
+Это означает, что следующее допустимо и пройдет проверку типов:
+
+{% tabs invariance_3 %}
+{% tab 'Scala 2 и 3' for=invariance_3 %}
```scala mdoc
-object CovarianceTest extends App {
- def printAnimalNames(animals: List[Animal]): Unit = {
- animals.foreach { animal =>
- println(animal.name)
- }
- }
+val myAnimal: Animal = Cat("Felix")
+```
- val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom"))
- val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex"))
+{% endtab %}
+{% endtabs %}
- printAnimalNames(cats)
- // Whiskers
- // Tom
+А контейнеры?
+Является ли `Box[Cat]` подтипом `Box[Animal]`, как `Cat` подтип `Animal`?
+На первый взгляд может показаться, что это правдоподобно,
+но если мы попытаемся это сделать, компилятор сообщит об ошибке:
- printAnimalNames(dogs)
- // Fido
- // Rex
-}
+{% tabs invariance_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=invariance_4 %}
+
+```scala mdoc:fail
+val myCatBox: Box[Cat] = new Box[Cat](Cat("Felix"))
+val myAnimalBox: Box[Animal] = myCatBox // не компилируется
+val myAnimal: Animal = myAnimalBox.content
```
-### Контрвариантность
+{% endtab %}
+{% tab 'Scala 3' for=invariance_4 %}
-Параметр типа `A` обобщенного класса можно сделать контрвариантным с помощью аннотации `-A`. Это создает схожее, но противоположное ковариантным, взаимоотношения между типом параметра и подтипами класса. То есть, для некого класса `Writer[-A]`, указание `A` контрвариантным подразумевает, что для двух типов `A` и `B` где `A` является подтипом `B`, `Writer[B]` является подтипом `Writer[A]`.
+```scala
+val myCatBox: Box[Cat] = Box[Cat](Cat("Felix"))
+val myAnimalBox: Box[Animal] = myCatBox // не компилируется
+val myAnimal: Animal = myAnimalBox.content
+```
-Рассмотрим классы `Cat`, `Dog`, и `Animal`, описанные выше для следующего примера:
+{% endtab %}
+{% endtabs %}
-```scala mdoc
-abstract class Printer[-A] {
- def print(value: A): Unit
-}
+Почему это может быть проблемой?
+Мы можем достать из контейнера кота, и это все еще животное, не так ли? Ну да.
+Но это не все, что мы можем сделать. Мы также можем заменить в контейнере кота другим животным.
+
+{% tabs invariance_5 %}
+{% tab 'Scala 2 и 3' for=invariance_5 %}
+
+```scala
+ myAnimalBox.content = Dog("Fido")
```
-`Printer[A]` - это простой класс, который знает, как распечатать некоторый тип `A`. Давайте определим подклассы для конкретных типов:
+{% endtab %}
+{% endtabs %}
-```scala mdoc
-class AnimalPrinter extends Printer[Animal] {
- def print(animal: Animal): Unit =
- println("The animal's name is: " + animal.name)
-}
+Теперь в контейнере для животных есть собака.
+Все в порядке, вы можете поместить собак в контейнеры для животных, потому что собаки — это животные.
+Но наш контейнер для животных — это контейнер для котов! Нельзя поместить собаку в контейнер с котом.
+Если бы мы могли, а затем попытались достать кота из нашего кошачьего контейнера,
+он оказался бы собакой, нарушающей целостность типа.
-class CatPrinter extends Printer[Cat] {
- def print(cat: Cat): Unit =
- println("The cat's name is: " + cat.name)
-}
+{% tabs invariance_6 %}
+{% tab 'Scala 2 и 3' for=invariance_6 %}
+
+```scala
+ val myCat: Cat = myCatBox.content // myCat стал бы собакой Fido!
```
-Если `Printer[Cat]` знает, как распечатать любой класс `Cat` в консоли, а `Printer[Animal]` знает, как распечатать любое `Animal` в консоли, то разумно если `Printer[Animal]` также знает, как распечатать любое `Cat`. Обратного отношения нет, потому что `Printer[Cat]` не знает, как распечатать любой `Animal` в консоли. Чтоб иметь возможность заменить `Printer[Cat]` на `Printer[Animal]`, необходимо `Printer[A]` сделать контрвариантным.
+{% endtab %}
+{% endtabs %}
-```scala mdoc
-object ContravarianceTest extends App {
- val myCat: Cat = Cat("Boots")
+Из этого мы должны сделать вывод, что между `Box[Cat]` и `Box[Animal]` не может быть отношения подтипа,
+хотя между `Cat` и `Animal` это отношение есть.
- def printMyCat(printer: Printer[Cat]): Unit = {
- printer.print(myCat)
- }
+### Ковариантность
- val catPrinter: Printer[Cat] = new CatPrinter
- val animalPrinter: Printer[Animal] = new AnimalPrinter
+Проблема, с которой мы столкнулись выше, заключается в том,
+что, поскольку мы можем поместить собаку в контейнер для животных,
+контейнер для кошек не может быть контейнером для животных.
- printMyCat(catPrinter)
- printMyCat(animalPrinter)
-}
-```
+Но что, если мы не сможем поместить собаку в контейнер?
+Тогда мы бы могли просто вернуть нашего кота, и это не проблема, чтобы можно было следовать отношениям подтипа.
+Оказывается, это действительно то, что мы можем сделать.
-Результатом работы этой программы будет:
+{% tabs covariance_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=covariance_1 %}
+```scala mdoc
+class ImmutableBox[+A](val content: A)
+val catbox: ImmutableBox[Cat] = new ImmutableBox[Cat](Cat("Felix"))
+val animalBox: ImmutableBox[Animal] = catbox // теперь код компилируется
```
-The cat's name is: Boots
-The animal's name is: Boots
+
+{% endtab %}
+{% tab 'Scala 3' for=covariance_1 %}
+
+```scala
+class ImmutableBox[+A](val content: A)
+val catbox: ImmutableBox[Cat] = ImmutableBox[Cat](Cat("Felix"))
+val animalBox: ImmutableBox[Animal] = catbox // теперь код компилируется
```
-### Инвариантность
+{% endtab %}
+{% endtabs %}
-Обобщенные классы в Scala по умолчанию являются инвариантными. Это означает, что они не являются ни ковариантными, ни контрвариантными друг другу. В контексте следующего примера класс `Container` является инвариантным. Между `Container[Cat]` и `Container[Animal]`, нет ни прямой, ни обратной взаимосвязи.
+Мы говорим, что `ImmutableBox` _ковариантен_ в `A` - на это указывает `+` перед `A`.
+
+Более формально это дает нам следующее отношение:
+если задано некоторое `class Cov[+T]`, то если `A` является подтипом `B`, то `Cov[A]` является подтипом `Cov[B]`.
+Это позволяет создавать очень полезные и интуитивно понятные отношения подтипов с помощью обобщения.
+
+В следующем менее надуманном примере метод `printAnimalNames` принимает список животных в качестве аргумента
+и печатает их имена с новой строки.
+Если бы `List[A]` не был бы ковариантным, последние два вызова метода не компилировались бы,
+что сильно ограничивало бы полезность метода `printAnimalNames`.
+
+{% tabs covariance_2 %}
+{% tab 'Scala 2 и 3' for=covariance_2 %}
```scala mdoc
-class Container[A](value: A) {
- private var _value: A = value
- def getValue: A = _value
- def setValue(value: A): Unit = {
- _value = value
+def printAnimalNames(animals: List[Animal]): Unit =
+ animals.foreach {
+ animal => println(animal.name)
}
-}
+
+val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom"))
+val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex"))
+
+// печатает: "Whiskers", "Tom"
+printAnimalNames(cats)
+
+// печатает: "Fido", "Rex"
+printAnimalNames(dogs)
```
-Может показаться что `Container[Cat]` должен также являться и `Container[Animal]`, но позволить мутабельному обобщенному классу быть ковариантным было бы небезопасно. В данном примере очень важно, чтобы `Container` был инвариантным. Предположим, что `Container` на самом деле был ковариантным, что-то вроде этого могло случиться:
+{% endtab %}
+{% endtabs %}
+
+### Контрвариантность
+
+Мы видели, что можем достичь ковариантности, убедившись, что не сможем поместить что-то в ковариантный тип, а только что-то получить.
+Что, если бы у нас было наоборот, что-то, что можно положить, но нельзя вынуть?
+Такая ситуация возникает, если у нас есть что-то вроде сериализатора, который принимает значения типа `A`
+и преобразует их в сериализованный формат.
+
+{% tabs contravariance_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=contravariance_1 %}
+
+```scala mdoc
+abstract class Serializer[-A] {
+ def serialize(a: A): String
+}
+val animalSerializer: Serializer[Animal] = new Serializer[Animal] {
+ def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }"""
+}
+val catSerializer: Serializer[Cat] = animalSerializer
+catSerializer.serialize(Cat("Felix"))
```
-val catContainer: Container[Cat] = new Container(Cat("Felix"))
-val animalContainer: Container[Animal] = catContainer
-animalContainer.setValue(Dog("Spot"))
-val cat: Cat = catContainer.getValue // Ой, мы бы закончили присвоением собаки к коту.
+
+{% endtab %}
+{% tab 'Scala 3' for=contravariance_1 %}
+
+```scala
+abstract class Serializer[-A]:
+ def serialize(a: A): String
+
+val animalSerializer: Serializer[Animal] = Serializer[Animal]():
+ def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }"""
+
+val catSerializer: Serializer[Cat] = animalSerializer
+catSerializer.serialize(Cat("Felix"))
```
-К счастью, компилятор остановит нас прежде, чем мы зайдем так далеко.
+{% endtab %}
+{% endtabs %}
-### Другие Примеры
+Мы говорим, что `Serializer` _контравариантен_ в `A`, и на это указывает `-` перед `A`.
+Более общий сериализатор является подтипом более конкретного сериализатора.
-Другим примером, который может помочь понять вариантность, является трейт `Function1[-T, +R]` из стандартной библиотеки Scala. `Function1` представляет собой функцию с одним параметром, где первый тип `T` представляет собой тип параметра, а второй тип `R` представляет собой тип результата. Функция `Function1` является контрвариантной в рамках типа принимаемого аргумента, а ковариантной - в рамках возвращаемого типа. Для этого примера мы будем использовать явное обозначение типа `A =>B` чтоб продемонстрировать `Function1[A, B]`.
+Более формально это дает нам обратное отношение: если задано некоторое `class Contra[-T]`,
+то если `A` является подтипом `B`, `Contra[B]` является подтипом `Contra[A]`.
-Рассмотрим схожий пример `Cat`, `Dog`, `Animal` в той же взаимосвязи что и раньше, плюс следующее:
+### Неизменность и вариантность
-```scala mdoc
-abstract class SmallAnimal extends Animal
-case class Mouse(name: String) extends SmallAnimal
+Неизменяемость является важной частью проектного решения, связанного с использованием вариантности.
+Например, коллекции Scala систематически различают [изменяемые и неизменяемые коллекции](https://docs.scala-lang.org/ru/overviews/collections-2.13/overview.html).
+Основная проблема заключается в том, что ковариантная изменяемая коллекция может нарушить безопасность типов.
+Вот почему `List` - ковариантная коллекция, а `scala.collection.mutable.ListBuffer` - инвариантная коллекция.
+`List` - это коллекция в `package scala.collection.immutable`, поэтому она гарантированно будет неизменяемой для всех.
+Принимая во внимание, что `ListBuffer` изменяем, то есть вы можете обновлять, добавлять или удалять элементы `ListBuffer`.
+
+Чтобы проиллюстрировать проблему ковариантности и изменчивости, предположим,
+что `ListBuffer` ковариантен, тогда следующий проблемный пример скомпилируется (на самом деле он не компилируется):
+
+{% tabs immutability_and_variance_2 %}
+{% tab 'Scala 2 и 3' %}
+
+```scala mdoc:fail
+import scala.collection.mutable.ListBuffer
+
+val bufInt: ListBuffer[Int] = ListBuffer[Int](1,2,3)
+val bufAny: ListBuffer[Any] = bufInt
+bufAny(0) = "Hello"
+val firstElem: Int = bufInt(0)
```
-Предположим, мы работаем с функциями, которые принимают типы животных и возвращают типы еды, которую они едят. Если мы хотим `Cat => SmallAnimal` (потому что кошки едят маленьких животных), но вместо этого мы получим функцию `Animal => Mouse`, то наша программа все равно будет работать. Интуитивно функция `Animal => Mouse` все равно будет принимать `Cat` в качестве аргумента, тк `Cat` является `Animal`, и возвращать `Mouse` - который также является и `SmallAnimal`. Поскольку мы можем безопасно заменить первое вторым, можно сказать, что `Animal => Mouse` аналогично `Cat => SmallAnimal`.
+{% endtab %}
+{% endtabs %}
+
+Если бы приведенный выше код был бы возможен, то вычисление `firstElem` завершилась бы ошибкой с `ClassCastException`,
+потому что `bufInt(0)` теперь содержит `String`, а не `Int`.
+
+Инвариантность `ListBuffer` означает, что `ListBuffer[Int]` не является подтипом `ListBuffer[Any]`,
+несмотря на то, что `Int` является подтипом `Any`,
+и поэтому `bufInt` не может быть присвоен в качестве значения `bufAny`.
### Сравнение с другими языками
-В языках, похожих на Scala, разные способы поддержи вариантности. Например, указания вариантности в Scala очень похожи на то, как это делается в C#, где такие указания добавляются при объявлении абстракции класса (вариантность при объявлении). Однако в Java, указание вариантности задается непосредственно при использовании абстракции класса (вариантность при использовании).
+В языках, похожих на Scala, разные способы поддержки вариантности.
+Например, указания вариантности в Scala очень похожи на то, как это делается в C#,
+где такие указания добавляются при объявлении абстракции класса (вариантность при объявлении).
+Однако в Java, указание вариантности задается непосредственно при использовании абстракции класса (вариантность при использовании).
+
+Тенденция Scala к неизменяемым типам делает ковариантные и контравариантные типы более распространенными,
+чем в других языках, поскольку изменяемый универсальный тип должен быть инвариантным.
diff --git a/_sass/base/helper.scss b/_sass/base/helper.scss
index 1b32d31165..8b6f9c46d2 100755
--- a/_sass/base/helper.scss
+++ b/_sass/base/helper.scss
@@ -3,12 +3,50 @@
//------------------------------------------------
.wrap {
- @include outer-container;
- @include padding(0 20px);
+ @include outer-container;
+ @include padding(0 20px);
+}
+
+.place-inline {
+ // add vertical margin
+ @include outer-container;
+ @include margin(20px 0);
+}
+
+.inline-sticky-top {
+ position: sticky;
+ top: 15px;
+ margin-bottom: 25px;
+ background: #fff;
+ -webkit-box-shadow: 0 0 18px 20px #fff;
+ -moz-box-shadow: 0 0 18px 20px #fff;
+ box-shadow: 0 0 18px 20px #fff;
+ z-index: 5;
+}
+
+.inline-sticky-top.inline-sticky-top-higher {
+ z-index: 7;
+}
+
+.wrap-inline {
+ // add vertical padding
+ @include outer-container;
+ @include padding(20px 0);
+}
+
+.wrap-tab {
+ @extend .wrap-narrow;
+ margin-top: 20px;
+ margin-bottom: 20px;
+}
+
+.wrap-narrow {
+ @include outer-container;
+ @include padding(0 10px);
}
.dot {
- font-size: 10px;
- color: rgba($base-font-color-light, 0.6);
- margin: 0 3px;
+ font-size: 10px;
+ color: rgba($base-font-color-light, 0.6);
+ margin: 0 3px;
}
diff --git a/_sass/components/alt-details.scss b/_sass/components/alt-details.scss
new file mode 100644
index 0000000000..c86febae5d
--- /dev/null
+++ b/_sass/components/alt-details.scss
@@ -0,0 +1,83 @@
+// ALT-DETAILS
+//------------------------------------------------
+//------------------------------------------------
+
+.alt-details.help-info {
+ .alt-details-toggle {
+ background-color: $brand-primary;
+ color: white;
+
+ &:hover {
+ background-color: darken($brand-primary, 15%);
+ }
+ }
+
+ .alt-details-detail {
+ background: #fae6e6
+ }
+}
+
+.alt-details {
+ @include span-columns(12);
+
+ .alt-details-toggle {
+ @include span-columns(12);
+ font-family: $base-font-family;
+ line-height: normal;
+ text-align: center;
+ border: none;
+ background-color: $brand-tertiary;
+ padding: 5px 10px;
+ border-radius: $border-radius-large;
+ font-size: $font-size-medium;
+ cursor: pointer;
+ font-weight: 500;
+ color: $gray-dark;
+
+ &:hover {
+ background-color: darken($brand-tertiary, 15%);
+ }
+
+ &:after {
+ // show a right arrow at the end of the toggle element
+ content: "\f138"; //
+ font-family: "Font Awesome 5 Free";
+ font-weight: 900;
+ font-size: 15px;
+ float: right;
+ margin-top: 2px;
+ }
+
+ }
+
+ .alt-details-control {
+ margin: 0;
+ }
+
+ .alt-details-control+.alt-details-toggle+.alt-details-detail {
+ // by default, hide the details
+ position: absolute;
+ top: -999em;
+ left: -999em;
+ }
+
+ .alt-details-control:checked+.alt-details-toggle+.alt-details-detail {
+ // show the details when the control is checked
+ position: static;
+ }
+
+ .alt-details-control:checked+.alt-details-toggle:after {
+ // change the marker on the toggle label to a down arrow
+ content: "\f13a"; //
+ }
+
+ .alt-details-detail {
+ // The detail box appears to be underneath the toggle button
+ // so we add a padding to the top and push it up.
+ border-bottom: $base-border-gray;
+ border-left: $base-border-gray;
+ border-right: $base-border-gray;
+ padding-top: 15px;
+ margin-top: 15px;
+ }
+}
diff --git a/_sass/components/code.scss b/_sass/components/code.scss
index e771eb6ad1..15e8c641e3 100755
--- a/_sass/components/code.scss
+++ b/_sass/components/code.scss
@@ -23,3 +23,45 @@
}
}
+
+.code-snippet-area {
+ width: 100%;
+ margin-top: 1em;
+ margin-bottom: 1em;
+ position: relative; // so we can position the buttons
+
+ &:hover {
+
+ // display the copy buttons on hover of the whole area
+ .code-snippet-buttons {
+ opacity: 0.95;
+
+ &:active {
+ transition: none;
+ opacity: 0.7;
+ }
+ }
+ }
+
+ .code-snippet-buttons {
+ opacity: 0; // default invisible until hover
+ transition: $base-transition;
+ position: absolute; // so we can position the buttons
+ right: 3px;
+ top: 5px;
+
+ button {
+ border: none;
+ background: #fff;
+ font-size: $font-size-medium;
+ color: $gray-darker;
+ cursor: pointer;
+ }
+ }
+
+ .code-snippet-display {
+ margin-top: 0px;
+ margin-bottom: 0px;
+ width: 100%;
+ }
+}
diff --git a/_sass/components/dropdown.scss b/_sass/components/dropdown.scss
index 6cf33e73ca..b656233a34 100644
--- a/_sass/components/dropdown.scss
+++ b/_sass/components/dropdown.scss
@@ -2,6 +2,8 @@
//------------------------------------------------
//------------------------------------------------
+$border-1-grey: 1px solid rgba(128, 128, 128, 0.5);
+
.language-dropdown {
position: relative;
margin-top: 50px;
@@ -17,6 +19,7 @@
// width: 100%;
// }
float: right;
+ padding-right: 6px; // leave space for the search bar
.table-of-content & {
margin-top: 0;
@@ -31,8 +34,13 @@
box-sizing: border-box;
.table-of-content & {
- border: 1px solid rgba(128, 128, 128, 0.5);
+ border: $border-1-grey;
+ }
+
+ .full-width & {
+ border: $border-1-grey;
}
+
.table-of-content &:focus {
}
diff --git a/_sass/components/heading-anchor.scss b/_sass/components/heading-anchor.scss
new file mode 100644
index 0000000000..a38b6d96bf
--- /dev/null
+++ b/_sass/components/heading-anchor.scss
@@ -0,0 +1,12 @@
+// HEADING ANCHOR
+//------------------------------------------------
+//------------------------------------------------
+
+.heading-anchor {
+ visibility: hidden;
+ padding-left: 0.5em;
+
+ &:hover {
+ text-decoration: none;
+ }
+}
diff --git a/_sass/components/search.scss b/_sass/components/search.scss
index de18915531..5a25704964 100755
--- a/_sass/components/search.scss
+++ b/_sass/components/search.scss
@@ -2,6 +2,19 @@
//------------------------------------------------
//------------------------------------------------
+// Override the styles below to style the search container
+// when it is shown on a specific page (as opposed to the
+// landing page)
+.titles + .search-container {
+ @include span-columns(3);
+ @include bp(medium) {
+ display: none;
+ }
+ float: right;
+ margin-top: 50px;
+ margin-right: 0;
+}
+
.search-container {
position: relative;
margin-top: 20px;
diff --git a/_sass/components/tab.scss b/_sass/components/tab.scss
index b5a9bb89c3..8207f3eb52 100755
--- a/_sass/components/tab.scss
+++ b/_sass/components/tab.scss
@@ -2,15 +2,21 @@
//------------------------------------------------
//------------------------------------------------
+// dynamic tab switching based on https: //levelup.gitconnected.com/tabbed-interfaces-without-javascript-661bab1eaec8
+
.nav-tab {
border-bottom: $base-border-gray;
@include display(flex);
@include align-items(center);
@include justify-content(flex-start);
- margin-bottom: 10px;
+ overflow-x: auto; // scrollbar when width is too small.
+ overflow-y: hidden;
.item-tab {
+
+ label,
a {
+ transition: none; // do not animate the transition to active
color: $base-font-color-light;
display: block;
padding: 0 20px 10px;
@@ -23,21 +29,107 @@
color: $base-font-color;
}
- &.active {
- border-bottom: 2px solid $brand-primary;
- color: $brand-primary;
- pointer-events: none;
+ &:hover {
+ cursor: pointer;
}
}
+ label {
+ -webkit-touch-callout: none;
+ -webkit-user-select: none;
+ -khtml-user-select: none;
+ -moz-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+ }
+
}
+
@include bp(small) {
@include justify-content(space-between);
+
.item-tab {
- a {
- padding: 0 10px 10px;
- font-size: $font-size-medium;
+ label,
+ a {
+ transition: none; // do not animate the transition to active
+ padding: 0 10px 10px;
+ font-size: $font-size-medium;
+ }
}
+ }
+}
+
+/* Active Tabs for standard screen size */
+.nav-tab>.item-tab>a.active, // used in the blog
+.tabsection>input:nth-child(1):checked~.nav-tab .item-tab:nth-child(1) label,
+.tabsection>input:nth-child(2):checked~.nav-tab .item-tab:nth-child(2) label,
+.tabsection>input:nth-child(3):checked~.nav-tab .item-tab:nth-child(3) label,
+.tabsection>input:nth-child(4):checked~.nav-tab .item-tab:nth-child(4) label,
+.tabsection>input:nth-child(5):checked~.nav-tab .item-tab:nth-child(5) label,
+.tabsection>input:nth-child(6):checked~.nav-tab .item-tab:nth-child(6) label,
+.tabsection>input:nth-child(7):checked~.nav-tab .item-tab:nth-child(7) label,
+.tabsection>input:nth-child(8):checked~.nav-tab .item-tab:nth-child(8) label,
+.tabsection>input:nth-child(9):checked~.nav-tab .item-tab:nth-child(9) label {
+ border-bottom: 2px solid $brand-primary;
+ padding: 0 20px 8px; // so text does not jump up when active
+ color: $brand-primary;
+ pointer-events: none;
+}
+
+/* Active Tabs for small screen size */
+@include bp(small) {
+ .nav-tab>.item-tab>a.active,
+ .tabsection>input:nth-child(1):checked~.nav-tab .item-tab:nth-child(1) label,
+ .tabsection>input:nth-child(2):checked~.nav-tab .item-tab:nth-child(2) label,
+ .tabsection>input:nth-child(3):checked~.nav-tab .item-tab:nth-child(3) label,
+ .tabsection>input:nth-child(4):checked~.nav-tab .item-tab:nth-child(4) label,
+ .tabsection>input:nth-child(5):checked~.nav-tab .item-tab:nth-child(5) label,
+ .tabsection>input:nth-child(6):checked~.nav-tab .item-tab:nth-child(6) label,
+ .tabsection>input:nth-child(7):checked~.nav-tab .item-tab:nth-child(7) label,
+ .tabsection>input:nth-child(8):checked~.nav-tab .item-tab:nth-child(8) label,
+ .tabsection>input:nth-child(9):checked~.nav-tab .item-tab:nth-child(9) label {
+ padding: 0 10px 8px; // match narrower padding for inactive tabs
+ }
+}
+
+.tabsection {
+ padding: 0.1px 0; // ensure inner content is correctly padded
+ border-left: 2px solid $base-border-color-gray;
+
+ .nav-tab {
+ padding-left: 0;
+ margin-bottom: 0;
+
+ .item-tab {
+ padding: 0;
+ margin-bottom: 0;
+ list-style: none;
}
}
+
+ input { // hide the input because they are not interactive
+ display: block; /* "enable" hidden elements in IE/edge */
+ position: absolute; /* then hide them off-screen */
+ left: -100%;
+ }
+
+ .tabcontent {
+ section { // by default, hide all sections until the user clicks on the associated label
+ position: absolute;
+ top: -999em;
+ left: -999em;
+ }
+ }
+}
+
+.tabsection>input:nth-child(1):checked~.tabcontent section:nth-child(1),
+.tabsection>input:nth-child(2):checked~.tabcontent section:nth-child(2),
+.tabsection>input:nth-child(3):checked~.tabcontent section:nth-child(3),
+.tabsection>input:nth-child(4):checked~.tabcontent section:nth-child(4),
+.tabsection>input:nth-child(5):checked~.tabcontent section:nth-child(5),
+.tabsection>input:nth-child(6):checked~.tabcontent section:nth-child(6),
+.tabsection>input:nth-child(7):checked~.tabcontent section:nth-child(7),
+.tabsection>input:nth-child(8):checked~.tabcontent section:nth-child(8),
+.tabsection>input:nth-child(9):checked~.tabcontent section:nth-child(9) {
+ position: static;
}
diff --git a/_sass/components/wip-notice.scss b/_sass/components/wip-notice.scss
index b4a011e9fa..3c84c75ac0 100644
--- a/_sass/components/wip-notice.scss
+++ b/_sass/components/wip-notice.scss
@@ -2,7 +2,8 @@
position: relative;
top: 1em;
padding: 1em;
- background: rgba(255,255,255,0.7);
+ border-radius: 5px;
+ background: $gray-light;
a {
color: $brand-primary;
diff --git a/_sass/layout/details-summary.scss b/_sass/layout/details-summary.scss
new file mode 100644
index 0000000000..1f18d4cd64
--- /dev/null
+++ b/_sass/layout/details-summary.scss
@@ -0,0 +1,3 @@
+details > summary > p {
+ display: inline;
+}
diff --git a/_sass/layout/doc-navigation.scss b/_sass/layout/doc-navigation.scss
index 7fa75f5d6a..7539881c3f 100644
--- a/_sass/layout/doc-navigation.scss
+++ b/_sass/layout/doc-navigation.scss
@@ -65,7 +65,7 @@ $nav-height: 46px;
position: absolute;
margin-top: 10px;
display: none;
- z-index: 1;
+ z-index: 40;
box-shadow: 0 3px 12px rgba(0, 0, 0, 0.15);
@include bp(medium) {
diff --git a/_sass/layout/documentation.scss b/_sass/layout/documentation.scss
index 6954645f23..c4e56bd3d4 100644
--- a/_sass/layout/documentation.scss
+++ b/_sass/layout/documentation.scss
@@ -9,7 +9,7 @@
.content-title-documentation {
.titles {
- @include span-columns(9);
+ @include span-columns(6);
@include bp(medium) {
@include span-columns(12);
}
@@ -44,6 +44,10 @@
.content-primary.documentation {
line-height: 1.3;
+ p {
+ line-height: 1.5;
+ }
+
ol {
margin-bottom: 18px;
}
@@ -58,75 +62,43 @@
font-weight: $font-bold;
padding: 1px 5px;
}
-}
-a.new-version-notice {
- display: block;
- background: rgb(255, 255, 200);
- font-size: large;
- text-align: center;
-}
-
-// Styles for the index of docs.scala-lang.org
-.landing-page .title-page {
- background: $gray-li;
-
- h1 {
- color: rgb(134,161,166);
+ .tag-inline {
+ float: none;
}
-}
-
-.landing-page .table-of-content .wrap {
-
- position: relative;
- h5 {
- margin: 0;
- }
-
- .language-header {
- padding: 30px;
- background: $brand-tertiary;
+ h1,
+ h3,
+ h4,
+ h5,
+ h6 {
+ .heading-anchor {
+ color: $base-font-color;
+ }
- h1 {
- font-size: 1.875rem;
- font-family: $base-font-family;
- text-transform: uppercase;
- text-shadow: $text-shadow;
- color: #fff;
+ &:hover {
+ .heading-anchor {
+ visibility: visible;
+ }
}
}
- .language-footer {
- bottom: 0;
- width: 100%;
-
- .go-btn {
- display: block;
- padding: 20px;
- height: 66px;
- background: #fff;
- border-top: 1px solid lighten($base-font-color-light, 35%);
- color: lighten($base-font-color-light, 10%);
- font-weight: $font-regular;
- font-size: $font-regular;
- text-decoration: none;
+ h2 {
+ .heading-anchor {
+ color: $brand-tertiary;
+ }
- &:hover {
- cursor: pointer;
- background: #E5EAEA;
- color: rgba(0, 0, 0, 0.4);
+ &:hover {
+ .heading-anchor {
+ visibility: visible;
}
}
}
-
- &:first-of-type {
- margin-bottom: 20px;
- }
}
-.landing-page .table-of-content .wrap.scala3 {
- .language-header {
- background: $brand-tertiary-dotty;
- }
+a.new-version-notice {
+ display: block;
+ background: rgb(255, 255, 200);
+ font-size: large;
+ text-align: center;
}
diff --git a/_sass/layout/footer.scss b/_sass/layout/footer.scss
index d21eb9e50e..e6f690fd4e 100755
--- a/_sass/layout/footer.scss
+++ b/_sass/layout/footer.scss
@@ -84,7 +84,7 @@
text-align: center;
z-index: 2;
color: #f0f3f3;
- background-color: #dc322f;
+ background-color: $brand-primary;
border-radius: 50%;
display: none;
diff --git a/_sass/layout/glossary.scss b/_sass/layout/glossary.scss
index e55ef1c9aa..8346ea1b40 100644
--- a/_sass/layout/glossary.scss
+++ b/_sass/layout/glossary.scss
@@ -55,7 +55,7 @@
}
li {
- h4 {
+ h3 {
text-transform: none;
margin-bottom: 2px;
font-weight: $font-black;
diff --git a/_sass/layout/header.scss b/_sass/layout/header.scss
index ab392dfd77..ff1b4fdb70 100755
--- a/_sass/layout/header.scss
+++ b/_sass/layout/header.scss
@@ -18,6 +18,23 @@
padding: 10px 40px;
}
+ &.alert-warning {
+ background: $warning-bg;
+ color: $warning-text;
+
+ a {
+ color: $warning-link;
+ font-weight: bold;
+ text-decoration: underline;
+
+ &:active,
+ &:focus,
+ &:hover {
+ text-decoration: none;
+ }
+ }
+ }
+
span {
position: absolute;
right: 20px;
diff --git a/_sass/layout/inner-main.scss b/_sass/layout/inner-main.scss
index 6233be6fdb..64074851c8 100755
--- a/_sass/layout/inner-main.scss
+++ b/_sass/layout/inner-main.scss
@@ -2,17 +2,21 @@
//------------------------------------------------
//------------------------------------------------
+#inner-main>section:nth-child(2) {
+ // corresponds to area with the content below the title
+ position: relative;
+ top: -80px; // have it overlap with the title area
+}
+
#inner-main {
background: $gray-lighter;
padding-bottom: $padding-xlarge;
-
- section:nth-child(2) {
- position: relative;
- top: -80px;
- }
-
.inner-box {
+ margin-bottom: 30px;
+ &:last-child {
+ margin-bottom: 0;
+ }
padding: $padding-medium;
background: #fff;
@include border-radius($border-radius-base);
@@ -43,6 +47,10 @@
order: 1;
margin-bottom: 30px;
}
+
+ @include bp(medium) {
+ order: 3; // move TOC to the bottom on mobile
+ }
}
.content-nav-blog {
@@ -77,13 +85,6 @@
&:nth-child(2n) {
clear: none;
}
-
- &:active,
- &:focus,
- &:hover {
- text-decoration: none;
- background: none;
- }
}
}
}
diff --git a/_sass/layout/online-courses.scss b/_sass/layout/online-courses.scss
new file mode 100644
index 0000000000..e9410fcf02
--- /dev/null
+++ b/_sass/layout/online-courses.scss
@@ -0,0 +1,45 @@
+.online-courses {
+ margin-bottom: 30px;
+}
+
+.online-courses-wrapper {
+ @include clearfix;
+}
+
+.online-courses-image {
+ @include span-columns(5);
+ @include bp(medium) {
+ @include span-columns(12);
+ }
+
+ img {
+ margin-bottom: 0;
+ }
+}
+
+.online-courses-content {
+ @include span-columns(7);
+ @include bp(medium) {
+ @include span-columns(12);
+ }
+
+ h2 {
+ margin-top: 16px;
+ margin-bottom: 16px;
+ }
+
+ blockquote,
+ p,
+ pre,
+ table,
+ ul {
+ margin-bottom: 8px;
+ }
+
+ ol,
+ ul {
+ li {
+ margin-bottom: 4px;
+ }
+ }
+}
diff --git a/_sass/layout/sips.scss b/_sass/layout/sips.scss
index 631c07762c..7fa2d5114e 100644
--- a/_sass/layout/sips.scss
+++ b/_sass/layout/sips.scss
@@ -103,41 +103,29 @@
.sips {
- .pending,
- .completed,
- .dormant,
- .rejected {
- .date {
- display: block;
- font-size: $font-size-small;
- text-transform: uppercase;
- font-weight: $font-bold;
- color: $base-font-color-light;
- margin-top: 4px;
- }
+ .sip-list {
strong {
font-weight: $font-black;
+ display: block;
+ }
+
+ .no-fragmentation {
+ break-inside: avoid;
}
.tag {
float: left;
- position: relative;
display: block;
- top: 3px;
color: #fff;
text-transform: uppercase;
font-size: 11px;
font-weight: 700;
padding: 1px 5px;
+ margin-left: 1px;
+ margin-top: 1px;
}
- }
- .pending {
- display: flex;
- // flex-direction: column;
- // flex-wrap: wrap;
- // max-height: 400px;
ul {
list-style: inside disc;
-webkit-column-count: 2; /* Chrome, Safari, Opera */
@@ -163,41 +151,4 @@
}
}
- .other-sips {
- @include display(flex);
- @include flex-direction(row);
- @include flex-wrap(wrap);
- @include justify-content(space-between);
-
- .completed,
- .dormant,
- .rejected {
- display: flex;
- flex-direction: column;
- // justify-content: flex-end;
- position: relative;
- flex: 0 1 calc(50% - 1em);
-
- @include bp(medium) {
- flex: 0 1 calc(100% - 0.5em);
- }
-
- ul {
- // padding-left: 0px;
-
- li {
- // margin-left: 1em;
- padding-bottom: 24px;
- line-height: 1;
- }
-
- a {
- color: $gray-darker;
- &:hover {
- color: $brand-primary;
- }
- }
- }
- }
- }
}
diff --git a/_sass/layout/table-of-content.scss b/_sass/layout/table-of-content.scss
index 5dca9f7945..e846256f73 100755
--- a/_sass/layout/table-of-content.scss
+++ b/_sass/layout/table-of-content.scss
@@ -65,7 +65,9 @@
@include justify-content(flex-start);
margin-bottom: 10px;
- .fa {
+ .fa,
+ .fa-regular,
+ .fa-brands {
font-size: 1.563rem;
margin-right: 14px;
color: $brand-primary;
@@ -92,9 +94,9 @@
}
}
- &:active,
- &:focus,
- &:hover {
+ &.doc-item-link:active,
+ &.doc-item-link:focus,
+ &.doc-item-link:hover {
text-decoration: none;
background: $gray-lighter;
}
@@ -109,7 +111,7 @@
@include clearfix;
padding-bottom: $padding-small;
.discourse,
- .gitter {
+ .discord {
h3 {
margin-top: 0;
}
@@ -168,7 +170,7 @@
}
}
- .gitter {
+ .discord {
ul {
li {
@include span-columns(3 of 6);
diff --git a/_sass/layout/talk-to-us.scss b/_sass/layout/talk-to-us.scss
index ca83f9676e..94c6a147e3 100755
--- a/_sass/layout/talk-to-us.scss
+++ b/_sass/layout/talk-to-us.scss
@@ -25,7 +25,7 @@
}
.discourse,
- .gitter {
+ .discord {
margin-bottom: 50px;
@include clearfix;
}
@@ -76,7 +76,7 @@
}
}
- .gitter {
+ .discord {
ul.first {
@include shift(2);
diff --git a/_sass/layout/title-page.scss b/_sass/layout/title-page.scss
index e0a5353faf..208f0b9565 100755
--- a/_sass/layout/title-page.scss
+++ b/_sass/layout/title-page.scss
@@ -2,8 +2,8 @@
//------------------------------------------------
//------------------------------------------------
-.scala3 .title-page {
- background: $brand-tertiary-dotty;
+.outdated-page .title-page {
+ background: $brand-tertiary-outdated;
}
.title-page {
diff --git a/_sass/layout/toc.scss b/_sass/layout/toc.scss
index 0e5e7f71d1..dfacedd379 100644
--- a/_sass/layout/toc.scss
+++ b/_sass/layout/toc.scss
@@ -11,10 +11,6 @@
position: relative;
}
- @include bp(medium) {
- display: none;
- }
-
.contents {
font-weight: 700;
}
@@ -23,14 +19,11 @@
.inner-toc {
max-height: 60vh;
overflow-y: auto;
+ position: relative;
@include bp(large) {
max-height: none;
}
-
- &.book {
- max-height: none;
- }
}
#toc {
@@ -83,11 +76,6 @@
}
}
-// disable floating for the book, since the TOC can become very large
-.scala3 .sidebar-toc-wrapper {
- position: relative;
-}
-
.book #toc {
ul {
margin-top: 5px;
diff --git a/_sass/layout/type-md.scss b/_sass/layout/type-md.scss
index 973a606c02..6548b1ff60 100755
--- a/_sass/layout/type-md.scss
+++ b/_sass/layout/type-md.scss
@@ -45,8 +45,7 @@
h5 {
font-size: 1.0rem;
font-family: $base-font-family;
- text-transform: uppercase;
- font-weight: $font-regular;
+ font-weight: $font-bold;
}
}
@@ -88,6 +87,11 @@
margin-bottom: 18px;
}
+ p + .code-snippet-area {
+ // remove the margin-top for code snippet following a paragraph
+ margin-top: 0px;
+ }
+
h4, h5 {
margin-bottom: 0.5rem;
}
@@ -145,35 +149,52 @@
li,
p,
- tr,
- td,
+ dt,
+ dd,
+ pre {
+ // common code for all code (inline and blocks)
+ code {
+ border: $base-border-gray;
+ }
+ }
+
+ li,
+ p,
dt,
dd {
code {
font-family: 'Consolas';
- @include border-radius($border-radius-small);
- font-size: $font-size-medium;
- background: $gray-lighter;
- color: #667b83;
- // border: 1px solid #ced7d7;
- padding: 0 6px;
- margin: 0 4px;
+ background-color: #fff;
+ color: #859900;
+ @include border-radius($border-radius-medium);
+ padding: 2px 6px;
}
}
- pre {
- margin-bottom: 36px;
+ tr,
+ td{
+ code {
+ font-family: 'Consolas';
+ font-size: 0.9375rem;
+ }
+ }
+
+
+ pre {
code {
- padding: 20px;
+ overflow-x: auto;
+ display: block;
font-size: $font-size-medium;
@include border-radius($border-radius-base);
+ padding: 10px 7px;
}
}
table {
width: 100%;
text-align: left;
+ border-collapse: collapse;
thead {
font-weight: $font-bold;
@@ -181,8 +202,8 @@
td,
th {
- border-bottom: $base-border-gray;
- padding: 6px 0;
+ border: $base-border-gray;
+ padding: 6px;
}
}
@@ -198,6 +219,11 @@
font-style: italic;
@include border-radius($border-radius-base);
+ &.help-info {
+ border: 2px dashed $brand-tertiary-dotty;
+ color: $brand-tertiary-dotty;
+ }
+
p {
margin: 0;
}
diff --git a/_sass/utils/_variables.scss b/_sass/utils/_variables.scss
index 33277a1b03..d018dbae37 100755
--- a/_sass/utils/_variables.scss
+++ b/_sass/utils/_variables.scss
@@ -7,6 +7,7 @@
$brand-primary: #DC322F;
$brand-secondary: #859900;
$brand-tertiary: #5CC6E4;
+$brand-tertiary-outdated: #a9c0c6;
$brand-tertiary-dotty: #E45C77;
//-------------------------------------------------
$gray-darker: #002B36;
@@ -17,6 +18,10 @@ $gray-light: #E5EAEA;
$gray-lighter: #F0F3F3;
$apple-blue: #6dccf5;
+$warning-bg: #FFA500;
+$warning-link: #185eb3;
+$warning-text: #000;
+
//-------------------------------------------------
$headings-font-color: $gray-dark;
$base-font-color: #4A5659;
@@ -74,6 +79,8 @@ $padding-small: 20px;
//------------------------------------------------
$border-radius-base: 3px;
$border-radius-small: 2px;
+$border-radius-medium: 10px;
+$border-radius-large: 15px;
// Breakpoints
//------------------------------------------------
diff --git a/_sass/vendors/neat/settings/_grid.scss b/_sass/vendors/neat/settings/_grid.scss
index fad1e9a445..d2c3639ff8 100755
--- a/_sass/vendors/neat/settings/_grid.scss
+++ b/_sass/vendors/neat/settings/_grid.scss
@@ -22,7 +22,7 @@ $grid-columns: 12 !default;
///
/// @type Number (Unit)
///
-$max-width: 1000px !default;
+$max-width: 1280px!default;
/// When set to true, it sets the box-sizing property of all elements to `border-box`. Set with a `!global` flag.
///
diff --git a/_sips/all.md b/_sips/all.md
index ed26042765..befff8ec61 100644
--- a/_sips/all.md
+++ b/_sips/all.md
@@ -2,69 +2,97 @@
layout: sips
title: List of All SIPs
-redirect_from: "/sips/sip-list.html"
-redirect_from: "/sips/pending/index.html"
+redirect_from:
+ - "/sips/sip-list.html"
+ - "/sips/pending/index.html"
---
+{% assign sips = site.sips | sort: title %}
+{% assign sipData = site.data.sip-data %}
+
+## Pre-SIP Discussions
+
+You can find so-called “pre-SIP discussions” in the Scala Contributors forum, under
+the category [Scala Improvement Process](https://contributors.scala-lang.org/c/sip/13).
+The goal of pre-SIP discussions is to gather initial community feedback and support.
## Pending SIPs
-
+Proposals that are at the design or implementation stage, and that are actively
+discussed by the committee and the proposals’ authors. Click on a proposal to
+read its content, or the corresponding discussions on GitHub if its design has
+not been accepted yet.
+
+
-:9: error: type mismatch;
- found : Double
- required: Int
- f"$height%4d"
- ^
-f 插值器利用了java中的字符串数据格式。这种以%开头的格式在 [Formatter javadoc] 中有相关概述。如果在具体变量后没有%，则格式化程序默认使用 %s（串型）格式。
-
-### raw 插值器
-
-除了对字面值中的字符不做编码外，raw 插值器与 s 插值器在功能上是相同的。如下是个被处理过的字符串：
-
- scala>s"a\nb"
- res0:String=
- a
- b
-这里，s 插值器用回车代替了\n。而raw插值器却不会如此处理。
-
- scala>raw"a\nb"
- res1:String=a\nb
-当不想输入\n被转换为回车的时候，raw 插值器是非常实用的。
-
-除了以上三种字符串插值器外，使用者可以自定义插值器。
-
-### 高级用法
-
-在Scala中，所有处理过的字符串字面值都进行了简单编码转换。任何时候编译器遇到一个如下形式的字符串字面值：
-
- id"string content"
-它都会被转换成一个StringContext实例的call(id)方法。这个方法在隐式范围内仍可用。只需要简单得
-建立一个隐类，给StringContext实例增加一个新方法，便可以定义我们自己的字符串插值器。如下例：
-
- //注意：为了避免运行时实例化，我们从AnyVal中继承。
- //更多信息请见值类的说明
- implicit class JsonHelper(val sc:StringContext) extends AnyVal{
- def json(args:Any*):JSONObject=sys.error("TODO-IMPLEMENT")
- }
-
- def giveMeSomeJson(x:JSONObject):Unit=...
-
- giveMeSomeJson(json"{name:$name,id:$id}")
-在这个例子中，我们试图通过字符串插值生成一个JSON文本语法。隐类 JsonHelper 作用域内使用该语法，且这个JSON方法需要一个完整的实现。只不过，字符串字面值格式化的结果不是一个字符串，而是一个JSON对象。
-
-当编译器遇到"{name:$name,id:$id"}"，它将会被重写成如下表达式：
-
- new StringContext("{name:",",id:","}").json(name,id)
-
-隐类则被重写成如下形式
-
- new JsonHelper(new StringContext("{name:",",id:","}")).json(name,id)
-
-所以，JSON方法可以访问字符串的原生片段而每个表达式都是一个值。这个方法的一个简单但又令人迷惑的例子：
-
- implicit class JsonHelper(val sc:StringContext) extends AnyVal{
- def json(args:Any*):JSONObject={
- val strings=sc.parts.iterator
- val expressions=args.iterator
- var buf=new StringBuilder(strings.next())
- while(strings.hasNext){
- buf.append(expressions.next())
- buf.append(strings.next())
- }
- parseJson(buf)
- }
- }
-
-被处理过的字符串的每部分都是StringContext的成员。每个表达式的值都将传入到JSON方法的args参数。JSON方法接受这些值并合成一个大字符串，然后再解析成JSON格式。有一种更复杂的实现可以避免合成字符串的操作，它只是简单的直接通过原生字符串和表达式值构建JSON。
-
-## 限制
-
-字符串插值目前对模式匹配语句不适用。此特性将在2.11版本中生效。
diff --git a/_zh-cn/overviews/core/value-classes.md b/_zh-cn/overviews/core/value-classes.md
index a04b3a958b..9b9446a94b 100644
--- a/_zh-cn/overviews/core/value-classes.md
+++ b/_zh-cn/overviews/core/value-classes.md
@@ -43,7 +43,7 @@ Value class只能继承universal traits，但其自身不能再被继承。所
def toHexString: String = java.lang.Integer.toHexString(self)
}
-在运行时，表达式3.toHexString 被优化并等价于静态对象的方法调用 （RichInt$.MODULE$.extension$toHexString(3)），而不是创建一个新实例对象，再调用其方法。
+在运行时，表达式3.toHexString 被优化并等价于静态对象的方法调用 （RichInt$.MODULE$.toHexString$extension(3)），而不是创建一个新实例对象，再调用其方法。
## 正确性
diff --git a/_zh-cn/overviews/index.md b/_zh-cn/overviews/index.md
index 533785b420..a051fef550 100644
--- a/_zh-cn/overviews/index.md
+++ b/_zh-cn/overviews/index.md
@@ -1,54 +1,10 @@
---
-layout: inner-page-no-masthead
+layout: overviews
language: zh-cn
partof: overviews
title: 目录
+redirect_from:
+ - /zh-cn/scala3/guides.html
---
-)
+x.take(5) // LazyList()
+x.map(_ + 1) // LazyList()
+```
+{% endtab %}
+{% endtabs %}
+
+在所有这些例子中，什么都没有发生。
+事实上，除非你强迫它发生，否则什么都不会发生，例如通过调用它的 `foreach` 方法：
+
+{% tabs lazylist-evaluation-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> x.take(1).foreach(println)
+1
+```
+{% endtab %}
+{% endtabs %}
+
+有关严格和非严格的用途、好处和缺点的更多信息严格（惰性）集合，请参阅 [Scala 2.13集合的架构][strict] 页面上的“严格”和“非严格”讨论。
+
+
+
+## 向量
+
+[向量](https://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html) 是一个索引的、不可变的序列。
+描述的“索引”部分意味着它提供了在有效恒定时间内随机访问和更新向量，因此您可以通过索引值快速访问 `Vector` 元素，例如访问 `listOfPeople(123_456_789)` 。
+
+一般来说，除了 (a) `Vector` 有索引而 `List` 没有索引，以及 (b) `List` 有 `::` 方法这两个不同外，这两种类型的工作方式相同，所以我们将快速过一下示例。
+
+以下是创建“向量”的几种方法：
+
+{% tabs vector-creation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val nums = Vector(1, 2, 3, 4, 5)
+
+val strings = Vector("one", "two")
+
+case class Person(name: String)
+val people = Vector(
+ Person("Bert"),
+ Person("Ernie"),
+ Person("Grover")
+)
+```
+{% endtab %}
+{% endtabs %}
+
+因为 `Vector` 是不可变的，所以你不能向它添加新元素。
+相反，您通过将元素附加或插入头部到现有的 `Vector`，从而创建新序列。
+这些示例展示了如何将元素_附加_到 `Vector`：
+
+{% tabs vector-appending %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = Vector(1,2,3) // Vector(1, 2, 3)
+val b = a :+ 4 // Vector(1, 2, 3, 4)
+val c = a ++ Vector(4, 5) // Vector(1, 2, 3, 4, 5)
+```
+{% endtab %}
+{% endtabs %}
+
+这就是你_插入头部_元素的方式：
+
+{% tabs vector-prepending %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = Vector(1,2,3) // Vector(1, 2, 3)
+val b = 0 +: a // Vector(0, 1, 2, 3)
+val c = Vector(-1, 0) ++: a // Vector(-1, 0, 1, 2, 3)
+```
+{% endtab %}
+{% endtabs %}
+
+除了快速的随机访问和更新之外，`Vector` 还提供了快速的追加和前置时间，因此您可以根据需要使用这些功能。
+
+> 请参阅 [集合性能特性](https://docs.scala-lang.org/overviews/collections-2.13/performance-characteristics.html) 了解有关 `Vector` 和其他集合的性能详细信息。
+
+最后，您可以在 `for` 循环中使用 `Vector`，就像 `List`、`ArrayBuffer` 或任何其他序列一样：
+
+{% tabs vector-loop class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+scala> val names = Vector("Joel", "Chris", "Ed")
+val names: Vector[String] = Vector(Joel, Chris, Ed)
+
+scala> for (name <- names) println(name)
+Joel
+Chris
+Ed
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+scala> val names = Vector("Joel", "Chris", "Ed")
+val names: Vector[String] = Vector(Joel, Chris, Ed)
+
+scala> for name <- names do println(name)
+Joel
+Chris
+Ed
+```
+{% endtab %}
+{% endtabs %}
+
+## 数组缓冲区
+
+当您在 Scala 应用程序中需要一个通用的、可变的索引序列时，请使用 `ArrayBuffer`。
+它是可变的，所以你可以改变它的元素，也可以调整它的大小。
+因为它是索引的，所以元素的随机访问很快。
+
+### 创建一个数组缓冲区
+
+要使用 `ArrayBuffer`，首先导入它：
+
+{% tabs arraybuffer-import %}
+{% tab 'Scala 2 and 3' %}
+```scala
+import scala.collection.mutable.ArrayBuffer
+```
+{% endtab %}
+{% endtabs %}
+
+如果您需要从一个空的 `ArrayBuffer` 开始，只需指定其类型：
+
+{% tabs arraybuffer-creation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+var strings = ArrayBuffer[String]()
+var ints = ArrayBuffer[Int]()
+var people = ArrayBuffer[Person]()
+```
+{% endtab %}
+{% endtabs %}
+
+如果您知道 `ArrayBuffer` 最终需要的大致大小，则可以使用初始大小创建它：
+
+{% tabs list-creation-with-size %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// ready to hold 100,000 ints
+val buf = new ArrayBuffer[Int](100_000)
+```
+{% endtab %}
+{% endtabs %}
+
+要创建具有初始元素的新 `ArrayBuffer`，只需指定其初始元素，就像 `List` 或 `Vector` 一样：
+
+{% tabs arraybuffer-init %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val nums = ArrayBuffer(1, 2, 3)
+val people = ArrayBuffer(
+ Person("Bert"),
+ Person("Ernie"),
+ Person("Grover")
+)
+```
+{% endtab %}
+{% endtabs %}
+
+### 将元素添加到数组缓冲区
+
+使用 `+=` 和 `++=` 方法将新元素附加到 `ArrayBuffer`。
+或者，如果您更喜欢具有文本名称的方法，您也可以使用 `append`、`appendAll`、`insert`、`insertAll`、`prepend` 和 `prependAll`。
+
+以下是 `+=` 和 `++=` 的一些示例：
+
+{% tabs arraybuffer-add %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val nums = ArrayBuffer(1, 2, 3) // ArrayBuffer(1, 2, 3)
+nums += 4 // ArrayBuffer(1, 2, 3, 4)
+nums ++= List(5, 6) // ArrayBuffer(1, 2, 3, 4, 5, 6)
+```
+{% endtab %}
+{% endtabs %}
+
+### 从数组缓冲区中移除元素
+
+`ArrayBuffer` 是可变的，所以它有 `-=`、`--=`、`clear`、`remove` 等方法。
+这些示例演示了 `-=` 和 `--=` 方法：
+
+{% tabs arraybuffer-remove %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = ArrayBuffer.range('a', 'h') // ArrayBuffer(a, b, c, d, e, f, g)
+a -= 'a' // ArrayBuffer(b, c, d, e, f, g)
+a --= Seq('b', 'c') // ArrayBuffer(d, e, f, g)
+a --= Set('d', 'e') // ArrayBuffer(f, g)
+```
+{% endtab %}
+{% endtabs %}
+
+### 更新数组缓冲区元素
+
+通过重新分配所需元素或使用 `update` 方法来更新 `ArrayBuffer` 中的元素：
+
+{% tabs arraybuffer-update %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = ArrayBuffer.range(1,5) // ArrayBuffer(1, 2, 3, 4)
+a(2) = 50 // ArrayBuffer(1, 2, 50, 4)
+a.update(0, 10) // ArrayBuffer(10, 2, 50, 4)
+```
+{% endtab %}
+{% endtabs %}
+
+## 映射
+
+`Map` 是由键值对组成的可迭代集合。
+Scala 有可变和不可变的 `Map` 类型，本节演示如何使用_不可变_ `Map`。
+
+### 创建不可变映射
+
+像这样创建一个不可变的`Map`：
+
+{% tabs map-init %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val states = Map(
+ "AK" -> "Alaska",
+ "AL" -> "Alabama",
+ "AZ" -> "Arizona"
+)
+```
+{% endtab %}
+{% endtabs %}
+
+一旦你有了一个`Map`，你可以像这样在`for`循环中遍历它的元素：
+
+{% tabs map-loop class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+for ((k, v) <- states) println(s"key: $k, value: $v")
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+for (k, v) <- states do println(s"key: $k, value: $v")
+```
+{% endtab %}
+{% endtabs %}
+
+REPL 展示了它是如何工作的：
+
+{% tabs map-repl class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+scala> for ((k, v) <- states) println(s"key: $k, value: $v")
+key: AK, value: Alaska
+key: AL, value: Alabama
+key: AZ, value: Arizona
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+scala> for (k, v) <- states do println(s"key: $k, value: $v")
+key: AK, value: Alaska
+key: AL, value: Alabama
+key: AZ, value: Arizona
+```
+{% endtab %}
+{% endtabs %}
+
+### 访问映射元素
+
+通过在括号中指定所需的键值来访问映射元素：
+
+{% tabs map-access-element %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val ak = states("AK") // ak: String = Alaska
+val al = states("AL") // al: String = Alabama
+```
+{% endtab %}
+{% endtabs %}
+
+在实践中，您还将使用诸如 `keys`、`keySet`、`keysIterator`、`for` 循环之类的方法以及 `map` 之类的高阶函数来处理 `Map` 键和值。
+
+### 向映射添加元素
+
+使用 `+` 和 `++` 将元素添加到不可变映射中，记住将结果分配给新变量：
+
+{% tabs map-add-element %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = Map(1 -> "one") // a: Map(1 -> one)
+val b = a + (2 -> "two") // b: Map(1 -> one, 2 -> two)
+val c = b ++ Seq(
+ 3 -> "three",
+ 4 -> "four"
+)
+// c: Map(1 -> one, 2 -> two, 3 -> three, 4 -> four)
+```
+{% endtab %}
+{% endtabs %}
+
+### 从映射中删除元素
+
+使用 `-` 或 `--` 和要删除的键值从不可变映射中删除元素，记住将结果分配给新变量：
+
+{% tabs map-remove-element %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = Map(
+ 1 -> "one",
+ 2 -> "two",
+ 3 -> "three",
+ 4 -> "four"
+)
+
+val b = a - 4 // b: Map(1 -> one, 2 -> two, 3 -> three)
+val c = a - 4 - 3 // c: Map(1 -> one, 2 -> two)
+```
+{% endtab %}
+{% endtabs %}
+
+### 更新映射元素
+
+要更新不可变映射中的元素，请在将结果分配给新变量时使用 `updated` 方法（或 `+` 运算符）：
+
+{% tabs map-update-element %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = Map(
+ 1 -> "one",
+ 2 -> "two",
+ 3 -> "three"
+)
+
+val b = a.updated(3, "THREE!") // b: Map(1 -> one, 2 -> two, 3 -> THREE!)
+val c = a + (2 -> "TWO...") // c: Map(1 -> one, 2 -> TWO..., 3 -> three)
+```
+{% endtab %}
+{% endtabs %}
+
+### 遍历映射
+
+如前所述，这是使用 `for` 循环手动遍历映射中元素的常用方法：
+
+{% tabs map-traverse class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val states = Map(
+ "AK" -> "Alaska",
+ "AL" -> "Alabama",
+ "AZ" -> "Arizona"
+)
+
+for ((k, v) <- states) println(s"key: $k, value: $v")
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val states = Map(
+ "AK" -> "Alaska",
+ "AL" -> "Alabama",
+ "AZ" -> "Arizona"
+)
+
+for (k, v) <- states do println(s"key: $k, value: $v")
+```
+{% endtab %}
+{% endtabs %}
+
+话虽如此，有_许多_方法可以使用映射中的键和值。
+常见的 `Map` 方法包括 `foreach`、`map`、`keys` 和 `values`。
+
+Scala 有许多更专业的`Map` 类型，包括`CollisionProofHashMap`、`HashMap`、`LinkedHashMap`、`ListMap`、`SortedMap`、`TreeMap`、`WeakHashMap` 等等。
+
+## 使用集合
+
+Scala [集合]({{site.baseurl}}/overviews/collections-2.13/sets.html) 是一个没有重复元素的可迭代集合。
+
+Scala 有可变和不可变的 `Set` 类型。
+本节演示_不可变_ `Set`。
+
+### 创建一个集合
+
+像这样创建新的空集：
+
+{% tabs set-creation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val nums = Set[Int]()
+val letters = Set[Char]()
+```
+{% endtab %}
+{% endtabs %}
+
+使用初始数据创建集合，如下：
+
+{% tabs set-init %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val nums = Set(1, 2, 3, 3, 3) // Set(1, 2, 3)
+val letters = Set('a', 'b', 'c', 'c') // Set('a', 'b', 'c')
+```
+{% endtab %}
+{% endtabs %}
+
+### 向集合中添加元素
+
+使用 `+` 和 `++` 将元素添加到不可变的 `Set`，记住将结果分配给一个新变量：
+
+{% tabs set-add-element %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = Set(1, 2) // Set(1, 2)
+val b = a + 3 // Set(1, 2, 3)
+val c = b ++ Seq(4, 1, 5, 5) // HashSet(5, 1, 2, 3, 4)
+```
+{% endtab %}
+{% endtabs %}
+
+请注意，当您尝试添加重复元素时，它们会被悄悄删除。
+
+另请注意，元素的迭代顺序是任意的。
+
+### 从集合中删除元素
+
+使用 `-` 和 `--` 从不可变集合中删除元素，再次将结果分配给新变量：
+
+{% tabs set-remove-element %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = Set(1, 2, 3, 4, 5) // HashSet(5, 1, 2, 3, 4)
+val b = a - 5 // HashSet(1, 2, 3, 4)
+val c = b -- Seq(3, 4) // HashSet(1, 2)
+```
+{% endtab %}
+{% endtabs %}
+
+## 范围
+
+Scala `Range` 通常用于填充数据结构和迭代 `for` 循环。
+这些 REPL 示例演示了如何创建范围：
+
+{% comment %}
+LATER: the dotty repl currently shows results differently
+{% endcomment %}
+
+{% tabs range-init %}
+{% tab 'Scala 2 and 3' %}
+```scala
+1 to 5 // Range(1, 2, 3, 4, 5)
+1 until 5 // Range(1, 2, 3, 4)
+1 to 10 by 2 // Range(1, 3, 5, 7, 9)
+'a' to 'c' // NumericRange(a, b, c)
+```
+{% endtab %}
+{% endtabs %}
+
+您可以使用范围来填充集合：
+
+{% tabs range-conversion %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val x = (1 to 5).toList // List(1, 2, 3, 4, 5)
+val x = (1 to 5).toBuffer // ArrayBuffer(1, 2, 3, 4, 5)
+```
+{% endtab %}
+{% endtabs %}
+
+它们也用于 `for` 循环：
+
+{% tabs range-iteration class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+scala> for (i <- 1 to 3) println(i)
+1
+2
+3
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+scala> for i <- 1 to 3 do println(i)
+1
+2
+3
+```
+{% endtab %}
+{% endtabs %}
+
+还有 `range` 方法：
+
+{% tabs range-methods %}
+{% tab 'Scala 2 and 3' %}
+```scala
+Vector.range(1, 5) // Vector(1, 2, 3, 4)
+List.range(1, 10, 2) // List(1, 3, 5, 7, 9)
+Set.range(1, 10) // HashSet(5, 1, 6, 9, 2, 7, 3, 8, 4)
+```
+{% endtab %}
+{% endtabs %}
+
+当您运行测试时，范围对于生成测试集合也很有用：
+
+{% tabs range-tests %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val evens = (0 to 10 by 2).toList // List(0, 2, 4, 6, 8, 10)
+val odds = (1 to 10 by 2).toList // List(1, 3, 5, 7, 9)
+val doubles = (1 to 5).map(_ * 2.0) // Vector(2.0, 4.0, 6.0, 8.0, 10.0)
+
+// create a Map
+val map = (1 to 3).map(e => (e,s"$e")).toMap
+ // map: Map[Int, String] = Map(1 -> "1", 2 -> "2", 3 -> "3")
+```
+{% endtab %}
+{% endtabs %}
+
+## 更多细节
+
+当您需要特定集合更多的信息，请参阅以下资源：
+
+- [具体的不可变集合类](https://docs.scala-lang.org/overviews/collections-2.13/concrete-immutable-collection-classes.html)
+- [具体的可变集合类](https://docs.scala-lang.org/overviews/collections-2.13/concrete-mutable-collection-classes.html)
+- [集合是如何构造的？ 我应该选择哪一个？](https://docs.scala-lang.org/tutorials/FAQ/collections.html)
+
+
+[strict]: {% link _overviews/core/architecture-of-scala-213-collections.md %}
+[collections1]: /resources/images/tour/collections-diagram-213.svg
+[collections2]: /resources/images/tour/collections-immutable-diagram-213.svg
+[collections3]: /resources/images/tour/collections-mutable-diagram-213.svg
diff --git a/_zh-cn/overviews/scala3-book/collections-intro.md b/_zh-cn/overviews/scala3-book/collections-intro.md
new file mode 100644
index 0000000000..0b2e1b77ff
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/collections-intro.md
@@ -0,0 +1,30 @@
+---
+title: Scala 集合
+type: chapter
+description: This page provides and introduction to the common collections classes and their methods in Scala 3.
+language: zh-cn
+num: 37
+previous-page: packaging-imports
+next-page: collections-classes
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本章介绍了最常见的 Scala 3 集合及其附带的方法。
+Scala 提供了丰富的集合类型，但您可以从其中的几个开始，然后根据需要使用其他的。
+同样，每种类型都有数十种方法可以让您的生活更轻松，但您可以从少数几种方法开始使用，就可以有很多收获。
+
+因此，本节介绍并演示您开始时，需要使用的最常见的集合类型和方法。
+
+{% comment %}
+LATER: Use more of the content from this page:
+ https://docs.scala-lang.org/overviews/index.html
+{% endcomment %}
+
+
+
+
diff --git a/_zh-cn/overviews/scala3-book/collections-methods.md b/_zh-cn/overviews/scala3-book/collections-methods.md
new file mode 100644
index 0000000000..898619d144
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/collections-methods.md
@@ -0,0 +1,558 @@
+---
+title: 集合方法
+type: section
+description: This page demonstrates the common methods on the Scala 3 collections classes.
+language: zh-cn
+num: 39
+previous-page: collections-classes
+next-page: collections-summary
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 集合的一大优势在于它们提供了许多开箱即用的方法，并且这些方法在不可变和可变集合类型中始终可用。
+这样做的好处是，您不用在每次需要使用集合时编写自定义的 `for` 循环，并且当您从一个项目转到另一个项目时，您会发现更多地使用这些相同的方法，而不是使用自定义 `for` 循环。
+
+有*几十*种方法可供您使用，因此此处并未全部显示。
+相反，只显示了一些最常用的方法，包括：
+
+- `map`
+- `filter`
+- `foreach`
+- `head`
+- `tail`
+- `take`, `takeWhile`
+- `drop`, `dropWhile`
+- `reduce`
+
+以下方法适用于所有序列类型，包括 `List`、`Vector`、`ArrayBuffer` 等，但除非另有说明，否则这些示例使用 `List`。
+
+> 作为一个非常重要的说明，`List` 上的任何方法都不会改变列表。
+> 它们都以函数式风格工作，这意味着它们返回带有修改结果的新集合。
+
+## 常用方法示例
+
+为了让您大致了解在后面章节中将看到的内容，这些示例展示了一些最常用的集合方法。
+首先，这里有一些不使用 lambda 的方法：
+
+{% tabs common-method-examples %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10)
+
+a.distinct // List(10, 20, 30, 40)
+a.drop(2) // List(30, 40, 10)
+a.dropRight(2) // List(10, 20, 30)
+a.head // 10
+a.headOption // Some(10)
+a.init // List(10, 20, 30, 40)
+a.intersect(List(19,20,21)) // List(20)
+a.last // 10
+a.lastOption // Some(10)
+a.slice(2,4) // List(30, 40)
+a.tail // List(20, 30, 40, 10)
+a.take(3) // List(10, 20, 30)
+a.takeRight(2) // List(40, 10)
+```
+{% endtab %}
+{% endtabs %}
+
+### 高阶函数和 lambda
+
+接下来，我们将展示一些常用的接受 lambda（匿名函数）的高阶函数 (HOF)。
+首先，这里有几个 lambda 语法的变体，从最长的形式开始，逐步过渡最简洁的形式：
+
+{% tabs higher-order-functions-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// these functions are all equivalent and return
+// the same data: List(10, 20, 10)
+
+a.filter((i: Int) => i < 25) // 1. most explicit form
+a.filter((i) => i < 25) // 2. `Int` is not required
+a.filter(i => i < 25) // 3. the parens are not required
+a.filter(_ < 25) // 4. `i` is not required
+```
+{% endtab %}
+{% endtabs %}
+
+在那些编号的例子中：
+
+1. 第一个例子显示了最长的形式。
+ _很少_需要这么多的冗长，并且只在最复杂的用法中需要。
+2. 编译器知道 `a` 包含 `Int`，所以这里没有必要重述。
+3. 只有一个参数时不需要括号，例如`i`。
+4. 当你有一个参数并且它在你的匿名函数中只出现一次时，你可以用 `_` 替换参数。
+
+[匿名函数][lambdas] 提供了与缩短 lambda 表达式相关的规则的更多详细信息和示例。
+
+现在您已经看到了简洁的形式，下面是使用短形式 lambda 语法的其他 HOF 的示例：
+
+{% tabs anonymous-functions-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+a.dropWhile(_ < 25) // List(30, 40, 10)
+a.filter(_ > 100) // List()
+a.filterNot(_ < 25) // List(30, 40)
+a.find(_ > 20) // Some(30)
+a.takeWhile(_ < 30) // List(10, 20)
+```
+{% endtab %}
+{% endtabs %}
+
+值得注意的是，HOF 也接受方法和函数作为参数——不仅仅是 lambda 表达式。
+下面是一些使用名为 `double` 的方法的`map` HOF 示例。
+再次显示了 lambda 语法的几种变体：
+
+{% tabs method-as-parameter-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def double(i: Int) = i * 2
+
+// these all return `List(20, 40, 60, 80, 20)`
+a.map(i => double(i))
+a.map(double(_))
+a.map(double)
+```
+{% endtab %}
+{% endtabs %}
+
+在最后一个示例中，当匿名函数由一个接受单个参数的函数调用组成时，您不必命名参数，因此甚至不需要 `_`。
+
+最后，您可以根据需要组合 HOF 来解决问题：
+
+{% tabs higher-order-functions-combination-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// yields `List(100, 200)`
+a.filter(_ < 40)
+ .takeWhile(_ < 30)
+ .map(_ * 10)
+```
+{% endtab %}
+{% endtabs %}
+
+## 例子数据
+
+以下部分中的示例使用这些列表：
+
+{% tabs sample-data %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val oneToTen = (1 to 10).toList
+val names = List("adam", "brandy", "chris", "david")
+```
+{% endtab %}
+{% endtabs %}
+
+## `map`
+
+`map` 方法遍历现有列表中的每个元素，将您提供的函数应用于每个元素，一次一个；
+然后它返回一个包含所有修改元素的新列表。
+
+这是一个将 `map` 方法应用于 `oneToTen` 列表的示例：
+
+{% tabs map-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val doubles = oneToTen.map(_ * 2)
+doubles: List[Int] = List(2, 4, 6, 8, 10, 12, 14, 16, 18, 20)
+```
+{% endtab %}
+{% endtabs %}
+
+您还可以使用长格式编写匿名函数，如下所示：
+
+{% tabs map-example-anonymous %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val doubles = oneToTen.map(i => i * 2)
+doubles: List[Int] = List(2, 4, 6, 8, 10, 12, 14, 16, 18, 20)
+```
+{% endtab %}
+{% endtabs %}
+
+但是，在本课中，我们将始终使用第一种较短的形式。
+
+以下是更多应用于 `oneToTen` 和 `names` 列表的 `map` 方法的示例：
+
+{% tabs few-more-examples %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val capNames = names.map(_.capitalize)
+capNames: List[String] = List(Adam, Brandy, Chris, David)
+
+scala> val nameLengthsMap = names.map(s => (s, s.length)).toMap
+nameLengthsMap: Map[String, Int] = Map(adam -> 4, brandy -> 6, chris -> 5, david -> 5)
+
+scala> val isLessThanFive = oneToTen.map(_ < 5)
+isLessThanFive: List[Boolean] = List(true, true, true, true, false, false, false, false, false, false)
+```
+{% endtab %}
+{% endtabs %}
+
+如最后两个示例所示，使用 `map` 返回与原始类型不同类型的集合是完全合法的（并且很常见）。
+
+## `filter`
+
+`filter` 方法创建一个新列表，其中包含满足所提供谓词的元素。
+谓词或条件是返回 `Boolean`（`true` 或 `false`）的函数。
+这里有一些例子：
+
+{% tabs filter-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val lessThanFive = oneToTen.filter(_ < 5)
+lessThanFive: List[Int] = List(1, 2, 3, 4)
+
+scala> val evens = oneToTen.filter(_ % 2 == 0)
+evens: List[Int] = List(2, 4, 6, 8, 10)
+
+scala> val shortNames = names.filter(_.length <= 4)
+shortNames: List[String] = List(adam)
+```
+{% endtab %}
+{% endtabs %}
+
+集合上的函数式方法的一个优点是您可以将它们链接在一起以解决问题。
+例如，这个例子展示了如何链接 `filter` 和 `map`：
+
+{% tabs filter-example-anonymous %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.filter(_ < 4).map(_ * 10)
+```
+{% endtab %}
+{% endtabs %}
+
+REPL 显示结果：
+
+{% tabs filter-example-anonymous-repl %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> oneToTen.filter(_ < 4).map(_ * 10)
+val res1: List[Int] = List(10, 20, 30)
+```
+{% endtab %}
+{% endtabs %}
+
+## `foreach`
+
+`foreach` 方法用于遍历集合中的所有元素。
+请注意，`foreach` 用于副作用，例如打印信息。
+这是一个带有 `names` 列表的示例：
+
+{% tabs foreach-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> names.foreach(println)
+adam
+brandy
+chris
+david
+```
+{% endtab %}
+{% endtabs %}
+
+## `head`
+
+`head` 方法来自 Lisp 和其他早期的函数式编程语言。
+它用于访问列表的第一个元素（头元素）：
+
+{% tabs head-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.head // 1
+names.head // adam
+```
+{% endtab %}
+{% endtabs %}
+
+因为 `String` 可以看作是一个字符序列，所以你也可以把它当作一个列表。
+这就是 `head` 在这些字符串上的工作方式：
+
+{% tabs string-head-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+"foo".head // 'f'
+"bar".head // 'b'
+```
+{% endtab %}
+{% endtabs %}
+
+`head` 是一个很好的方法，但需要注意的是，在空集合上调用它时也会抛出异常：
+
+{% tabs head-error-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val emptyList = List[Int]() // emptyList: List[Int] = List()
+emptyList.head // java.util.NoSuchElementException: head of empty list
+```
+{% endtab %}
+{% endtabs %}
+
+因此，您可能希望使用 `headOption` 而不是 `head`，尤其是在以函数式编程时：
+
+{% tabs head-option-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+emptyList.headOption // None
+```
+{% endtab %}
+{% endtabs %}
+
+如图所示，它不会抛出异常，它只是返回值为 `None` 的类型 `Option`。
+您可以在 [函数式编程][fp-intro] 章节中了解有关这种编程风格的更多信息。
+
+## `tail`
+
+`tail` 方法也来自 Lisp，它用于打印列表头元素之后的每个元素。
+几个例子展示了这一点：
+
+{% tabs tail-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.head // 1
+oneToTen.tail // List(2, 3, 4, 5, 6, 7, 8, 9, 10)
+
+names.head // adam
+names.tail // List(brandy, chris, david)
+```
+{% endtab %}
+{% endtabs %}
+
+就像 `head` 一样，`tail` 也适用于字符串：
+
+{% tabs string-tail-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+"foo".tail // "oo"
+"bar".tail // "ar"
+```
+{% endtab %}
+{% endtabs %}
+
+如果列表为空，`tail` 会抛出 _java.lang.UnsupportedOperationException_，所以就像 `head` 和 `headOption` 一样，还有一个 `tailOption` 方法，这是函数式编程的首选方法。
+
+也可以匹配一个列表，因此您可以编写如下表达式：
+
+{% tabs tail-match-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val x :: xs = names
+```
+{% endtab %}
+{% endtabs %}
+
+将该代码放在 REPL 中显示 `x` 分配给列表的头部，而 `xs` 分配给列表尾部：
+
+{% tabs tail-match-example-repl %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val x :: xs = names
+val x: String = adam
+val xs: List[String] = List(brandy, chris, david)
+```
+{% endtab %}
+{% endtabs %}
+
+像这样的模式匹配在许多情况下都很有用，例如使用递归编写一个 `sum` 方法：
+
+{% tabs tail-match-sum-example class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def sum(list: List[Int]): Int = list match {
+ case Nil => 0
+ case x :: xs => x + sum(xs)
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def sum(list: List[Int]): Int = list match
+ case Nil => 0
+ case x :: xs => x + sum(xs)
+```
+{% endtab %}
+{% endtabs %}
+
+## `take`、`takeRight`、`takeWhile`
+
+`take`、`takeRight` 和 `takeWhile` 方法为您提供了一种从列表中“获取”要用于创建新列表的元素的好方法。
+这是 `take` 和 `takeRight`：
+
+{% tabs take-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.take(1) // List(1)
+oneToTen.take(2) // List(1, 2)
+
+oneToTen.takeRight(1) // List(10)
+oneToTen.takeRight(2) // List(9, 10)
+```
+{% endtab %}
+{% endtabs %}
+
+注意这些方法是如何处理“临界”情况的，当我们要求比序列中更多的元素，或者要求零元素的时候：
+
+{% tabs take-edge-cases-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.take(Int.MaxValue) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+oneToTen.takeRight(Int.MaxValue) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+oneToTen.take(0) // List()
+oneToTen.takeRight(0) // List()
+```
+{% endtab %}
+{% endtabs %}
+
+这是`takeWhile`，它与谓词函数一起使用：
+
+{% tabs take-while-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.takeWhile(_ < 5) // List(1, 2, 3, 4)
+names.takeWhile(_.length < 5) // List(adam)
+```
+{% endtab %}
+{% endtabs %}
+
+## `drop`、`dropRight`、`dropWhile`
+
+`drop`、`dropRight` 和 `dropWhile` 本质上与它们对应的“取”相反，从列表中删除元素。
+这里有些例子：
+
+{% tabs drop-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.drop(1) // List(2, 3, 4, 5, 6, 7, 8, 9, 10)
+oneToTen.drop(5) // List(6, 7, 8, 9, 10)
+
+oneToTen.dropRight(8) // List(1, 2)
+oneToTen.dropRight(7) // List(1, 2, 3)
+```
+{% endtab %}
+{% endtabs %}
+
+再次注意这些方法如何处理临界情况：
+
+{% tabs drop-edge-cases-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.drop(Int.MaxValue) // List()
+oneToTen.dropRight(Int.MaxValue) // List()
+oneToTen.drop(0) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+oneToTen.dropRight(0) // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+```
+{% endtab %}
+{% endtabs %}
+
+这是 `dropWhile`，它与谓词函数一起使用：
+
+{% tabs drop-while-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+oneToTen.dropWhile(_ < 5) // List(5, 6, 7, 8, 9, 10)
+names.dropWhile(_ != "chris") // List(chris, david)
+```
+{% endtab %}
+{% endtabs %}
+
+## `reduce`
+
+当您听到 “map reduce” 术语时，“reduce” 部分指的是诸如 `reduce` 之类的方法。
+它接受一个函数（或匿名函数）并将该函数应用于列表中的连续元素。
+
+解释 `reduce` 的最好方法是创建一个可以传递给它的小辅助方法。
+例如，这是一个将两个整数相加的 `add` 方法，还为我们提供了一些不错的调试输出：
+
+{% tabs reduce-example class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def add(x: Int, y: Int): Int = {
+ val theSum = x + y
+ println(s"received $x and $y, their sum is $theSum")
+ theSum
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def add(x: Int, y: Int): Int =
+ val theSum = x + y
+ println(s"received $x and $y, their sum is $theSum")
+ theSum
+```
+{% endtab %}
+{% endtabs %}
+
+有上面的方法和下面的列表：
+
+{% tabs reduce-example-init %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = List(1,2,3,4)
+```
+{% endtab %}
+{% endtabs %}
+
+这就是将 `add` 方法传递给 `reduce` 时发生的情况：
+
+{% tabs reduce-example-evaluation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> a.reduce(add)
+received 1 and 2, their sum is 3
+received 3 and 3, their sum is 6
+received 6 and 4, their sum is 10
+res0: Int = 10
+```
+{% endtab %}
+{% endtabs %}
+
+如该结果所示，`reduce` 使用`add` 将列表 `a` 归约为单个值，在这种情况下，是列表中整数的总和。
+
+一旦你习惯了 `reduce`，你会写一个像这样的“求和”算法：
+
+{% tabs reduce-example-sum %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> a.reduce(_ + _)
+res0: Int = 10
+```
+{% endtab %}
+{% endtabs %}
+
+类似地，“连乘”算法如下所示：
+
+{% tabs reduce-example-multiply %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> a.reduce(_ * _)
+res1: Int = 24
+```
+{% endtab %}
+{% endtabs %}
+
+> 关于 `reduce` 的一个重要概念是——顾名思义——它用于将集合_归约_为单个值。
+
+## 更多
+
+在 Scala 集合类型上确实有几十个额外的方法，可以让你不再需要编写另一个 `for` 循环。有关 Scala 集合的更多详细信息，请参阅[可变和不可变集合][mut-immut-colls]和[Scala集合的架构][architecture]。
+
+> 最后一点，如果您在 Scala 项目中使用 Java 代码，您可以将 Java 集合转换为 Scala 集合。
+> 通过这样做，您可以在 `for` 表达式中使用这些集合，还可以利用 Scala 的函数式集合方法。
+> 请参阅 [与 Java 交互][interacting] 部分了解更多详细信息。
+
+[interacting]: {% link _zh-cn/overviews/scala3-book/interacting-with-java.md %}
+[lambdas]: {% link _zh-cn/overviews/scala3-book/fun-anonymous-functions.md %}
+[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %}
+[mut-immut-colls]: {% link _overviews/collections-2.13/overview.md %}
+[architecture]: {% link _overviews/core/architecture-of-scala-213-collections.md %}
+
diff --git a/_zh-cn/overviews/scala3-book/collections-summary.md b/_zh-cn/overviews/scala3-book/collections-summary.md
new file mode 100644
index 0000000000..8a0c958712
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/collections-summary.md
@@ -0,0 +1,37 @@
+---
+title: 总结
+type: section
+description: This page provides a summary of the Collections chapter.
+language: zh-cn
+num: 40
+previous-page: collections-methods
+next-page: fp-intro
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本章总结了常见的 Scala 3 集合及其附带的方法。
+如图所示，Scala 带有丰富的集合和方法。
+
+当您需要查看本章中显示的集合类型的更多详细信息时，请参阅他们的 Scaladoc 页面：
+
+- [List](https://www.scala-lang.org/api/current/scala/collection/immutable/List.html)
+- [Vector](https://www.scala-lang.org/api/current/scala/collection/immutable/Vector.html)
+- [ArrayBuffer](https://www.scala-lang.org/api/current/scala/collection/mutable/ArrayBuffer.html)
+- [Range](https://www.scala-lang.org/api/current/scala/collection/immutable/Range.html)
+
+也提到了不可变的 `Map` 和 `Set`:
+
+- [Map](https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html)
+- [Set](https://www.scala-lang.org/api/current/scala/collection/immutable/Set.html)
+
+和可变的 `Map` 和 `Set`:
+
+- [Map](https://www.scala-lang.org/api/current/scala/collection/mutable/Map.html)
+- [Set](https://www.scala-lang.org/api/current/scala/collection/mutable/Set.html)
+
+
diff --git a/_zh-cn/overviews/scala3-book/concurrency.md b/_zh-cn/overviews/scala3-book/concurrency.md
new file mode 100644
index 0000000000..169e1f1684
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/concurrency.md
@@ -0,0 +1,315 @@
+---
+title: 并发
+type: chapter
+description: This page discusses how Scala concurrency works, with an emphasis on Scala Futures.
+language: zh-cn
+num: 68
+previous-page: ca-summary
+next-page: scala-tools
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+当您想在 Scala 中编写并行和并发应用程序时，您_可以_使用原生 Java `Thread` --- 但 Scala [Future](https://www.scala-lang.org/api/current/scala/concurrent/Future$.html) 提供了一种更高级和惯用的方法，因此它是首选，本章将对此进行介绍。
+
+## 介绍
+
+以下是 Scaladoc 中对 Scala `Future` 的描述：
+
+> “ `Future` 代表一个值，它可能_当前_可用或不可用，但在某个时候可用，或者如果该值不能可用，则表示为异常。”
+
+为了演示这意味着什么，让我们首先看一下单线程编程。
+在单线程世界中，您将方法调用的结果绑定到如下变量：
+
+```scala
+def aShortRunningTask(): Int = 42
+val x = aShortRunningTask()
+```
+
+在此代码中，值 `42` 立即绑定到 `x`。
+
+当您使用 `Future` 时，分配过程看起来很相似：
+
+```scala
+def aLongRunningTask(): Future[Int] = ???
+val x = aLongRunningTask()
+```
+
+但在这种情况下的主要区别在于，因为 `aLongRunningTask` 需要不确定的时间才能返回，所以 `x` 中的值可能_当前_可用也可能不可用，但它会在某个时候可用——在未来.
+
+另一种看待这个问题的方法是阻塞。
+在这个单线程示例中，在 `aShortRunningTask` 完成之前不会打印 `println` 语句：
+
+```scala
+def aShortRunningTask(): Int =
+ Thread.sleep(500)
+ 42
+val x = aShortRunningTask()
+println("Here")
+```
+
+相反，如果 `aShortRunningTask` 被创建为 `Future`，`println` 语句几乎立即被打印，因为 `aShortRunningTask` 是在其他线程上产生的——它不会阻塞。
+
+在本章中，您将看到如何使用 futures，包括如何并行运行多个 future 并将它们的结果组合到一个 `for` 表达式中。
+您还将看到一些例子，在这些例子中，有些方法用于处理在返回的 future 中的值。
+
+> 当你考虑 future 时，重要的是要知道它们是一次性的，“在其他线程上处理这个相对较慢的计算，完成后给把结果通知我”的结构。
+> 作为对比，[Akka](https://akka.io) Actor 旨在运行很长时间，并在其生命周期内响应许多请求。
+> 虽然 actor可能永远活着，但 future 最终会包含只运行一次的计算结果。
+
+## REPL 中的一个例子
+
+future 用于创建一个临时的并发包。
+例如，当您需要调用运行不确定时间的算法时---例如调用远程微服务---您使用 future---因此您希望在主线程之外运行它。
+
+为了演示它是如何工作的，让我们从 REPL 中的 `Future` 示例开始。
+首先，粘贴这些必需的 `import` 语句：
+
+```scala
+import scala.concurrent.Future
+import scala.concurrent.ExecutionContext.Implicits.global
+import scala.util.{Failure, Success}
+```
+
+现在您已准备好创造 future 。
+对于这个例子，首先定义一个长时间运行的单线程算法：
+
+```scala
+def longRunningAlgorithm() =
+ Thread.sleep(10_000)
+ 42
+```
+
+这种奇特的算法在十秒延迟后返回整数值`42`。
+现在通过将其包装到 `Future` 构造函数中来调用该算法，并将结果分配给一个变量：
+
+```scala
+scala> val eventualInt = Future(longRunningAlgorithm())
+eventualInt: scala.concurrent.Future[Int] = Future()
+```
+
+马上，您的计算——对 `longRunningAlgorithm()` 的调用——开始运行。
+如果你立即检查变量 `eventualInt` 的值，你会看到 future 还没有完成：
+
+```scala
+scala> eventualInt
+val res1: scala.concurrent.Future[Int] = Future()
+```
+
+但是如果你在十秒后再次检查，你会看到它已经成功完成了：
+
+```scala
+scala> eventualInt
+val res2: scala.concurrent.Future[Int] = Future(Success(42))
+```
+
+虽然这是一个相对简单的示例，但它显示了基本方法：只需使用您的长时间运行的算法构建一个新的 `Future`。
+
+需要注意的一点是，您期望的 `42` 被包裹在 `Success` 中，而后者又被包裹在 `Future` 中。
+这是一个需要理解的关键概念：`Future` 中的值始终是`scala.util.Try` 类型之一的实例：`Success` 或 `Failure`。
+因此，当您处理 future 的结果时，您使用通常的 `Try` 处理技术。
+
+### 将 `map` 与 future 一起使用
+
+`Future` 有一个 `map` 方法，你可以像使用集合中的 `map` 方法一样使用它。
+这是在创建变量 `f` 后立即调用 `map` 时的结果：
+
+```scala
+scala> val a = eventualInt.map(_ * 2)
+a: scala.concurrent.Future[Int] = Future()
+```
+
+如图所示，对于使用 `longRunningAlgorithm` 创建的 future ，初始输出显示 `Future()`。
+但是当你在十秒后检查 `a` 的值时，你会看到它包含 `84` 的预期结果：
+
+```scala
+scala> a
+res1: scala.concurrent.Future[Int] = Future(Success(84))
+```
+
+再一次，成功的结果被包裹在 `Success` 和 `Future` 中。
+
+### 在 future 中使用回调方法
+
+除了像`map`这样的高阶函数，你还可以使用回调方法和futures。
+一种常用的回调方法是 `onComplete`，它采用*偏函数*，您可以在其中处理 `Success` 和 `Failure` 情况：
+
+```scala
+eventualInt.onComplete {
+ case Success(value) => println(s"Got the callback，value = $value")
+ case Failure(e) => e.printStackTrace
+}
+```
+
+当您将该代码粘贴到 REPL 中时，您最终会看到结果：
+
+```scala
+Got the callback, value = 42
+```
+
+## 其他 future 方法
+
+`Future` 类还有其他可以使用的方法。
+它具有您在 Scala 集合类中找到的一些方法，包括：
+
+- `filter`
+- `flatMap`
+- `map`
+
+它的回调方法有：
+
+- `onComplete`
+- `andThen`
+- `foreach`
+
+其他转换方法包括：
+
+- `fallbackTo`
+- `recover`
+- `recoverWith`
+
+请参阅 [Futures and Promises][futures] 页面，了解有关 future 可用的其他方法的讨论。
+
+## 运行多个 future 并加入他们的结果
+
+要并行运行多个计算并在所有 future 完成后加入它们的结果，请使用 “for” 表达式。
+
+正确的做法是：
+
+1. 开始计算返回 `Future` 结果
+2. 将他们的结果合并到一个 `for` 表达式中
+3. 使用 `onComplete` 或类似技术提取合并结果
+
+### 一个例子
+
+以下示例显示了正确方法的三个步骤。
+一个关键是你首先开始计算返回 future ，然后将它们加入到 `for` 表达式中：
+
+```scala
+import scala.concurrent.Future
+import scala.concurrent.ExecutionContext.Implicits.global
+import scala.util.{Failure, Success}
+
+val startTime = System.currentTimeMillis()
+def delta() = System.currentTimeMillis() - startTime
+def sleep(millis: Long) = Thread.sleep(millis)
+
+@main def multipleFutures1 =
+
+ println(s"creating the futures: ${delta()}")
+
+ // (1) start the computations that return futures
+ val f1 = Future { sleep(800); 1 } // eventually returns 1
+ val f2 = Future { sleep(200); 2 } // eventually returns 2
+ val f3 = Future { sleep(400); 3 } // eventually returns 3
+
+ // (2) join the futures in a `for` expression
+ val result =
+ for
+ r1 <- f1
+ r2 <- f2
+ r3 <- f3
+ yield
+ println(s"in the 'yield': ${delta()}")
+ (r1 + r2 + r3)
+
+ // (3) process the result
+ result.onComplete {
+ case Success(x) =>
+ println(s"in the Success case: ${delta()}")
+ println(s"result = $x")
+ case Failure(e) =>
+ e.printStackTrace
+ }
+
+ println(s"before the 'sleep(3000)': ${delta()}")
+
+ // important for a little parallel demo: keep the jvm alive
+ sleep(3000)
+```
+
+当您运行该应用程序时，您会看到如下所示的输出：
+
+````
+creating the futures: 1
+before the 'sleep(3000)': 2
+in the 'yield': 806
+in the Success case: 806
+result = 6
+````
+
+如该输出所示， future 的创建速度非常快，仅在两毫秒内就到达了方法末尾的 `sleep(3000)` 语句之前的打印语句。
+所有这些代码都在 JVM 的主线程上运行。
+然后，在 806 毫秒，三个 future 完成并运行 `yield` 块中的代码。
+然后代码立即转到 `onComplete` 方法中的 `Success` 分支。
+
+806 毫秒的输出是看到三个计算并行运行的关键。
+如果它们按顺序运行，总时间约为 1,400 毫秒——三个计算的睡眠时间之和。
+但是因为它们是并行运行的，所以总时间只比运行时间最长的计算：`f1`，即 800 毫秒，稍长。
+
+> 请注意，如果计算是在 `for` 表达式中运行的，它们
+> 将按顺序执行，而不是并行执行：
+> ~~~
+> // Sequential execution (no parallelism!)
+> for
+> r1 <- Future { sleep(800); 1 }
+> r2 <- Future { sleep(200); 2 }
+> r3 <- Future { sleep(400); 3 }
+> yield
+> r1 + r2 + r3
+> ~~~
+> 因此，如果您希望计算可能并行运行，请记住
+> 在 `for` 表达式之外运行它们。
+
+### 一个返回 future 的方法
+
+到目前为止，您已经了解了如何将单线程算法传递给 `Future` 构造函数。
+您可以使用相同的技术来创建一个返回 `Future` 的方法：
+
+```scala
+// simulate a slow-running method
+def slowlyDouble(x: Int, delay: Long): Future[Int] = Future {
+ sleep(delay)
+ x * 2
+}
+```
+
+与前面的示例一样，只需将方法调用的结果分配给一个新变量。
+然后当你立刻检查结果时，你会看到它没有完成，但是在延迟时间之后，future 会有一个结果：
+
+````
+scala> val f = slowlyDouble(2, 5_000L)
+val f: concurrent.Future[Int] = Future()
+
+scala> f
+val res0: concurrent.Future[Int] = Future()
+
+scala> f
+val res1: concurrent.Future[Int] = Future(Success(4))
+````
+
+## 关于 future 的要点
+
+希望这些示例能让您了解 Scala future 是如何工作的。
+总而言之，关于 future 的几个关键点是：
+
+- 您构建 future 以在主线程之外运行任务
+- Futures 用于一次性的、可能长时间运行的并发任务，这些任务*最终*返回一个值；他们创造了一个临时的并发的容器
+- 一旦你构建了 future，它就会开始运行
+- future 相对于线程的一个好处是它们可以使用 `for` 表达式，并带有各种回调方法，可以简化使用并发线程的过程
+- 当您使用 future 时，您不必关心线程管理的低级细节
+- 您可以使用 `onComplete` 和 `andThen` 之类的回调方法或 `filter`、`map` 等转换方法来处理 future 的结果。
+- `Future` 中的值始终是 `Try` 类型之一的实例：`Success` 或 `Failure`
+- 如果您使用多个 future 来产生一个结果，请将它们组合在一个 `for` 表达式中
+
+此外，正如您在这些示例中看到的 `import` 语句，Scala `Future` 依赖于 `ExecutionContext`。
+
+有关 future 的更多详细信息，请参阅[Future 和 Promises][future]，这是一篇讨论 future 、promises 和 ExecutionContext 的文章。
+它还讨论了如何将 `for` 表达式转换为 `flatMap` 操作。
+
+
+[futures]: {% link _overviews/core/futures.md %}
diff --git a/_zh-cn/overviews/scala3-book/control-structures.md b/_zh-cn/overviews/scala3-book/control-structures.md
new file mode 100644
index 0000000000..fa46f25a2c
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/control-structures.md
@@ -0,0 +1,1120 @@
+---
+title: 控制结构
+type: chapter
+description: This page provides an introduction to Scala's control structures, including if/then/else, 'for' loops, 'for' expressions, 'match' expressions, try/catch/finally, and 'while' loops.
+language: zh-cn
+num: 19
+previous-page: string-interpolation
+next-page: domain-modeling-intro
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala具有您希望在编程语言中找到的控制结构，包括：
+
+- `if`/`then`/`else`
+- `for` 循环
+- `while` 循环
+- `try`/`catch`/`finally`
+
+它还具有另外两个您可能以前从未见过的强大结构，具体取决于您的编程背景：
+
+- `for` 表达式（也被称作 _`for` comprehensions_）
+- `match` 表达式
+
+这些都将在以下各节中进行演示。
+
+## if/then/else 结构
+
+单行 Scala `if` 语句像这样：
+
+{% tabs control-structures-1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=control-structures-1 %}
+
+```scala
+if (x == 1) println(x)
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=control-structures-1 %}
+
+```scala
+if x == 1 then println(x)
+```
+
+{% endtab %}
+{% endtabs %}
+
+如果要在 `if` 比较后运行多行代码，用这个语法：
+
+{% tabs control-structures-2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=control-structures-2 %}
+
+```scala
+if (x == 1) {
+ println("x is 1, as you can see:")
+ println(x)
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=control-structures-2 %}
+
+```scala
+if x == 1 then
+ println("x is 1, as you can see:")
+ println(x)
+```
+
+{% endtab %}
+{% endtabs %}
+
+`if`/`else` 语法像这样：
+
+{% tabs control-structures-3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=control-structures-3 %}
+
+```scala
+if (x == 1) {
+ println("x is 1, as you can see:")
+ println(x)
+} else {
+ println("x was not 1")
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=control-structures-3 %}
+
+```scala
+if x == 1 then
+ println("x is 1, as you can see:")
+ println(x)
+else
+ println("x was not 1")
+```
+
+{% endtab %}
+{% endtabs %}
+
+这是 `if`/`else if`/`else` 语法：
+
+{% tabs control-structures-4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=control-structures-4 %}
+
+```scala
+if (x < 0)
+ println("negative")
+else if (x == 0)
+ println("zero")
+else
+ println("positive")
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=control-structures-4 %}
+
+```scala
+if x < 0 then
+ println("negative")
+else if x == 0 then
+ println("zero")
+else
+ println("positive")
+```
+
+{% endtab %}
+{% endtabs %}
+
+### `end if` 语句
+
+
+
+## Scala 类型层次结构
+
+`Any` 是所有类型的超类型，也称为 **首类型**。
+它定义了某些通用方法，例如 `equals` ， `hashCode` 和 `toString` 。
+
+首类型 `Any` 有一个子类型 [`Matchable`][matchable]，它用于标记可以执行模式匹配的所有类型。
+保证属性调用 _“参数化”_ 非常重要。
+我们不会在这里详细介绍，但总而言之，这意味着我们不能对类型为 `Any` 的值进行模式匹配，而只能对 `Matchable` 的子类型的值进行模式匹配。
+[参考文档][matchable]包含有关 `Matchable` 的更多信息。
+
+`Matchable` 有两个重要的子类型： `AnyVal` 和 `AnyRef` 。
+
+*`AnyVal`* 表示值类型。
+有几个预定义的值类型，它们是不可为空的： `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit`, 和 `Boolean`。
+`Unit` 是一种值类型，它不携带有意义的信息。
+`Unit` 只有一个实例，我们可以将其称为：`()`。
+
+*`AnyRef`* 表示引用类型。
+所有非值类型都定义为引用类型。
+Scala中的每个用户定义类型都是 `AnyRef` 的子类型。
+如果在Java运行时环境的上下文中使用Scala，则 `AnyRef` 对应于 `java.lang.Object`。
+
+在基于语句的编程语言中， `void` 用于没有返回值的方法。
+如果您在Scala中编写没有返回值的方法，例如以下方法，则 `Unit` 用于相同的目的：
+
+{% tabs unit %}
+{% tab 'Scala 2 and 3' for=unit %}
+
+```scala
+def printIt(a: Any): Unit = println(a)
+```
+
+{% endtab %}
+{% endtabs %}
+
+下面是一个示例，它演示了字符串、整数、字符、布尔值和函数都是 `Any` 的实例，可以像对待其他所有对象一样处理：
+
+{% tabs any %}
+{% tab 'Scala 2 and 3' for=any %}
+
+```scala
+val list: List[Any] = List(
+ "a string",
+ 732, // an integer
+ 'c', // a character
+ true, // a boolean value
+ () => "an anonymous function returning a string"
+)
+
+list.foreach(element => println(element))
+```
+
+{% endtab %}
+{% endtabs %}
+
+该代码定义了一个类型为 `List[Any]` 的值 `list` 。
+该列表使用各种类型的元素进行初始化，但每个元素都是 `scala.Any` 的实例，因此我们可以将它们添加到列表中。
+
+下面是程序的输出：
+
+```
+a string
+732
+c
+true
+
+```
+
+## Scala的“值类型”
+
+如上所示，Scala的值类型扩展了 `AnyVal`，它们都是成熟的对象。
+这些示例演示如何声明以下数值类型的变量：
+
+{% tabs anyval %}
+{% tab 'Scala 2 and 3' for=anyval %}
+
+```scala
+val b: Byte = 1
+val i: Int = 1
+val l: Long = 1
+val s: Short = 1
+val d: Double = 2.0
+val f: Float = 3.0
+```
+
+{% endtab %}
+{% endtabs %}
+
+在前四个示例中，如果未显式指定类型，则数字 `1` 将默认为 `Int` ，因此，如果需要其他数据类型之一 --- `Byte` 、`Long` 或 `Short` --- 则需要显式声明这些类型，如上面代码所示。
+带有小数的数字（如2.0）将默认为 `Double` ，因此，如果您想要 `Float` ，则需要声明 `Float` ，如上一个示例所示。
+
+由于 `Int` 和 `Double` 是默认数值类型，因此通常在不显式声明数据类型的情况下创建它们：
+
+{% tabs anynum %}
+{% tab 'Scala 2 and 3' for=anynum %}
+
+```scala
+val i = 123 // defaults to Int
+val x = 1.0 // defaults to Double
+```
+
+{% endtab %}
+{% endtabs %}
+
+在代码中，您还可以将字符 `L` 、 `D` 和 `F` （及其小写等效项）加到数字末尾，以指定它们是 `Long`, `Double`, 或 `Float` 值：
+
+{% tabs type-post %}
+{% tab 'Scala 2 and 3' for=type-post %}
+
+```scala
+val x = 1_000L // val x: Long = 1000
+val y = 2.2D // val y: Double = 2.2
+val z = 3.3F // val z: Float = 3.3
+```
+
+{% endtab %}
+{% endtabs %}
+
+Scala还具有 `String` 和 `Char` 类型，通常可以使用隐式形式声明：
+
+{% tabs type-string %}
+{% tab 'Scala 2 and 3' for=type-string %}
+
+```scala
+val s = "Bill"
+val c = 'a'
+```
+
+{% endtab %}
+{% endtabs %}
+
+如下面表格所示，将字符串括在双引号中 --- 或多行字符串括在三引号中 --- 或字符括在单引号中。
+
+这些数据类型及其范围包括：
+
+| 数据类型 | 可能的值 |
+| ---------- | --------------- |
+| Boolean | `true` 或 `false` |
+| Byte | 8 位有符号二进制补码整数（-2^7 至 2^7-1,含）
-128 至 127 | +| Short | 16 位有符号二进制补码整数（-2^15 至 2^15-1,含）
-32,768 至 32,767 | +| Int | 32 位二进制补码整数（-2^31 至 2^31-1,含）
-2,147,483,648 至 2,147,483,647 | +| Long | 64 位 2 的补码整数（-2^63 到 2^63-1,含）
（-2^63 到 2^63-1,包括） | +| Float | 32 位 IEEE 754 单精度浮点数
1.40129846432481707e-45 到 3.40282346638528860e+38 | +| Double | 64 位 IEEE 754 双精度浮点数
4.94065645841246544e-324 到 1.79769313486231570e+308 | +| Char | 16 位无符号 Unicode 字符（0 到 2^16-1,含）
0 到 65,535 | +| String | 一个 `Char` 序列 | + +## `BigInt` 和 `BigDecimal` + +当您需要非常大的数字时，请使用 `BigInt` 和 `BigDecimal` 类型： + +{% tabs type-bigint %} +{% tab 'Scala 2 and 3' for=type-bigint %} + +```scala +val a = BigInt(1_234_567_890_987_654_321L) +val b = BigDecimal(123_456.789) +``` + +{% endtab %} +{% endtabs %} + +其中 `Double` 和 `Float` 是近似的十进制数， `BigDecimal` 用于精确算术，例如在使用货币时。 + +`BigInt` 和 `BigDecimal` 的一个好处是，它们支持您习惯于用于数字类型的所有运算符： + +{% tabs type-bigint2 %} +{% tab 'Scala 2 and 3' for=type-bigint2 %} + +```scala +val b = BigInt(1234567890) // scala.math.BigInt = 1234567890 +val c = b + b // scala.math.BigInt = 2469135780 +val d = b * b // scala.math.BigInt = 1524157875019052100 +``` + +{% endtab %} +{% endtabs %} + +## 关于字符串的两个注释 + +Scala字符串类似于Java字符串，但它们有两个很棒的附加特性： + +- 它们支持字符串插值 +- 创建多行字符串很容易 + +### 字符串插值 + +字符串插值提供了一种非常可读的方式在字符串中使用变量。 +例如，给定以下三个变量： + +{% tabs string-inside1 %} +{% tab 'Scala 2 and 3' for=string-inside1 %} + +```scala +val firstName = "John" +val mi = 'C' +val lastName = "Doe" +``` + +{% endtab %} +{% endtabs %} + +你可以把那些变量组合成这样的字符串： + +{% tabs string-inside2 %} +{% tab 'Scala 2 and 3' for=string-inside2 %} + +```scala +println(s"Name: $firstName $mi $lastName") // "Name: John C Doe" +``` + +{% endtab %} +{% endtabs %} + +只需在字符串前面加上字母 `s` ，然后在字符串内的变量名称之前放置一个 `$` 符号。 + +如果要在字符串中使用可能较大的表达式时，请将它们放在大括号中： + +{% tabs string-inside3 %} +{% tab 'Scala 2 and 3' for=string-inside3 %} + +```scala +println(s"2 + 2 = ${2 + 2}") // prints "2 + 2 = 4" +val x = -1 +println(s"x.abs = ${x.abs}") // prints "x.abs = 1" +``` + +{% endtab %} +{% endtabs %} + +#### 其他插值器 + +放置在字符串前面的 `s` 只是一个可能的插值器。 +如果使用 `f` 而不是 `s` ，则可以在字符串中使用 `printf` 样式的格式语法。 +此外，字符串插值器只是一种特殊方法，可以定义自己的方法。 +例如，一些数据库库定义了非常强大的 `sql` 插值器。 + +### 多行字符串 + +多行字符串是通过将字符串包含在三个双引号内来创建的： + +{% tabs string-mlines1 %} +{% tab 'Scala 2 and 3' for=string-mlines1 %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` + +{% endtab %} +{% endtabs %} + +这种基本方法的一个缺点是，第一行之后的行是缩进的，如下所示： + +{% tabs string-mlines2 %} +{% tab 'Scala 2 and 3' for=string-mlines2 %} + +```scala +"The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +当间距很重要时，在第一行之后的所有行前面放一个 `|` 符号，并在字符串之后调用 `stripMargin` 方法： + +{% tabs string-mlines3 %} +{% tab 'Scala 2 and 3' for=string-mlines3 %} + +```scala +val quote = """The essence of Scala: + |Fusion of functional and object-oriented + |programming in a typed setting.""".stripMargin +``` + +{% endtab %} +{% endtabs %} + +现在字符串里所有行都是左对齐了： + +{% tabs string-mlines4 %} +{% tab 'Scala 2 and 3' for=string-mlines4 %} + +```scala +"The essence of Scala: +Fusion of functional and object-oriented +programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +## 类型转换 + +可以通过以下方式强制转换值类型： + +
+
+例如：
+
+{% tabs cast1 %}
+{% tab 'Scala 2 and 3' for=cast1 %}
+
+```scala
+val b: Byte = 127
+val i: Int = b // 127
+
+val face: Char = '☺'
+val number: Int = face // 9786
+```
+
+{% endtab %}
+{% endtabs %}
+
+只有在没有丢失信息的情况下，才能强制转换为类型。否则，您需要明确说明强制转换：
+
+{% tabs cast2 %}
+{% tab 'Scala 2 and 3' for=cast2 %}
+
+```scala
+val x: Long = 987654321
+val y: Float = x.toFloat // 9.8765434E8 (注意 `.toFloat` 是必须的，因为强制类型转换后的精度会损)
+val z: Long = y // Error
+```
+
+{% endtab %}
+{% endtabs %}
+
+还可以将引用类型强制转换为子类型。
+这将在教程的后面部分介绍。
+
+## `Nothing` 和 `null`
+
+`Nothing` 是所有类型的子类型，也称为**底部类型**。
+`Nothing` 类型是没有值的。
+一个常见的用途是发出非终止信号，例如抛出异常，程序退出或无限循环---即，它是不计算为值的那种表达式，或者不正常返回的方法。
+
+`Null` 是所有引用类型的子类型（即 `AnyRef` 的任何子类型）。
+它具有由关键字面量 `null` 标识的单个值。
+目前，使用 `null` 被认为是不好的做法。它应该主要用于与其他JVM语言的互操作性。选择加入编译器选项会更改 `Null` 状态，以修复与其用法相关的警告。此选项可能会成为将来版本的 Scala 中的默认值。你可以在[这里][safe-null]了解更多关于它的信息。
+
+与此同时， `null` 几乎不应该在Scala代码中使用。
+本书的[函数式编程章节][fp]和 [API文档][option-api]中讨论了 `null` 的替代方法。
+
+[reference]: {{ site.scala3ref }}/overview.html
+[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html
+[interpolation]: {% link _overviews/scala3-book/string-interpolation.md %}
+[fp]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %}
+[option-api]: https://scala-lang.org/api/3.x/scala/Option.html
+[safe-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html
diff --git a/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md b/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md
new file mode 100644
index 0000000000..b1cce269af
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md
@@ -0,0 +1,489 @@
+---
+title: 函数式错误处理
+type: section
+description: This section provides an introduction to functional error handling in Scala 3.
+language: zh-cn
+num: 46
+previous-page: fp-functions-are-values
+next-page: fp-summary
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+函数式编程就像写一系列代数方程，因为代数没有空值或抛出异常，所以你不用在 FP 中使用这些特性。
+这带来了一个有趣的问题：在 OOP 代码中通常可能使用空值或异常的情况下，您会怎么做？
+
+Scala 的解决方案是使用类似 `Option`/`Some`/`None` 类的结构。
+本课介绍如何使用这些技术。
+
+在我们开始之前有两个注意事项：
+
+- `Some` 和 `None` 类是 `Option` 的子类。
+- 下面的文字一般只指“`Option`”或“`Option`类”，而不是重复说“`Option`/`Some`/`None`”。
+
+## 第一个例子
+
+虽然第一个示例不处理空值，但它是引入 `Option` 类的好方法，所以我们将从它开始。
+
+想象一下，您想编写一个方法，可以轻松地将字符串转换为整数值，并且您想要一种优雅的方法来处理异常，这个是异常是该方法获取类似“Hello”而不是“1”的字符串时引发的。
+对这种方法的初步猜测可能如下所示：
+
+{% tabs fp-java-try class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def makeInt(s: String): Int =
+ try {
+ Integer.parseInt(s.trim)
+ } catch {
+ case e: Exception => 0
+ }
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def makeInt(s: String): Int =
+ try
+ Integer.parseInt(s.trim)
+ catch
+ case e: Exception => 0
+```
+{% endtab %}
+{% endtabs %}
+
+如果转换成功，则此方法返回正确的 `Int` 值，但如果失败，则该方法返回 `0`。
+出于某些目的，这可能是可以的，但它并不准确。
+例如，该方法可能收到了`"0"`，但它也可能收到了 `"foo"`、`"bar"` 或无数其他将引发异常的字符串。
+这是一个真正的问题：您如何知道该方法何时真正收到 `"0"`，或者何时收到其他内容？
+答案是，用这种方法，没有办法知道。
+
+## 使用 Option/Some/None
+
+Scala 中这个问题的一个常见解决方案是使用三个类，称为 `Option`、`Some` 和 `None` 。
+`Some` 和 `None` 类是 `Option` 的子类，因此解决方案的工作原理如下：
+
+- 你声明 `makeInt` 返回一个 `Option` 类型
+- 如果 `makeInt` 接收到一个字符串，它*可以* 转换为 `Int`，答案将包含在 `Some` 中
+- 如果 `makeInt` 接收到一个它*无法*转换的字符串，它返回一个 `None`
+
+这是 `makeInt` 的修订版：
+
+{% tabs fp--try-option class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def makeInt(s: String): Option[Int] =
+ try {
+ Some(Integer.parseInt(s.trim))
+ } catch {
+ case e: Exception => None
+ }
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def makeInt(s: String): Option[Int] =
+ try
+ Some(Integer.parseInt(s.trim))
+ catch
+ case e: Exception => None
+```
+{% endtab %}
+{% endtabs %}
+
+这段代码可以理解为，“当给定的字符串转换为整数时，返回包裹在 `Some` 中的 `Int`，例如 `Some(1)`。
+当字符串无法转换为整数时，会抛出并捕获异常，并且该方法返回一个 `None` 值。”
+
+这些示例展示了 `makeInt` 的工作原理：
+
+{% tabs fp-try-option-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = makeInt("1") // Some(1)
+val b = makeInt("one") // None
+```
+{% endtab %}
+{% endtabs %}
+
+如图所示，字符串`"1"`产生一个 `Some(1)`，而字符串 `"one"` 产生一个 `None`。
+这是错误处理的 `Option` 方法的本质。
+如图所示，使用了这种技术，因此方法可以返回 *值* 而不是 *异常*。
+在其他情况下，`Option` 值也用于替换 `null` 值。
+
+两个注意事项：
+
+- 你会发现这种方法在整个 Scala 库类和第三方 Scala 库中使用。
+- 这个例子的一个关键点是函数式方法不会抛出异常；相反，它们返回类似 `Option` 的值。
+
+## 成为 makeInt 的消费者
+
+现在假设您是 `makeInt` 方法的使用者。
+你知道它返回一个 `Option[Int]` 的子类，所以问题就变成了，你如何处理这些返回类型？
+
+根据您的需要，有两个常见的答案：
+
+- 使用 `match` 表达式
+- 使用 `for` 表达式
+
+## 使用 `match` 表达式
+
+一种可能的解决方案是使用 `match` 表达式：
+
+{% tabs fp-option-match class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+makeInt(x) match {
+ case Some(i) => println(i)
+ case None => println("That didn’t work.")
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+makeInt(x) match
+ case Some(i) => println(i)
+ case None => println("That didn’t work.")
+```
+{% endtab %}
+{% endtabs %}
+
+在本例中，如果 `x` 可以转换为 `Int`，则计算第一个 `case` 子句右侧的表达式；如果 `x` 不能转换为 `Int`，则计算第二个 `case` 子句右侧的表达式。
+
+## 使用 `for` 表达式
+
+另一种常见的解决方案是使用 `for` 表达式，即本书前面显示的 `for`/`yield` 组合。
+例如，假设您要将三个字符串转换为整数值，然后将它们相加。
+这就是你使用 `for` 表达式和 `makeInt` 的方法：
+
+{% tabs fp-for-comprehension class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+{% endtabs %}
+
+在该表达式运行后，`y` 将是以下两种情况之一：
+
+- 如果*所有*三个字符串都转换为 `Int` 值，`y` 将是 `Some[Int]`，即包裹在 `Some` 中的整数
+- 如果三个字符串中*任意一个*字符串不能转换为 `Int`，则 `y` 将是 `None`
+
+你可以自己测试一下：
+
+{% tabs fp-for-comprehension-evaluation class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val stringA = "1"
+val stringB = "2"
+val stringC = "3"
+
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val stringA = "1"
+val stringB = "2"
+val stringC = "3"
+
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+{% endtabs %}
+
+使用该样本数据，变量 `y` 的值将是 `Some(6)` 。
+
+要查看失败案例，请将这些字符串中的任何一个更改为不会转换为整数的字符串。
+当你这样做时，你会看到 `y` 是 `None`：
+
+{% tabs fp-for-comprehension-failure-result %}
+{% tab 'Scala 2 and 3' %}
+```scala
+y: Option[Int] = None
+```
+{% endtab %}
+{% endtabs %}
+
+## 将 Option 视为容器
+
+心智模型通常可以帮助我们理解新情况，因此，如果您不熟悉 `Option` 类，可以将它们视为*容器*：
+
+- `Some` 是一个容器，里面有一个项目
+- `None` 是一个容器，但里面什么都没有
+
+如果您更愿意将 `Option` 类想象成一个盒子，`None` 就像一个空盒子。
+它可能有一些东西，但它没有。
+
+{% comment %}
+NOTE: I commented-out this subsection because it continues to explain Some and None, and I thought it was probably too much for this book.
+
+## Using `foreach` with `Option`
+
+Because `Some` and `None` can be thought of containers, they’re also like collections classes.
+They have many of the methods you’d expect from a collection class, including `map`, `filter`, `foreach`, etc.
+
+This raises an interesting question: What will these two values print, if anything?
+
+{% tabs fp-option-methods-evaluation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+makeInt("1").foreach(println)
+makeInt("x").foreach(println)
+```
+{% endtab %}
+{% endtabs %}
+
+Answer: The first example prints the number `1`, and the second example doesn’t print anything.
+The first example prints `1` because:
+
+- `makeInt("1")` evaluates to `Some(1)`
+- The expression becomes `Some(1).foreach(println)`
+- The `foreach` method on the `Some` class knows how to reach inside the `Some` container and extract the value (`1`) that’s inside it, so it passes that value to `println`
+
+Similarly, the second example prints nothing because:
+
+- `makeInt("x")` evaluates to `None`
+- The `foreach` method on the `None` class knows that `None` doesn’t contain anything, so it does nothing
+
+In this regard, `None` is similar to an empty `List`.
+
+### The happy and unhappy paths
+
+Somewhere in Scala’s history, someone noted that the first example (the `Some`) represents the “Happy Path” of the `Option` approach, and the second example (the `None`) represents the “Unhappy Path.”
+*But* despite having two different possible outcomes, the great thing with `Option` is that there’s really just one path: The code you write to handle the `Some` and `None` possibilities is the same in both cases.
+The `foreach` examples look like this:
+
+{% tabs fp-another-option-method-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+makeInt(aString).foreach(println)
+```
+{% endtab %}
+{% endtabs %}
+
+And the `for` expression looks like this:
+
+{% tabs fp-another-for-comprehension-example class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+{% endtabs %}
+
+With exceptions you have to worry about handling branching logic, but because `makeInt` returns a value, you only have to write one piece of code to handle both the Happy and Unhappy Paths, and that simplifies your code.
+
+Indeed, the only time you have to think about whether the `Option` is a `Some` or a `None` is when you handle the result value, such as in a `match` expression:
+
+{% tabs fp-option-match-handle class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+makeInt(x) match {
+ case Some(i) => println(i)
+ case None => println("That didn't work.")
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+makeInt(x) match
+ case Some(i) => println(i)
+ case None => println("That didn't work.")
+```
+{% endtab %}
+{% endtabs %}
+
+> There are several other ways to handle `Option` values.
+> See the reference documentation for more details.
+{% endcomment %}
+
+## 使用 `Option` 替换 `null`
+
+回到 `null` 值，`null` 值可以悄悄地潜入你的代码的地方是这样的类：
+
+{% tabs fp=case-class-nulls %}
+{% tab 'Scala 2 and 3' %}
+```scala
+class Address(
+ var street1: String,
+ var street2: String,
+ var city: String,
+ var state: String,
+ var zip: String
+)
+```
+{% endtab %}
+{% endtabs %}
+
+虽然地球上的每个地址都有一个 `street1` 值，但 `street2` 值是可选的。
+因此，`street2` 字段可以被分配一个 `null` 值：
+
+{% tabs fp-case-class-nulls-example class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "1 Main Street",
+ null, // <-- D’oh! A null value!
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "1 Main Street",
+ null, // <-- D’oh! A null value!
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+{% endtabs %}
+
+从历史上看，开发人员在这种情况下使用了空白字符串和空值，这两种方法都是使用技巧来解决基础性的问题，这个问题是：`street2` 是一个*可选*字段。
+在 Scala 和其他现代语言中，正确的解决方案是预先声明 `street2` 是可选的：
+
+{% tabs fp-case-class-with-options %}
+{% tab 'Scala 2 and 3' %}
+```scala
+class Address(
+ var street1: String,
+ var street2: Option[String], // an optional value
+ var city: String,
+ var state: String,
+ var zip: String
+)
+```
+{% endtab %}
+{% endtabs %}
+
+现在开发人员可以编写更准确的代码，如下所示：
+
+{% tabs fp-case-class-with-options-example-none class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "1 Main Street",
+ None, // 'street2' has no value
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "1 Main Street",
+ None, // 'street2' has no value
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+{% endtabs %}
+
+或这个：
+
+{% tabs fp-case-class-with-options-example-some class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "123 Main Street",
+ Some("Apt. 2B"),
+ "Talkeetna",
+ "Alaska",
+ "99676"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "123 Main Street",
+ Some("Apt. 2B"),
+ "Talkeetna",
+ "Alaska",
+ "99676"
+)
+```
+{% endtab %}
+{% endtabs %}
+
+## `Option` 不是唯一的解决方案
+
+虽然本节关注的是 `Option` 类，但 Scala 还有一些其他选择。
+
+例如，称为 `Try`/`Success`/`Failure` 的三个类以相同的方式工作，但是 (a) 当您的代码可以抛出异常时，您主要使用这些类，并且 (b) 您想要使用`Failure` 类，因为它使您可以访问异常消息。
+例如，在编写与文件、数据库和 Internet 服务交互的方法时，通常会使用这些 `Try` 类，因为这些函数很容易引发异常。
+
+## 快速回顾
+
+这部分很长，让我们快速回顾一下：
+
+- 函数式程序员不使用 `null` 值
+- `null` 值的主要替代品是使用 `Option` 类
+- 函数式方法不会抛出异常； 相反，它们返回诸如 `Option` 、 `Try` 或 `Either` 之类的值
+- 使用 `Option` 值的常用方法是 `match` 和 `for` 表达式
+- Option 可以被认为是一个项目（`Some`）和没有项目（`None`）的容器
+- option 也可用于可选的构造函数或方法参数
+
diff --git a/_zh-cn/overviews/scala3-book/fp-functions-are-values.md b/_zh-cn/overviews/scala3-book/fp-functions-are-values.md
new file mode 100644
index 0000000000..ab802ed02a
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-functions-are-values.md
@@ -0,0 +1,133 @@
+---
+title: 函数是值
+type: section
+description: This section looks at the use of functions as values in functional programming.
+language: zh-cn
+num: 45
+previous-page: fp-pure-functions
+next-page: fp-functional-error-handling
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+虽然曾经创建的每种编程语言都可能允许您编写纯函数，但 Scala FP 的第二个重要特性是*您可以将函数创建为值*，就像您创建 `String` 和 `Int` 值一样。
+
+这个特性有很多好处，其中最常见的是（a）您可以定义方法来接受函数参数，以及（b）您可以将函数作为参数传递给方法。
+你已经在本书的多个地方看到了这一点，每当演示像 `map` 和 `filter` 这样的方法时：
+
+{% tabs fp-function-as-values-anonymous %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val nums = (1 to 10).toList
+
+val doubles = nums.map(_ * 2) // double each value
+val lessThanFive = nums.filter(_ < 5) // List(1,2,3,4)
+```
+{% endtab %}
+{% endtabs %}
+
+在这些示例中，匿名函数被传递到 `map` 和 `filter` 中。
+
+> 匿名函数也称为 *lambdas*。
+
+除了将匿名函数传递给 `filter` 和 `map` 之外，您还可以为它们提供 *方法*：
+
+{% tabs fp-function-as-values-defined %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// two methods
+def double(i: Int): Int = i * 2
+def underFive(i: Int): Boolean = i < 5
+
+// pass those methods into filter and map
+val doubles = nums.filter(underFive).map(double)
+```
+{% endtab %}
+{% endtabs %}
+
+这种将方法和函数视为值的能力是函数式编程语言提供的强大特性。
+
+> 从技术上讲，将另一个函数作为输入参数的函数称为 *高阶函数*。
+> （如果你喜欢幽默，就像有人曾经写过的那样，这就像说一个将另一个类的实例作为构造函数参数的类是一个高阶类。）
+
+## 函数、匿名函数和方法
+
+正如您在这些示例中看到的，这是一个匿名函数：
+
+{% tabs fp-anonymous-function-short %}
+{% tab 'Scala 2 and 3' %}
+```scala
+_ * 2
+```
+{% endtab %}
+{% endtabs %}
+
+如 [高阶函数][hofs] 讨论中所示，上面的写法是下面语法的简写版本：
+
+{% tabs fp-anonymous-function-full %}
+{% tab 'Scala 2 and 3' %}
+```scala
+(i: Int) => i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+像这样的函数被称为“匿名”，因为它们没有名字。
+如果你想给一个名字，只需将它分配给一个变量：
+
+{% tabs fp-function-assignement %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val double = (i: Int) => i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+现在你有了一个命名函数，一个分配给变量的函数。
+您可以像使用方法一样使用此函数：
+
+{% tabs fp-function-used-like-method %}
+{% tab 'Scala 2 and 3' %}
+```scala
+double(2) // 4
+```
+{% endtab %}
+{% endtabs %}
+
+在大多数情况下，`double` 是函数还是方法并不重要。 Scala 允许您以同样的方式对待它们。
+在幕后，让您像对待函数一样对待方法的 Scala 技术被称为 [Eta 表达式][eta]。
+
+这种将函数作为变量无缝传递的能力是 Scala 等函数式编程语言的一个显着特征。
+正如您在本书中的 `map` 和 `filter` 示例中所见，将函数传递给其他函数的能力有助于您创建简洁且仍然可读的代码---*富有表现力*。
+
+如果您对将函数作为参数传递给其他函数的过程不适应，可以尝试以下几个示例：
+
+{% tabs fp-function-as-values-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+List("bob", "joe").map(_.toUpperCase) // List(BOB, JOE)
+List("bob", "joe").map(_.capitalize) // List(Bob, Joe)
+List("plum", "banana").map(_.length) // List(4, 6)
+
+val fruits = List("apple", "pear")
+fruits.map(_.toUpperCase) // List(APPLE, PEAR)
+fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R)
+
+val nums = List(5, 1, 3, 11, 7)
+nums.map(_ * 2) // List(10, 2, 6, 22, 14)
+nums.filter(_ > 3) // List(5, 11, 7)
+nums.takeWhile(_ < 6) // List(5, 1, 3)
+nums.sortWith(_ < _) // List(1, 3, 5, 7, 11)
+nums.sortWith(_ > _) // List(11, 7, 5, 3, 1)
+
+nums.takeWhile(_ < 6).sortWith(_ < _) // List(1, 3, 5)
+```
+{% endtab %}
+{% endtabs %}
+
+[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %}
+[eta]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_zh-cn/overviews/scala3-book/fp-immutable-values.md b/_zh-cn/overviews/scala3-book/fp-immutable-values.md
new file mode 100644
index 0000000000..1d6b474daf
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-immutable-values.md
@@ -0,0 +1,95 @@
+---
+title: 不可变值
+type: section
+description: This section looks at the use of immutable values in functional programming.
+language: zh-cn
+num: 43
+previous-page: fp-what-is-fp
+next-page: fp-pure-functions
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+在纯函数式编程中，只使用不可变的值。
+在 Scala 中，这意味着：
+
+- 所有变量都创建为 `val` 字段
+- 仅使用不可变的集合类，例如 `List`、`Vector` 和不可变的 `Map` 和 `Set` 类
+
+只使用不可变变量会引发一个有趣的问题：如果一切都是不可变的，那么任何东西都如何改变？
+
+当谈到使用集合时，一个答案是你不会改变现有的集合。相反，您将函数应用于现有集合以创建新集合。
+这就是像 `map` 和 `filter` 这样的高阶函数的用武之地。
+
+例如，假设你有一个名字列表——一个 `List[String]`——都是小写的，你想找到所有以字母 `"j"` 开头的名字，并且把找出来的名字大写。
+在 FP 中，您编写以下代码：
+
+{% tabs fp-list %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = List("jane", "jon", "mary", "joe")
+val b = a.filter(_.startsWith("j"))
+ .map(_.capitalize)
+```
+{% endtab %}
+{% endtabs %}
+
+如图所示，您不会改变原始列表 `a`。
+相反，您将过滤和转换函数应用于 `a` 以创建一个新集合，并将该结果分配给新的不可变变量 `b` 。
+
+同样，在 FP 中，您不会创建具有可变 `var` 构造函数参数的类。
+也就是说，你不要这样写：
+
+{% tabs fp--class-variables %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// don’t do this in FP
+class Person(var firstName: String, var lastName: String)
+ --- ---
+```
+{% endtab %}
+{% endtabs %}
+
+相反，您通常创建 `case` 类，其构造函数参数默认为 `val`：
+
+{% tabs fp-immutable-case-class %}
+{% tab 'Scala 2 and 3' %}
+```scala
+case class Person(firstName: String, lastName: String)
+```
+{% endtab %}
+{% endtabs %}
+
+现在你创建一个 `Person` 实例作为 `val` 字段：
+
+{% tabs fp-case-class-creation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val reginald = Person("Reginald", "Dwight")
+```
+{% endtab %}
+{% endtabs %}
+
+然后，当您需要对数据进行更改时，您可以使用 `case` 类附带的 `copy` 方法来“在制作副本时更新数据”，如下所示：
+
+{% tabs fp-case-class-copy %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val elton = reginald.copy(
+ firstName = "Elton", // update the first name
+ lastName = "John" // update the last name
+)
+```
+{% endtab %}
+{% endtabs %}
+
+还有其他处理不可变集合和变量的技术，但希望这些示例能让您尝试一下这些技术。
+
+> 根据您的需要，您可以创建枚举、traits 或类，而不是 `case` 类。
+> 有关详细信息，请参阅[数据建模][modeling]一章。
+
+[modeling]: {% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %}
diff --git a/_zh-cn/overviews/scala3-book/fp-intro.md b/_zh-cn/overviews/scala3-book/fp-intro.md
new file mode 100644
index 0000000000..4805401aec
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-intro.md
@@ -0,0 +1,30 @@
+---
+title: 函数式编程
+type: chapter
+description: This chapter provides an introduction to functional programming in Scala 3.
+language: zh-cn
+num: 41
+previous-page: collections-summary
+next-page: fp-what-is-fp
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 允许您以面向对象编程 (OOP) 风格、函数式编程 (FP) 风格以及混合风格编写代码——结合使用这两种方法。
+正如 Scala 的创建者 Martin Odersky 所说，Scala 的本质是在类型化设置中融合了函数式编程和面向对象编程：
+
+- 逻辑函数
+- 模块化的对象
+
+本章假设您熟悉 OOP 而不太熟悉 FP，因此它简要介绍了几个主要的函数式编程概念：
+
+- 什么是函数式编程？
+- 不可变值
+- 纯函数
+- 函数是值
+- 函数式错误处理
+
diff --git a/_zh-cn/overviews/scala3-book/fp-pure-functions.md b/_zh-cn/overviews/scala3-book/fp-pure-functions.md
new file mode 100644
index 0000000000..25fa4398ff
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-pure-functions.md
@@ -0,0 +1,129 @@
+---
+title: 纯函数
+type: section
+description: This section looks at the use of pure functions in functional programming.
+language: zh-cn
+num: 44
+previous-page: fp-immutable-values
+next-page: fp-functions-are-values
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 提供的另一个帮助您编写函数式代码的特性是编写纯函数的能力。
+一个_纯函数_可以这样定义：
+
+- 函数 `f` 是纯函数，如果给定相同的输入 `x`，它总是返回相同的输出 `f(x)`
+- 函数的输出_只_取决于它的输入变量和它的实现
+- 它只计算输出而不修改周围的世界
+
+这意味着：
+- 它不修改其输入参数
+- 它不会改变任何隐藏状态
+- 没有任何“后门”：不从外界读取数据（包括控制台、Web服务、数据库、文件等），也不向外界写入数据
+
+作为这个定义的结果，任何时候你调用一个具有相同输入值的纯函数，你总是会得到相同的结果。
+例如，您可以使用输入值 `2` 无限次调用 `double` 函数，并且始终得到结果 `4`。
+
+## 纯函数示例
+
+给定这个定义，你可以想象， *scala.math._* 包中的这些方法是纯函数：
+
+- `abs`
+- `ceil`
+- `max`
+
+这些 `String` 方法也是纯函数：
+
+- `isEmpty`
+- `length`
+- `substring`
+
+Scala 集合类上的大多数方法也可以作为纯函数工作，包括 `drop`、`filter`、`map` 等等。
+
+> 在 Scala 中，_函数_和_方法_几乎可以完全互换，因此即使我们使用行业通用术语“纯函数”，这个术语也可以用来描述函数和方法。
+> 如果您对如何像函数一样使用方法感兴趣，请参阅 [Eta 表达式][eta] 的讨论。
+
+## 不纯函数示例
+
+相反，以下函数是_不纯的_，因为它们违反了纯函数的定义。
+
+- `println` -- 与控制台、文件、数据库、Web 服务、传感器等交互的方法都是不纯的。
+- `currentTimeMillis ` -- 与日期和时间相关的方法都是不纯的，因为它们的输出取决于输入参数以外的其他东西
+- `sys.error` -- 异常抛出方法是不纯的，因为它们不简单地返回结果
+
+不纯函数通常会执行以下一项或多项操作：
+
+- 从隐藏状态读取，即它们访问的变量和数据不是作为输入参数明确地传递给函数
+- 写入隐藏状态
+- 改变他们给定的参数，或改变隐藏变量，例如类中包涵的字段
+- 与外界执行某种 I/O
+
+> 通常，您应该注意返回类型为 `Unit` 的函数。
+> 因为这些函数不返回任何东西，逻辑上你调用它的唯一原因是实现一些副作用。
+> 因此，这些功能的使用通常是不纯的。
+
+## 但是需要不纯的函数...
+
+当然，如果一个应用程序不能读取或写入外部世界，它就不是很有用，所以人们提出以下建议：
+
+> 使用纯函数编写应用程序的核心，然后围绕该核心编写一个不纯的“包装器”以与外部世界交互。
+> 正如有人曾经说过的，这就像在纯蛋糕上加了一层不纯的糖霜。
+
+重要的是要注意，有一些方法可以让与外界的不纯粹互动感觉更纯粹。
+例如，你会听说使用 `IO` Monad 来处理输入和输出。
+这些主题超出了本文档的范围，所以为了简单起见，这样认识 FP 会有所帮助：FP 应用程序有一个纯函数核心，还有其他一些函数把这些纯函数包装起来与外部世界交互。
+
+## 编写纯函数
+
+**注意**：在本节中，常见的行业术语“纯函数”通常用于指代 Scala 方法。
+
+要在 Scala 中编写纯函数，只需使用 Scala 的方法语法编写它们（尽管您也可以使用 Scala 的函数语法）。
+例如，这是一个将给定输入值加倍的纯函数：
+
+{% tabs fp-pure-function %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def double(i: Int): Int = i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+如果您对递归感到满意，这是一个计算整数列表之和的纯函数：
+
+{% tabs fp-pure-recursive-function class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def sum(xs: List[Int]): Int = xs match {
+ case Nil => 0
+ case head :: tail => head + sum(tail)
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def sum(xs: List[Int]): Int = xs match
+ case Nil => 0
+ case head :: tail => head + sum(tail)
+```
+{% endtab %}
+{% endtabs %}
+
+如果您理解该代码，您会发现它符合纯函数定义。
+
+## 要点
+
+本节的第一个要点是纯函数的定义：
+
+> _纯函数_是仅依赖于其声明的输入及其实现来产生其输出的函数。
+> 它只计算其输出，不依赖或修改外部世界。
+
+第二个要点是每个现实世界的应用程序都与外部世界交互。
+因此，考虑函数式程序的一种简化方法是，它们由一个纯函数核心组成，其他一些函数把这些纯函数包装起来与外部世界交互。
+
+[eta]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_zh-cn/overviews/scala3-book/fp-summary.md b/_zh-cn/overviews/scala3-book/fp-summary.md
new file mode 100644
index 0000000000..459b2d6f82
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-summary.md
@@ -0,0 +1,30 @@
+---
+title: 总结
+type: section
+description: This section summarizes the previous functional programming sections.
+language: zh-cn
+num: 47
+previous-page: fp-functional-error-handling
+next-page: types-introduction
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本章在比较高的层次上，对 Scala 中的函数式编程进行了介绍。
+涵盖的主题是：
+
+- 什么是函数式编程？
+- 不可变值
+- 纯函数
+- 函数是值
+- 函数式错误处理
+
+如前所述，函数式编程是一个很大的话题，所以我们在本书中所能做的就是触及这些介绍性概念。
+有关详细信息，请参阅 [参考文档][reference]。
+
+[reference]: {{ site.scala3ref }}/overview.html
+
diff --git a/_zh-cn/overviews/scala3-book/fp-what-is-fp.md b/_zh-cn/overviews/scala3-book/fp-what-is-fp.md
new file mode 100644
index 0000000000..79370d450b
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-what-is-fp.md
@@ -0,0 +1,33 @@
+---
+title: 什么是函数式编程？
+type: section
+description: This section provides an answer to the question, what is functional programming?
+language: zh-cn
+num: 42
+previous-page: fp-intro
+next-page: fp-immutable-values
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+[维基百科定义_函数式编程_](https://en.wikipedia.org/wiki/Functional_programming)如下：
+
+ ints = List.of(1, 2, 3);
+List doubledInts = ints.stream()
+ .map(i -> i * 2)
+ .collect(Collectors.toList());
+```
+{% endtab %}
+{% endtabs %}
+
+## 缩短匿名函数
+
+当你想要明确时，你可以使用这个长格式编写一个匿名函数：
+
+{% tabs fun-anonymous-6 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val doubledInts = ints.map((i: Int) => i * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+该表达式中的匿名函数是这样的：
+
+{% tabs fun-anonymous-7 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+(i: Int) => i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+如果您不熟悉这种语法，将 `=>` 符号视为转换器会有所帮助，因为表达式使用 `=>` 符号右侧的算法（在这种情况下，一个将 `Int` 加倍的表达式）把符号左侧的参数列表（名为 `i` 的 `Int` 变量) *转换*为新结果。
+
+### 缩短该表达式
+
+这种长形式可以缩短，如以下步骤所示。
+首先，这是最长和最明确的形式：
+
+{% tabs fun-anonymous-8 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val doubledInts = ints.map((i: Int) => i * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+因为 Scala 编译器可以从 `ints` 中的数据推断 `i` 是一个 `Int`，所以可以删除 `Int` 声明：
+
+{% tabs fun-anonymous-9 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val doubledInts = ints.map((i) => i * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+因为只有一个参数，所以不需要在参数 `i` 周围的括号：
+
+{% tabs fun-anonymous-10 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val doubledInts = ints.map(i => i * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+因为当参数在函数中只出现一次时，Scala 允许您使用 `_` 符号而不是变量名，所以代码可以进一步简化：
+
+{% tabs fun-anonymous-11 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val doubledInts = ints.map(_ * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+### 变得更短
+
+在其他示例中，您可以进一步简化匿名函数。
+例如，从最显式的形式开始，您可以使用带有 `List` 类 `foreach` 方法的匿名函数打印 `ints` 中的每个元素：
+
+{% tabs fun-anonymous-12 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+ints.foreach((i: Int) => println(i))
+```
+{% endtab %}
+{% endtabs %}
+
+和以前一样，不需要 `Int` 声明，因为只有一个参数，所以不需要 `i` 周围的括号：
+
+{% tabs fun-anonymous-13 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+ints.foreach(i => println(i))
+```
+{% endtab %}
+{% endtabs %}
+
+因为 `i` 在函数体中只使用一次，表达式可以进一步简化为 `_` 符号：
+
+{% tabs fun-anonymous-14 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+ints.foreach(println(_))
+```
+{% endtab %}
+{% endtabs %}
+
+最后，如果一个匿名函数由一个接受单个参数的方法调用组成，您不需要显式命名和指定参数，因此您最终可以只写方法的名称（此处为 `println`）：
+
+{% tabs fun-anonymous-15 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+ints.foreach(println)
+```
+{% endtab %}
+{% endtabs %}
+
diff --git a/_zh-cn/overviews/scala3-book/fun-eta-expansion.md b/_zh-cn/overviews/scala3-book/fun-eta-expansion.md
new file mode 100644
index 0000000000..562ed0074e
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fun-eta-expansion.md
@@ -0,0 +1,114 @@
+---
+title: Eta 扩展
+type: section
+description: This page discusses Eta Expansion, the Scala technology that automatically and transparently converts methods into functions.
+language: zh-cn
+num: 31
+previous-page: fun-function-variables
+next-page: fun-hofs
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+当你查看 Scala 集合类的 `map` 方法的 Scaladoc 时，你会看到它被定义为接受一个_函数_：
+
+{% tabs fun_1 %}
+{% tab 'Scala 2 and 3' for=fun_1 %}
+```scala
+def map[B](f: (A) => B): List[B]
+ ------------
+```
+{% endtab %}
+{% endtabs %}
+
+事实上，Scaladoc 明确指出，“`f` 是应用于每个元素的_函数_。”
+但尽管如此，你可以通过某种方式将_方法_传递给 `map`，它仍然有效：
+
+{% tabs fun_2 %}
+{% tab 'Scala 2 and 3' for=fun_2 %}
+```scala
+def times10(i: Int) = i * 10 // a method
+List(1, 2, 3).map(times10) // List(10,20,30)
+```
+{% endtab %}
+{% endtabs %}
+
+你有没有想过这是如何工作的——如何将_方法_传递给需要_函数_的`map`？
+
+这背后的技术被称为_Eta Expansion_。
+它将 _方法类型_的表达式转换为 _函数类型_的等效表达式，并且它无缝而安静地完成了。
+
+## 方法和函数的区别
+
+{% comment %}
+NOTE: I got the following “method” definition from this page (https://dotty.epfl.ch/docs/reference/changed-features/eta-expansion-spec.html), but I’m not sure it’s 100% accurate now that 方法 can exist outside of classes/traits/objects.
+I’ve made a few changes to that description that I hope are more accurate and up to date.
+{% endcomment %}
+
+从历史上看，_方法_一直是类定义的一部分，尽管在 Scala 3 中您现在可以拥有类之外的方法，例如 [Toplevel definitions][toplevel] 和 [extension 方法][extension]。
+
+与方法不同，_函数_本身就是完整的对象，使它们成为第一等的实体。
+
+它们的语法也不同。
+此示例说明如何定义执行相同任务的方法和函数，确定给定整数是否为偶数：
+
+{% tabs fun_3 %}
+{% tab 'Scala 2 and 3' for=fun_3 %}
+```scala
+def isEvenMethod(i: Int) = i % 2 == 0 // a method
+val isEvenFunction = (i: Int) => i % 2 == 0 // a function
+```
+{% endtab %}
+{% endtabs %}
+
+该函数确实是一个对象，因此您可以像使用任何其他变量一样使用它，例如将其放入列表中：
+
+{% tabs fun_4 %}
+{% tab 'Scala 2 and 3' for=fun_4 %}
+```scala
+val functions = List(isEvenFunction)
+```
+{% endtab %}
+{% endtabs %}
+
+
+{% tabs fun_5 class=tabs-scala-version %}
+{% tab 'Scala 2' for=fun_5 %}
+```scala
+// this example shows the Scala 2 error message
+val methods = List(isEvenMethod)
+ ^
+error: missing argument list for method isEvenMethod
+Unapplied methods are only converted to functions when a function type is expected.
+You can make this conversion explicit by writing `isEvenMethod _` or `isEvenMethod(_)` instead of `isEvenMethod`.
+```
+
+相反，从技术上讲，方法不是对象，因此在 Scala 2 中，您不能将方法放入 `List` 中，至少不能直接放入，如下例所示：
+
+{% endtab %}
+{% tab 'Scala 3' for=fun_5 %}
+
+```scala
+val functions = List(isEvenFunction) // works
+val methods = List(isEvenMethod) // works
+```
+
+Scala 3 的重要部分是改进了 Eta 扩展技术，所以现在当您尝试将方法当作变量用，它是可以工作的---您不必自己处理手动转换：
+
+{% endtab %}
+{% endtabs %}
+
+就这本入门书而言，需要了解的重要事项是：
+
+- Eta Expansion 是 Scala 技术，让您可以像使用函数一样使用方法
+- 该技术在 Scala 3 中得到了改进，几乎完全无缝
+
+有关其工作原理的更多详细信息，请参阅参考文档中的 [Eta 扩展页面][eta_expansion]。
+
+[eta_expansion]: {{ site.scala3ref }}/changed-features/eta-expansion.html
+[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}
+[toplevel]: {% link _zh-cn/overviews/scala3-book/taste-toplevel-definitions.md %}
diff --git a/_zh-cn/overviews/scala3-book/fun-function-variables.md b/_zh-cn/overviews/scala3-book/fun-function-variables.md
new file mode 100644
index 0000000000..e4591ef2ee
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fun-function-variables.md
@@ -0,0 +1,166 @@
+---
+title: 函数变量
+type: section
+description: This page shows how to use anonymous functions in Scala, including examples with the List class 'map' and 'filter' functions.
+language: zh-cn
+num: 30
+previous-page: fun-anonymous-functions
+next-page: fun-eta-expansion
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+从上一节回到这个例子：
+
+{% tabs fun-function-variables-1 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val doubledInts = ints.map((i: Int) => i * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+我们注意到这部分表达式是一个匿名函数：
+
+{% tabs fun-function-variables-2 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+(i: Int) => i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+它被称为 *匿名* 的原因是它没有分配给变量，因此没有名称。
+
+但是，可以将匿名函数（也称为*函数字面量*）分配给变量以创建*函数变量*：
+
+{% tabs fun-function-variables-3 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val double = (i: Int) => i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+这将创建一个名为 `double` 的函数变量。
+在这个表达式中，原始函数字面量在 `=` 符号的右侧：
+
+{% tabs fun-function-variables-4 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val double = (i: Int) => i * 2
+ -----------------
+```
+{% endtab %}
+{% endtabs %}
+
+新变量名在左侧：
+
+{% tabs fun-function-variables-5 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val double = (i: Int) => i * 2
+ ------
+```
+{% endtab %}
+{% endtabs %}
+
+并且函数的参数列表在此处加下划线：
+
+{% tabs fun-function-variables-6 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val double = (i: Int) => i * 2
+ --------
+```
+{% endtab %}
+{% endtabs %}
+
+就像方法的参数列表一样，这意味着 `double` 函数有一个参数，一个名为 `i` 的 `Int`。
+你可以在 REPL 中看到 `double` 的类型为 `Int => Int`，这意味着它接受一个 `Int` 参数并返回一个 `Int`：
+
+{% tabs fun-function-variables-7 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val double = (i: Int) => i * 2
+val double: Int => Int = ...
+```
+{% endtab %}
+{% endtabs %}
+
+### 调用函数
+
+现在你可以像这样调用`double`函数：
+
+{% tabs fun-function-variables-8 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val x = double(2) // 4
+```
+{% endtab %}
+{% endtabs %}
+
+您还可以将 `double` 传递给 `map` 调用：
+
+{% tabs fun-function-variables-9 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+List(1, 2, 3).map(double) // List(2, 4, 6)
+```
+{% endtab %}
+{% endtabs %}
+
+此外，当您有 `Int => Int` 类型的其他函数时：
+
+{% tabs fun-function-variables-10 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val triple = (i: Int) => i * 3
+```
+{% endtab %}
+{% endtabs %}
+
+您可以将它们存储在 `List` 或 `Map` 中：
+
+{% tabs fun-function-variables-11 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val functionList = List(double, triple)
+
+val functionMap = Map(
+ "2x" -> double,
+ "3x" -> triple
+)
+```
+{% endtab %}
+{% endtabs %}
+
+如果将这些表达式粘贴到 REPL 中，您会看到它们具有以下类型：
+
+{% tabs fun-function-variables-12 %}
+{% tab 'Scala 2 and 3' %}
+````
+// a List that contains functions of the type `Int => Int`
+functionList: List[Int => Int]
+
+// a Map whose keys have the type `String`, and whose
+// values have the type `Int => Int`
+functionMap: Map[String, Int => Int]
+````
+{% endtab %}
+{% endtabs %}
+
+## 关键点
+
+这里的重要部分是：
+
+- 要创建函数变量，只需将变量名分配给函数字面量
+- 一旦你有了一个函数，你可以像对待任何其他变量一样对待它，即像一个`String`或`Int`变量
+
+并且由于 Scala 3 中改进的 [Eta Expansion][eta_expansion] 函数式，您可以以相同的方式处理 *方法*。
+
+[eta_expansion]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_zh-cn/overviews/scala3-book/fun-hofs.md b/_zh-cn/overviews/scala3-book/fun-hofs.md
new file mode 100644
index 0000000000..a0fda317b8
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fun-hofs.md
@@ -0,0 +1,384 @@
+---
+title: 高阶函数
+type: section
+description: This page demonstrates how to create and use higher-order functions in Scala.
+language: zh-cn
+num: 32
+previous-page: fun-eta-expansion
+next-page: fun-write-map-function
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+高阶函数 (HOF) 通常定义为这类函数，它 (a) 将其他函数作为输入参数或 (b) 返回函数作为结果。
+在 Scala 中，HOF 是可能的，因为函数是一等值。
+
+需要注意的是，虽然我们在本文档中使用了常见的行业术语“高阶函数”，但在 Scala 中，该短语同时适用于 *方法* 和 *函数*。
+得益于 Scala 的 [Eta 扩展技术][eta_expansion]，它们通常可以在相同的地方使用。
+
+## 从消费者到创造者
+
+在本书到目前为止的示例中，您已经了解了如何成为方法的*消费者*，该方法将其他函数作为输入参数，例如使用诸如 `map` 和 `filter` 之类的 HOF。
+在接下来的几节中，您将了解如何成为 HOF 的*创造者*，包括：
+
+- 如何编写将函数作为输入参数的方法
+- 如何从方法中返回函数
+
+在这个过程中你会看到：
+
+- 用于定义函数输入参数的语法
+- 引用函数后如何调用它
+
+作为本次讨论的一个有益的副作用，一旦您对这种语法感到满意，您将使用它来定义函数参数、匿名函数和函数变量，并且也更容易阅读有关高阶函数的 Scaladoc。
+
+## 理解过滤器的 Scaladoc
+
+要了解高阶函数的工作原理，深入研究一个示例会有所帮助。
+例如，您可以通过查看 Scaladoc 来了解 `filter` 接受的函数类型。
+这是 `List[A]` 类中的 `filter` 定义：
+
+{% tabs filter-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def filter(p: (A) => Boolean): List[A]
+```
+{% endtab %}
+{% endtabs %}
+
+这表明 `filter` 是一个接受名为 `p` 的函数参数的方法。
+按照惯例，`p` 代表 *谓词（predicate）*，它只是一个返回 `Boolean` 值的函数。
+所以 `filter` 将谓词 `p` 作为输入参数，并返回一个 `List[A]`，其中 `A` 是列表中保存的类型；如果你在 `List[Int]` 上调用 `filter`，`A` 是 `Int` 类型。
+
+在这一点上，如果你不知道 `filter` 方法的用途，你只知道它的算法以某种方式使用谓词 `p` 创建并返回 `List[A]`。
+
+具体看函数参数 `p`，这部分 `filter` 的描述：
+
+{% tabs filter-definition_1 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+p: (A) => Boolean
+```
+{% endtab %}
+{% endtabs %}
+
+意味着您传入的任何函数都必须将类型 `A` 作为输入参数并返回一个 `Boolean` 。
+因此，如果您的列表是 `List[Int]`，则可以将通用类型 `A` 替换为 `Int`，并像这样读取该签名：
+
+{% tabs filter-definition_2 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+p: (Int) => Boolean
+```
+{% endtab %}
+{% endtabs %}
+
+因为 `isEven` 具有这种类型——它将输入 `Int` 转换为结果 `Boolean`——它可以与 `filter` 一起使用。
+
+{% comment %}
+NOTE: (A low-priority issue): The next several sections can be condensed.
+{% endcomment %}
+
+## 编写接受函数参数的方法
+
+鉴于此背景，让我们开始编写将函数作为输入参数的方法。
+
+**注意：**为了使下面的讨论更清楚，我们将您编写的代码称为*方法*，将您作为输入参数接受的代码称为*函数*。
+
+### 第一个例子
+
+要创建一个接受函数参数的方法，您所要做的就是：
+
+1. 在方法的参数列表中，定义要接受的函数的签名
+2. 在你的方法中使用那个函数
+
+为了证明这一点，这里有一个方法，它接受一个名为 `f` 的输入参数，其中 `f` 是一个函数：
+
+{% tabs sayHello-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def sayHello(f: () => Unit): Unit = f()
+```
+{% endtab %}
+{% endtabs %}
+
+这部分代码---*类型签名*---声明 `f` 是一个函数，并定义了 `sayHello` 方法将接受的函数类型：
+
+{% tabs sayHello-definition_1 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+f: () => Unit
+```
+{% endtab %}
+{% endtabs %}
+
+这是它的工作原理：
+
+- `f` 是函数输入参数的名称。
+ 这就像将 `String` 参数命名为 `s` 或 `Int` 参数命名为 `i`。
+- `f` 的类型签名指定此方法将接受的函数的 *类型*。
+- `f` 签名的 `()` 部分（在 `=>` 符号的左侧）表明 `f` 不接受输入参数。
+- 签名的 `Unit` 部分（在 `=>` 符号的右侧）表示 `f` 不应返回有意义的结果。
+- 回顾 `sayHello` 方法的主体（在 `=` 符号的右侧），那里的 `f()` 语句调用传入的函数。
+
+现在我们已经定义了 `sayHello`，让我们创建一个函数来匹配 `f` 的签名，以便我们可以测试它。
+以下函数不接受任何输入参数并且不返回任何内容，因此它匹配 `f` 的类型签名：
+
+{% tabs helloJoe-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def helloJoe(): Unit = println("Hello, Joe")
+```
+{% endtab %}
+{% endtabs %}
+
+因为类型签名匹配，你可以将 `helloJoe` 传递给 `sayHello`：
+
+{% tabs sayHello-usage %}
+{% tab 'Scala 2 and 3' %}
+```scala
+sayHello(helloJoe) // prints "Hello, Joe"
+```
+{% endtab %}
+{% endtabs %}
+
+如果您以前从未这样做过，那么恭喜您：
+您刚刚定义了一个名为 `sayHello` 的方法，它接受一个函数作为输入参数，然后在其方法体中调用该函数。
+
+### sayHello 可以带很多函数
+
+重要的是要知道这种方法的美妙之处并不是说 `sayHello` 可以将 *一个* 函数作为输入参数；而在于它可以采用与 `f` 签名匹配的 *任意一个* 函数。
+例如，因为下一个函数没有输入参数并且不返回任何内容，所以它也适用于 `sayHello`：
+
+{% tabs bonjourJulien-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def bonjourJulien(): Unit = println("Bonjour, Julien")
+```
+{% endtab %}
+{% endtabs %}
+
+它在 REPL 中：
+
+{% tabs bonjourJulien-usage %}
+{% tab 'Scala 2 and 3' %}
+````
+scala> sayHello(bonjourJulien)
+Bonjour, Julien
+````
+{% endtab %}
+{% endtabs %}
+
+这是一个好的开始。
+现在唯一要做的就是查看更多示例，了解如何为函数参数定义不同的类型签名。
+
+## 定义函数输入参数的通用语法
+
+在这种方法中：
+
+{% tabs sayHello-definition-2 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def sayHello(f: () => Unit): Unit
+```
+{% endtab %}
+{% endtabs %}
+
+我们注意到 `f` 的类型签名是：
+
+{% tabs sayHello-definition-2_1 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+() => Unit
+```
+{% endtab %}
+{% endtabs %}
+
+我们知道这意味着，“一个没有输入参数并且不返回任何有意义的东西的函数（由 `Unit` 给出）。”
+
+为了演示更多类型签名示例，这里有一个函数，它接受一个 `String` 参数并返回一个 `Int`：
+
+{% tabs sayHello-definition-2_2 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+f: (String) => Int
+```
+{% endtab %}
+{% endtabs %}
+
+什么样的函数接受一个字符串并返回一个整数？
+“字符串长度”和校验和等函数就是两个例子。
+
+同样，此函数接受两个 `Int` 参数并返回一个 `Int`：
+
+{% tabs sayHello-definition-2_3 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+f: (Int, Int) => Int
+```
+{% endtab %}
+{% endtabs %}
+
+你能想象什么样的函数匹配那个签名？
+
+答案是任何接受两个 `Int` 输入参数并返回 `Int` 的函数都与该签名匹配，因此所有这些“函数”（实际上是方法）都是匹配的：
+
+{% tabs add-sub-mul-definitions %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def add(a: Int, b: Int): Int = a + b
+def subtract(a: Int, b: Int): Int = a - b
+def multiply(a: Int, b: Int): Int = a * b
+```
+{% endtab %}
+{% endtabs %}
+
+正如您可以从这些示例中推断出的，定义函数参数类型签名的一般语法是：
+
+{% tabs add-sub-mul-definitions_1 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+variableName: (parameterTypes ...) => returnType
+```
+{% endtab %}
+{% endtabs %}
+
+> 因为函数式编程就像创建和组合一系列代数方程，所以在设计函数和应用程序时通常会考虑*很多*类型。
+> 你可能会说你“在类型中思考”。
+
+## 将函数参数与其他参数一起使用
+
+为了使 HOF 真正有用，它们还需要一些数据来处理。
+对于像 `List` 这样的类，它的 `map` 方法已经有数据可以处理：`List` 中的数据。
+但是对于没有自己数据的独立 HOF，它也应该接受数据作为其他输入参数。
+
+例如，这是一个名为 `executeNTimes` 的方法，它有两个输入参数：一个函数和一个 `Int`：
+
+{% tabs executeNTimes-definition class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def executeNTimes(f: () => Unit, n: Int): Unit =
+ for (i <- 1 to n) f()
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+def executeNTimes(f: () => Unit, n: Int): Unit =
+ for i <- 1 to n do f()
+```
+{% endtab %}
+{% endtabs %}
+
+如代码所示，`executeNTimes` 执行了`f` 函数 `n` 次。
+因为像这样的简单 `for` 循环没有返回值，`executeNTimes` 返回 `Unit`。
+
+要测试 `executeNTimes`，请定义一个匹配 `f` 签名的方法：
+
+{% tabs helloWorld-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// a method of type `() => Unit`
+def helloWorld(): Unit = println("Hello, world")
+```
+{% endtab %}
+{% endtabs %}
+
+然后将该方法与 `Int` 一起传递给`executeNTimes`：
+
+{% tabs helloWorld-usage %}
+{% tab 'Scala 2 and 3' %}
+````
+scala> executeNTimes(helloWorld, 3)
+Hello, world
+Hello, world
+Hello, world
+````
+{% endtab %}
+{% endtabs %}
+
+优秀。
+`executeNTimes` 方法执行 `helloWorld` 函数 3 次。
+
+### 需要多少参数
+
+您的方法可以继续变得尽可能复杂。
+例如，此方法采用类型为 `(Int, Int) => Int` 的函数，以及两个输入参数：
+
+{% tabs executeAndPrint-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def executeAndPrint(f: (Int, Int) => Int, i: Int, j: Int): Unit =
+ println(f(i, j))
+```
+{% endtab %}
+{% endtabs %}
+
+因为这些 `sum` 和 `multiply` 方法与该类型签名匹配，所以它们可以与两个 `Int` 值一起传递到 `executeAndPrint` 中：
+
+{% tabs executeAndPrint-usage %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def sum(x: Int, y: Int) = x + y
+def multiply(x: Int, y: Int) = x * y
+
+executeAndPrint(sum, 3, 11) // prints 14
+executeAndPrint(multiply, 3, 9) // prints 27
+```
+{% endtab %}
+{% endtabs %}
+
+## 函数类型签名一致性
+
+学习 Scala 的函数类型签名的一个好处是，用于定义函数输入参数的语法与用于编写函数字面量的语法相同。
+
+例如，如果你要编写一个计算两个整数之和的函数，你可以这样写：
+
+{% tabs f-val-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val f: (Int, Int) => Int = (a, b) => a + b
+```
+{% endtab %}
+{% endtabs %}
+
+该代码由类型签名组成：
+
+````
+val f: (Int, Int) => Int = (a, b) => a + b
+ -----------------
+````
+
+输入参数：
+
+````
+val f: (Int, Int) => Int = (a, b) => a + b
+ ------
+````
+
+和函数体：
+
+````
+val f: (Int, Int) => Int = (a, b) => a + b
+ -----
+````
+
+这里展示了 Scala 的一致性，这里的函数类型：
+
+````
+val f: (Int, Int) => Int = (a, b) => a + b
+ -----------------
+````
+
+与用于定义函数输入参数的类型签名相同：
+
+````
+def executeAndPrint(f: (Int, Int) => Int, ...
+ -----------------
+````
+
+一旦你熟悉了这种语法，你就会用它来定义函数参数、匿名函数和函数变量，而且当你阅读 Scaladoc 中有关高阶函数的内容时，这些内容变得更容易了。
+
+[eta_expansion]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_zh-cn/overviews/scala3-book/fun-intro.md b/_zh-cn/overviews/scala3-book/fun-intro.md
new file mode 100644
index 0000000000..90d45c4387
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fun-intro.md
@@ -0,0 +1,17 @@
+---
+title: 函数
+type: chapter
+description: This chapter looks at all topics related to functions in Scala 3.
+language: zh-cn
+num: 28
+previous-page: methods-summary
+next-page: fun-anonymous-functions
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+上一章介绍了 Scala *方法*，本章深入研究 *函数*。
+涵盖的主题包括匿名函数、函数变量和高阶函数 (HOF)，包括如何创建自己的 HOF。
diff --git a/_zh-cn/overviews/scala3-book/fun-summary.md b/_zh-cn/overviews/scala3-book/fun-summary.md
new file mode 100644
index 0000000000..efc747c7ce
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fun-summary.md
@@ -0,0 +1,40 @@
+---
+title: 总结
+type: section
+description: This page shows how to use anonymous functions in Scala, including examples with the List class 'map' and 'filter' functions.
+language: zh-cn
+num: 35
+previous-page: fun-write-method-returns-function
+next-page: packaging-imports
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+这是一个很长的章节，所以让我们回顾一下所涵盖的关键点。
+
+我们通常这样定义高阶函数 (HOF)，它以其他函数作为输入参数或将函数作为其值。
+在 Scala 中这是可能的，因为函数是一等值。
+
+浏览这些部分，首先您会看到：
+
+- 您可以将匿名函数编写为小代码片段
+- 您可以将它们传递给集合类上的几十个 HOF（方法），即像 `filter`、`map` 等方法。
+- 使用这些小代码片段和强大的 HOF，您只需少量代码即可创建大量的函数
+
+在查看了匿名函数和 HOF 之后，您看到了：
+
+- 函数变量只是绑定到变量的匿名函数
+
+在了解如何成为 HOF 的*消费者*之后，您将了解如何成为 HOF 的*创造者*。
+具体来说，您看到了：
+
+- 如何编写将函数作为输入参数的方法
+- 如何从方法中返回函数
+
+本章的一个有益的副作用是您看到了许多关于如何为函数声明类型签名的示例。
+这样做的好处是，您可以使用相同的语法来定义函数参数、匿名函数和函数变量，而且对于 `map`、`filter` 等高阶函数，阅读 Scaladoc 也变得更容易。
+
diff --git a/_zh-cn/overviews/scala3-book/fun-write-map-function.md b/_zh-cn/overviews/scala3-book/fun-write-map-function.md
new file mode 100644
index 0000000000..3ba7e44c1b
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fun-write-map-function.md
@@ -0,0 +1,140 @@
+---
+title: 自定义 map 函数
+type: section
+description: This page demonstrates how to create and use higher-order functions in Scala.
+language: zh-cn
+num: 33
+previous-page: fun-hofs
+next-page: fun-write-method-returns-function
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+现在您已经了解了如何编写自己的高阶函数，让我们快速浏览一个更真实的示例。
+
+想象一下，`List` 类没有自己的 `map` 方法，而您想编写自己的方法。
+创建函数的第一步是准确地陈述问题。
+只关注 `List[Int]`，你说：
+
+> 我想编写一个 `map` 方法，该方法可用于将函数应用于给定的 `List[Int]` 中的每个元素，并将转换后的元素作为新列表返回。
+
+鉴于该声明，您开始编写方法签名。
+首先，您知道您想接受一个函数作为参数，并且该函数应该将 `Int` 转换为某种通用类型 `A`，因此您编写：
+
+{% tabs map-accept-func-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def map(f: (Int) => A)
+```
+{% endtab %}
+{% endtabs %}
+
+使用泛型类型的语法要求在参数列表之前声明该类型符号，因此您添加：
+
+{% tabs map-type-symbol-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def map[A](f: (Int) => A)
+```
+{% endtab %}
+{% endtabs %}
+
+接下来，您知道 `map` 也应该接受 `List[Int]`：
+
+{% tabs map-list-int-param-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def map[A](f: (Int) => A, xs: List[Int])
+```
+{% endtab %}
+{% endtabs %}
+
+最后，您还知道 `map` 返回一个转换后的 `List`，其中包含泛型类型 `A` 的元素：
+
+{% tabs map-with-return-type-definition %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def map[A](f: (Int) => A, xs: List[Int]): List[A] = ???
+```
+{% endtab %}
+{% endtabs %}
+
+这负责方法签名。
+现在您所要做的就是编写方法体。
+`map` 方法将它赋予的函数应用于它赋予的列表中的每个元素，以生成一个新的、转换的列表。
+一种方法是使用 `for` 表达式：
+
+{% tabs for-definition class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+for (x <- xs) yield f(x)
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+for x <- xs yield f(x)
+```
+{% endtab %}
+{% endtabs %}
+
+`for` 表达式通常使代码出奇地简单，对于我们的目的，它最终成为整个方法体。
+
+把它和方法签名放在一起，你现在有了一个独立的 `map` 方法，它与 `List[Int]` 一起工作：
+
+{% tabs map-function class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def map[A](f: (Int) => A, xs: List[Int]): List[A] =
+ for (x <- xs) yield f(x)
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+def map[A](f: (Int) => A, xs: List[Int]): List[A] =
+ for x <- xs yield f(x)
+```
+{% endtab %}
+{% endtabs %}
+
+### 使其泛型化
+
+作为奖励，请注意 `for` 表达式不做任何取决于 `List` 中的类型为 `Int` 的事情。
+因此，您可以将类型签名中的 `Int` 替换为泛型类型参数 `B`：
+
+{% tabs map-function-full-generic class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def map[A, B](f: (B) => A, xs: List[B]): List[A] =
+ for (x <- xs) yield f(x)
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+def map[A, B](f: (B) => A, xs: List[B]): List[A] =
+ for x <- xs yield f(x)
+```
+{% endtab %}
+{% endtabs %}
+
+现在你有了一个适用于任何 `List` 的 `map` 方法。
+
+这些示例表明 `map` 可以按需要工作：
+
+{% tabs map-use-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def double(i : Int) = i * 2
+map(double, List(1, 2, 3)) // List(2, 4, 6)
+
+def strlen(s: String) = s.length
+map(strlen, List("a", "bb", "ccc")) // List(1, 2, 3)
+```
+{% endtab %}
+{% endtabs %}
+
+现在您已经了解了如何编写接受函数作为输入参数的方法，让我们看看返回函数的方法。
+
diff --git a/_zh-cn/overviews/scala3-book/fun-write-method-returns-function.md b/_zh-cn/overviews/scala3-book/fun-write-method-returns-function.md
new file mode 100644
index 0000000000..84e3460b6f
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fun-write-method-returns-function.md
@@ -0,0 +1,244 @@
+---
+title: 创建可以返回函数的方法
+type: section
+description: This page demonstrates how to create and use higher-order functions in Scala.
+language: zh-cn
+num: 34
+previous-page: fun-write-map-function
+next-page: fun-summary
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+由于 Scala 的一致性，编写一个返回函数的方法与您在前几节中看到的所有内容相似。
+例如，假设您想编写一个返回函数的 `greet` 方法。
+我们再次从问题陈述开始：
+
+> 我想创建一个返回函数的 `greet` 方法。
+> 该函数将接受一个字符串参数并使用 `println` 打印它。
+> 为了简化第一个示例，`greet` 不会接受任何输入参数；它只会构建一个函数并返回它。
+
+鉴于该声明，您可以开始构建 `greet`。
+你知道这将是一种方法：
+
+{% tabs fun-write-method-returns-function-1 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def greet()
+```
+{% endtab %}
+{% endtabs %}
+
+您还知道此方法将返回一个函数，该函数 (a) 采用 `String` 参数，并且 (b) 使用 `println` 打印该字符串。
+因此，该函数的类型为 `String => Unit`：
+
+{% tabs fun-write-method-returns-function-2 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def greet(): String => Unit = ???
+ ----------------
+```
+{% endtab %}
+{% endtabs %}
+
+现在你只需要一个方法体。
+您知道该方法需要返回一个函数，并且该函数接受一个“字符串”并打印它。
+此匿名函数与该描述匹配：
+
+{% tabs fun-write-method-returns-function-3 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+(name: String) => println(s"Hello, $name")
+```
+{% endtab %}
+{% endtabs %}
+
+现在您只需从方法中返回该函数：
+
+{% tabs fun-write-method-returns-function-4 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// a method that returns a function
+def greet(): String => Unit =
+ (name: String) => println(s"Hello, $name")
+```
+{% endtab %}
+{% endtabs %}
+
+因为这个方法返回一个函数，所以你可以通过调用`greet()`来得到这个函数。
+这是在 REPL 中做的一个很好的步骤，因为它验证了新函数的类型：
+
+{% tabs fun-write-method-returns-function-5 %}
+{% tab 'Scala 2 and 3' %}
+````
+scala> val greetFunction = greet()
+val greetFunction: String => Unit = Lambda....
+ -----------------------------------------
+````
+{% endtab %}
+{% endtabs %}
+
+现在你可以调用`greetFunction`了：
+
+{% tabs fun-write-method-returns-function-6 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+greetFunction("Joe") // prints "Hello, Joe"
+```
+{% endtab %}
+{% endtabs %}
+
+恭喜，您刚刚创建了一个返回函数的方法，然后执行了该函数。
+
+## 改进方法
+
+如果您可以传递问候语，我们的方法会更有用，所以让我们这样做。
+您所要做的就是将问候语作为参数传递给 `greet` 方法，并在 `println` 中的字符串中使用它：
+
+{% tabs fun-write-method-returns-function-7 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def greet(theGreeting: String): String => Unit =
+ (name: String) => println(s"$theGreeting, $name")
+```
+{% endtab %}
+{% endtabs %}
+
+现在，当您调用您的方法时，该过程更加灵活，因为您可以更改问候语。
+当您从此方法创建函数时，它是这样的：
+
+{% tabs fun-write-method-returns-function-8 %}
+{% tab 'Scala 2 and 3' %}
+````
+scala> val sayHello = greet("Hello")
+val sayHello: String => Unit = Lambda.....
+ ----------------------
+````
+{% endtab %}
+{% endtabs %}
+
+REPL 类型签名输出显示 `sayHello` 是一个接受 `String` 输入参数并返回 `Unit`（无）的函数。
+所以现在当你给 `sayHello` 一个 `String` 时，它会打印问候语：
+
+{% tabs fun-write-method-returns-function-9 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+sayHello("Joe") // prints "Hello, Joe"
+```
+{% endtab %}
+{% endtabs %}
+
+您还可以根据需要更改问候语以创建新函数：
+
+{% tabs fun-write-method-returns-function-10 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val sayCiao = greet("Ciao")
+val sayHola = greet("Hola")
+
+sayCiao("Isabella") // prints "Ciao, Isabella"
+sayHola("Carlos") // prints "Hola, Carlos"
+```
+{% endtab %}
+{% endtabs %}
+
+## 一个更真实的例子
+
+当您的方法返回许多可能的函数之一时，这种技术会更加有用，例如返回自定义构建函数的工厂。
+
+例如，假设您想编写一个方法，该方法返回用不同语言问候人们的函数。
+我们将其限制为使用英语或法语问候的函数，具体取决于传递给方法的参数。
+
+您知道的第一件事是，您想要创建一个方法，该方法 (a) 将“所需语言”作为输入，并且 (b) 返回一个函数作为其结果。
+此外，由于该函数会打印给定的字符串，因此您知道它的类型为 `String => Unit`。
+使用该信息编写方法签名：
+
+{% tabs fun-write-method-returns-function-11 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def createGreetingFunction(desiredLanguage: String): String => Unit = ???
+```
+{% endtab %}
+{% endtabs %}
+
+接下来，因为您知道可能返回的函数接受一个字符串并打印它，所以您可以为英语和法语编写两个匿名函数：
+
+{% tabs fun-write-method-returns-function-12 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+(name: String) => println(s"你好，$name")
+(name: String) => println(s"Bonjour, $name")
+```
+{% endtab %}
+{% endtabs %}
+
+在方法内部，如果你给这些匿名函数起一些名字，它可能会更易读，所以让我们将它们分配给两个变量：
+
+{% tabs fun-write-method-returns-function-13 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val englishGreeting = (name: String) => println(s"Hello, $name")
+val frenchGreeting = (name: String) => println(s"Bonjour, $name")
+```
+{% endtab %}
+{% endtabs %}
+
+现在您需要做的就是 (a) 如果 `desiredLanguage` 是英语，则返回 `englishGreeting`，并且 (b) 如果 `desiredLanguage` 是法语，则返回 `frenchGreeting`。
+一种方法是使用 `match` 表达式：
+
+{% tabs fun-write-method-returns-function-14 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def createGreetingFunction(desiredLanguage: String): String => Unit = {
+ val englishGreeting = (name: String) => println(s"Hello, $name")
+ val frenchGreeting = (name: String) => println(s"Bonjour, $name")
+ desiredLanguage match {
+ case "english" => englishGreeting
+ case "french" => frenchGreeting
+ }
+}
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+def createGreetingFunction(desiredLanguage: String): String => Unit =
+ val englishGreeting = (name: String) => println(s"Hello, $name")
+ val frenchGreeting = (name: String) => println(s"Bonjour, $name")
+ desiredLanguage match
+ case "english" => englishGreeting
+ case "french" => frenchGreeting
+```
+{% endtab %}
+{% endtabs %}
+
+这是最后的方法。
+请注意，从方法返回函数值与返回字符串或整数没有什么不同呃值。
+
+这就是 `createGreetingFunction` 构建法语问候函数的方式：
+
+{% tabs fun-write-method-returns-function-15 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val greetInFrench = createGreetingFunction("french")
+greetInFrench("Jonathan") // prints "Bonjour, Jonathan"
+```
+{% endtab %}
+{% endtabs %}
+
+这就是它构建英语问候功能的方式：
+
+{% tabs fun-write-method-returns-function-16 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val greetInEnglish = createGreetingFunction("english")
+greetInEnglish("Joe") // prints "Hello, Joe"
+```
+{% endtab %}
+{% endtabs %}
+
+如果你对这段代码感到满意——恭喜——你现在知道如何编写返回函数的方法了。
+
diff --git a/_zh-cn/overviews/scala3-book/interacting-with-java.md b/_zh-cn/overviews/scala3-book/interacting-with-java.md
new file mode 100644
index 0000000000..f2263d0bd2
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/interacting-with-java.md
@@ -0,0 +1,343 @@
+---
+title: 与 Java 交互
+type: chapter
+description: This page demonstrates how Scala code can interact with Java, and how Java code can interact with Scala code.
+language: zh-cn
+num: 72
+previous-page: tools-worksheets
+next-page: scala-for-java-devs
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+## 介绍
+
+本节介绍如何在 Scala 中使用 Java 代码，以及如何在 Java 中使用 Scala 代码。
+
+一般来说，在 Scala 中使用 Java 代码是非常无缝的。
+只有几个地方需要使用 Scala 实用程序将 Java 概念转换为 Scala，包括：
+
+- Java 集合类
+- Java `Optional` 类
+
+同样，如果您正在编写 Java 代码并想使用 Scala 概念，则需要转换 Scala 集合和 Scala `Option` 类。
+
+以下部分演示了您需要的最常见的转换：
+
+- 如何在 Scala 中使用 Java 集合
+- 如何在 Scala 中使用 Java `Optional`
+- 在 Scala 中扩展 Java 接口
+- 如何在 Java 中使用 Scala 集合
+- 如何在 Java 中使用 Scala `Option`
+- 如何在 Java 中使用 Scala traits
+- 如何在 Java 代码中处理 Scala 方法引发的异常
+- 如何在 Java 中使用 Scala 可变参数
+- 创建备用名称以在 Java 中使用 Scala 方法
+
+请注意，本节中的 Java 示例假设您使用的是 Java 11 或更高版本。
+
+## 如何在 Scala 中使用 Java 集合
+
+当您编写 Scala 代码并需要使用 Java 集合类时，您_可以_按原样使用该类。
+但是，如果您想在 Scala `for` 循环中使用该类，或者想利用 Scala 集合类中的高阶函数，则需要将 Java 集合转换为 Scala 集合。
+
+这是一个如何工作的例子。
+假定这个例子是 Java `ArrayList`：
+
+```java
+// java
+public class JavaClass {
+ public static List getStrings() {
+ return new ArrayList(List.of("a", "b", "c"));
+ }
+}
+```
+
+您可以使用 Scala _scala.jdk.CollectionConverters_ 包中的转换实用程序将该 Java 列表转换为 Scala `Seq`：
+
+```scala
+// scala
+import scala.jdk.CollectionConverters.*
+
+def testList() =
+ println("Using a Java List in Scala")
+ val javaList: java.util.List[String] = JavaClass.getStrings()
+ val scalaSeq: Seq[String] = javaList.asScala.toSeq
+ scalaSeq.foreach(println)
+ for s <- scalaSeq do println(s)
+```
+
+当然，该代码可以缩短，但此处显示的各个步骤是为了准确演示转换过程是如何工作的。
+
+## 如何在 Scala 中使用 Java `Optional`
+
+当您需要在 Scala 代码中使用 Java `Optional` 类时，导入 _scala.jdk.OptionConverters_ 对象，然后使用 `toScala` 方法将 `Optional` 值转换为 Scala `Option`。
+
+为了证明这一点，这里有一个带有两个 `Optional` 值的 Java 类，一个包含字符串，另一个为空：
+
+```java
+// java
+import java.util.Optional;
+
+public class JavaClass {
+ static Optional oString = Optional.of("foo");
+ static Optional oEmptyString = Optional.empty();
+}
+```
+
+现在在您的 Scala 代码中，您可以访问这些字段。
+如果您只是直接访问它们，它们都将是 `Optional` 值：
+
+```scala
+// scala
+import java.util.Optional
+
+val optionalString = JavaClass.oString // Optional[foo]
+val eOptionalString = JavaClass.oEmptyString // Optional.empty
+```
+
+但是通过使用 _scala.jdk.OptionConverters_ 方法，您可以将它们转换为 Scala `Option` 值：
+
+```scala
+import java.util.Optional
+import scala.jdk.OptionConverters.*
+
+val optionalString = JavaClass.oString // Optional[foo]
+val optionString = optionalString.toScala // Some(foo)
+
+val eOptionalString = JavaClass.oEmptyString // Optional.empty
+val eOptionString = eOptionalString.toScala // None
+```
+
+## 在 Scala 中扩展 Java 接口
+
+如果您需要在 Scala 代码中使用 Java 接口，请将它们扩展为 Scala trait。
+例如，给定这三个 Java 接口：
+
+```java
+// java
+interface Animal {
+ void speak();
+}
+
+interface Wagging {
+ void wag();
+}
+
+interface Running {
+ // an implemented method
+ default void run() {
+ System.out.println("I’m running");
+ }
+}
+```
+
+你可以在 Scala 中创建一个 `Dog` 类，就像使用 trait 一样。
+你所要做的就是实现 `speak` 和 `wag` 方法：
+
+```scala
+// scala
+class Dog extends Animal, Wagging, Running:
+ def speak = println("Woof")
+ def wag = println("Tail is wagging")
+
+@main def useJavaInterfaceInScala =
+ val d = new Dog
+ d.speak
+ d.wag
+```
+
+## 如何在 Java 中使用 Scala 集合
+
+当您需要在 Java 代码中使用 Scala 集合类时，请在 Java 代码中使用 Scala 的 `scala.jdk.javaapi.CollectionConverters` 对象的方法来进行转换。
+例如，如果您在 Scala 类中有这样的 `List[String]`：
+
+```scala
+// scala
+class ScalaClass:
+ val strings = List("a", "b")
+```
+
+您可以像这样在 Java 代码中访问该 Scala `List`：
+
+```java
+// java
+import scala.jdk.javaapi.CollectionConverters;
+
+// create an instance of the Scala class
+ScalaClass sc = new ScalaClass();
+
+// access the `strings` field as `sc.strings()`
+scala.collection.immutable.List xs = sc.strings();
+
+// convert the Scala `List` a Java `List`
+java.util.List listOfStrings = CollectionConverters.asJava(xs);
+listOfStrings.forEach(System.out::println);
+```
+
+该代码可以缩短，但显示了完整的步骤以演示该过程的工作原理。
+以下是该代码中需要注意的一些事项：
+
+- 在你的 Java 代码中，你创建一个 `ScalaClass` 的实例，就像一个 Java 类的实例一样
+- `ScalaClass` 有一个名为 `strings` 的字段，但在 Java 中，您可以将该字段作为方法访问，即，作为 `sc.strings()`
+
+## 如何在 Java 中使用 Scala `Option`
+
+当您需要在 Java 代码中使用 Scala `Option` 时，可以使用 Scala `scala.jdk.javaapi.OptionConverters` 对象的 `toJava` 方法将 `Option` 转换为 Java `Optional` 值。
+
+为了证明这一点，创建一个具有两个 `Option[String]` 值的 Scala 类，一个包含字符串，另一个为空：
+
+```scala
+// scala
+object ScalaObject:
+ val someString = Option("foo")
+ val noneString: Option[String] = None
+```
+
+然后在您的 Java 代码中，使用来自 `scala.jdk.javaapi.OptionConverters` 对象的 `toJava` 方法将这些 `Option[String]` 值转换为 `java.util.Optional[String]`：
+
+```java
+// java
+import java.util.Optional;
+import static scala.jdk.javaapi.OptionConverters.toJava;
+
+public class JUseScalaOptionInJava {
+ public static void main(String[] args) {
+ Optional stringSome = toJava(ScalaObject.someString()); // Optional[foo]
+ Optional stringNone = toJava(ScalaObject.noneString()); // Optional.empty
+ System.out.printf("stringSome = %s\n", stringSome);
+ System.out.printf("stringNone = %s\n", stringNone);
+ }
+}
+```
+
+两个 Scala `Option` 字段现在可用作 Java `Optional` 值。
+
+## 如何在 Java 中使用 Scala trait
+
+在 Java 11 中，您可以像使用 Java 接口一样使用 Scala trait，即使 trait 已经实现了方法。
+例如，给定这两个 Scala trait，一个具有已实现的方法，一个只有一个接口：
+
+```scala
+// scala
+trait ScalaAddTrait:
+ def sum(x: Int, y: Int) = x + y // implemented
+
+trait ScalaMultiplyTrait:
+ def multiply(x: Int, y: Int): Int // abstract
+```
+
+Java 类可以实现这两个接口，并定义 `multiply` 方法：
+
+```java
+// java
+class JavaMath implements ScalaAddTrait, ScalaMultiplyTrait {
+ public int multiply(int a, int b) {
+ return a * b;
+ }
+}
+
+JavaMath jm = new JavaMath();
+System.out.println(jm.sum(3,4)); // 7
+System.out.println(jm.multiply(3,4)); // 12
+```
+
+## 如何处理在 Java 代码中抛出异常的 Scala 方法
+
+当您使用 Scala 编程习惯编写 Scala 代码时，您永远不会编写引发异常的方法。
+但是如果由于某种原因你有一个抛出异常的 Scala 方法，并且你希望 Java 开发人员能够使用该方法，请在你的 Scala 方法中添加`@throws`注解，以便 Java 使用者知道它可以抛出的异常.
+
+例如，注解这个 Scala `exceptionThrower` 方法抛出一个 `Exception`：
+
+```scala
+// scala
+object SExceptionThrower:
+ @throws(classOf[Exception])
+ def exceptionThrower =
+ throw new Exception("Idiomatic Scala methods don’t throw exceptions")
+```
+
+因此，您需要处理 Java 代码中的异常。
+例如，这段代码不会编译，因为我不处理异常：
+
+```java
+// java: won’t compile because the exception isn’t handled
+public class ScalaExceptionsInJava {
+ public static void main(String[] args) {
+ SExceptionThrower.exceptionThrower();
+ }
+}
+```
+
+编译器给出了这个错误：
+
+````
+[error] ScalaExceptionsInJava: unreported exception java.lang.Exception;
+ must be caught or declared to be thrown
+[error] SExceptionThrower.exceptionThrower()
+````
+
+这很好——这就是你想要的：注解告诉 Java 编译器 `exceptionThrower` 可以抛出异常。
+现在，当您编写 Java 代码时，您必须使用 `try` 块处理异常或声明您的 Java 方法抛出异常。
+
+相反，如果你 Scala `exceptionThrower` 方法的注释，Java 代码_将编译_。
+这可能不是您想要的，因为 Java 代码可能无法考虑引发异常的 Scala 方法。
+
+## 如何在 Java 中使用 Scala 可变参数
+
+当 Scala 方法具有可变参数并且您想在 Java 中使用该方法时，请使用 `@varargs` 注解来标记 Scala 方法。
+例如，这个 Scala 类中的 `printAll` 方法声明了一个 `String*` 可变参数字段：
+
+```scala
+// scala
+import scala.annotation.varargs
+
+object VarargsPrinter:
+ @varargs def printAll(args: String*): Unit = args.foreach(println)
+```
+
+因为 `printAll` 是用 `@varargs` 注释声明的，所以可以从具有可变数量参数的 Java 程序中调用它，如下例所示：
+
+```scala
+// java
+public class JVarargs {
+ public static void main(String[] args) {
+ VarargsPrinter.printAll("Hello", "world");
+ }
+}
+```
+
+运行此代码时，结果在以下输出中：
+
+````
+Hello
+world
+````
+
+## 创建备用名称以在 Java 中使用 Scala 方法
+
+在 Scala 中，您可能希望使用符号字符创建方法名称：
+
+```scala
+def +(a: Int, b: Int) = a + b
+```
+
+该方法名称在 Java 中不能很好地工作，但您可以在 Scala 3 中为该方法提供一个“替代”名称——别名——这将在 Java 中工作：
+
+```scala
+import scala.annotation.targetName
+
+class Adder:
+ @targetName("add") def +(a: Int, b: Int) = a + b
+```
+
+现在在您的 Java 代码中，您可以使用别名方法名称 `add`：
+
+```scala
+var adder = new Adder();
+int x = adder.add(1,1);
+System.out.printf("x = %d\n", x);
+```
diff --git a/_zh-cn/overviews/scala3-book/introduction.md b/_zh-cn/overviews/scala3-book/introduction.md
new file mode 100644
index 0000000000..2e82050a0e
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/introduction.md
@@ -0,0 +1,35 @@
+---
+title: 导言
+type: chapter
+description: This page begins the overview documentation of the Scala 3 language.
+language: zh-cn
+num: 1
+previous-page:
+next-page: scala-features
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+欢迎阅读《Scala 3》一书。
+本书的目标是提供对 Scala 语言的非正式介绍，并以相对轻松的方式涉及所有的 Scala 主题。
+若您在阅读本书时想了解有关特定功能的更多信息，可以随时参阅[_参考文档_][reference]，其中更详细地涵盖了 Scala 语言的许多新特性。
+
+ def main(args: Array[String]): Unit =
+ try
+ happyBirthday(
+ CLP.parseArgument[Int](args, 0),
+ CLP.parseArgument[String](args, 1),
+ CLP.parseRemainingArguments[String](args, 2))
+ catch {
+ case error: CLP.ParseError => CLP.showError(error)
+ }
+}
+```
+
+> **注意**：在这个生成的代码中，`` 修饰符表示 `main` 方法是作为 `happyBirthday` 类的静态方法生成的。
+> 此功能不适用于 Scala 中的用户程序。
+> 常规“静态”成员在 Scala 中使用对象生成。
+
+{% endtab %}
+{% endtabs %}
+
+## 与 Scala 2 的向后兼容性
+
+`@main` 方法是在 Scala 3 中生成可以从命令行调用的程序的推荐方法。
+它们取代了 Scala 2 中以前的方法，即创建一个扩展 `App` 类的 `object` ：
+
+之前依赖于“神奇”的 `DelayedInit` trait 的 `App` 功能不再可用。
+`App` 目前仍以有限的形式存在，但它不支持命令行参数，将来会被弃用。
+
+如果程序需要在 Scala 2 和 Scala 3 之间交叉构建，建议使用带有 `Array[String]` 参数的显式 `main` 方法：
+
+{% tabs method_4 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+object happyBirthday {
+ private def happyBirthday(age: Int, name: String, others: String*) = {
+ ... // same as before
+ }
+ def main(args: Array[String]): Unit =
+ happyBirthday(args(0).toInt, args(1), args.drop(2).toIndexedSeq:_*)
+}
+```
+
+> 注意我们用 `:_*` 来传递不定数量的参数。为了保持向后兼容性，Scala 3 保持了这种用法。
+
+{% endtab %}
+{% endtabs %}
+
+如果将该代码放在名为 *happyBirthday.scala* 的文件中，则可以使用 `scalac` 编译它并使用 `scala` 运行它，如前所示：
+
+```bash
+$ scalac happyBirthday.scala
+
+$ scala happyBirthday 23 Lisa Peter
+Happy 23rd Birthday, Lisa and Peter!
+```
diff --git a/_zh-cn/overviews/scala3-book/methods-most.md b/_zh-cn/overviews/scala3-book/methods-most.md
new file mode 100644
index 0000000000..86d78f7960
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/methods-most.md
@@ -0,0 +1,700 @@
+---
+title: 方法特性
+type: section
+description: This section introduces Scala 3 methods, including main methods, extension methods, and more.
+language: zh-cn
+num: 25
+previous-page: methods-intro
+next-page: methods-main-methods
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本节介绍如何在 Scala 3 中定义和调用方法的各个方面。
+
+## 定义方法
+
+Scala 方法有很多特性，包括：
+
+- 泛型（类型）参数
+- 参数的默认值
+- 多个参数组（柯里化）
+- 上下文提供的参数
+- 传名参数
+- ...
+
+本节演示了其中一些功能，但是当您定义一个不使用这些功能的“简单”方法时，语法如下所示：
+
+{% tabs method_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_1 %}
+
+```scala
+def methodName(param1: Type1, param2: Type2): ReturnType = {
+ // the method body
+ // goes here
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_1 %}
+
+```scala
+def methodName(param1: Type1, param2: Type2): ReturnType =
+ // the method body
+ // goes here
+end methodName // this is optional
+```
+
+{% endtab %}
+{% endtabs %}
+
+在该语法中：
+
+- 关键字 `def` 用于定义方法
+- Scala 标准是使用驼峰式命法来命名方法
+- 方法参数总是和它们的类型一起定义
+- 声明方法返回类型是可选的
+- 方法可以包含多行，也可以只包含一行
+- 在方法体之后提供 `end methodName` 部分也是可选的，仅推荐用于长方法
+
+下面是一个名为 `add` 的单行方法的两个示例，它接受两个 `Int` 输入参数。
+第一个版本明确显示方法的 `Int` 返回类型，第二个版本没有：
+
+{% tabs method_2 %}
+{% tab 'Scala 2 and 3' for=method_2 %}
+
+```scala
+def add(a: Int, b: Int): Int = a + b
+def add(a: Int, b: Int) = a + b
+```
+
+{% endtab %}
+{% endtabs %}
+
+建议使用返回类型注释公开可见的方法。
+声明返回类型可以让您在几个月或几年后查看它或查看其他人的代码时更容易理解它。
+
+## 调用方法
+
+调用方法很简单：
+
+{% tabs method_3 %}
+{% tab 'Scala 2 and 3' for=method_3 %}
+
+```scala
+val x = add(1, 2) // 3
+```
+
+{% endtab %}
+{% endtabs %}
+
+Scala 集合类有几十个内置方法。
+这些示例显示了如何调用它们：
+
+{% tabs method_4 %}
+{% tab 'Scala 2 and 3' for=method_4 %}
+
+```scala
+val x = List(1, 2, 3)
+
+x.size // 3
+x.contains(1) // true
+x.map(_ * 10) // List(10, 20, 30)
+```
+
+{% endtab %}
+{% endtabs %}
+
+注意：
+
+- `size` 不带参数，并返回列表中元素的数量
+- `contains` 方法接受一个参数，即要搜索的值
+- `map` 接受一个函数参数；在上述情况下，传递给它的是一个匿名函数
+
+## 多行方法
+
+当方法超过一行时，从第二行开始方法体，向右缩进：
+
+{% tabs method_5 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_5 %}
+
+```scala
+def addThenDouble(a: Int, b: Int): Int = {
+ // imagine that this body requires multiple lines
+ val sum = a + b
+ sum * 2
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_5 %}
+
+```scala
+def addThenDouble(a: Int, b: Int): Int =
+ // imagine that this body requires multiple lines
+ val sum = a + b
+ sum * 2
+```
+
+{% endtab %}
+{% endtabs %}
+
+在那个方法中：
+
+- `sum` 是一个不可变的局部变量；它不能在方法之外访问
+- 最后一行将 `sum` 的值加倍；这个值是从方法返回的
+
+当您将该代码粘贴到 REPL 中时，您会看到它按预期工作：
+
+{% tabs method_6 %}
+{% tab 'Scala 2 and 3' for=method_6 %}
+
+```scala
+scala> addThenDouble(1, 1)
+res0: Int = 4
+```
+
+{% endtab %}
+{% endtabs %}
+
+请注意，方法末尾不需要 `return` 语句。
+因为在 Scala 中几乎所有的东西都是一个_表达式_——意味着每一行代码都返回（或_执行_）一个值——不需要使用 `return`。
+
+当您压缩该方法并将其写在一行上时，这一点变得更加清晰：
+
+{% tabs method_7 %}
+{% tab 'Scala 2 and 3' for=method_7 %}
+
+```scala
+def addThenDouble(a: Int, b: Int): Int = (a + b) * 2
+```
+
+{% endtab %}
+{% endtabs %}
+
+方法的主体可以使用语言的所有不同特性：
+
+- `if`/`else` 表达式
+- `match` 表达式
+- `while` 循环
+- `for` 循环和 `for` 表达式
+- 变量赋值
+- 调用其他方法
+- 其他方法的定义
+
+作为一个真实世界的多行方法的例子，这个 `getStackTraceAsString` 方法将它的 `Throwable` 输入参数转换成一个格式良好的 `String`：
+
+{% tabs method_8 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_8 %}
+
+```scala
+def getStackTraceAsString(t: Throwable): String = {
+ val sw = new StringWriter()
+ t.printStackTrace(new PrintWriter(sw))
+ sw.toString
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_8 %}
+
+```scala
+def getStackTraceAsString(t: Throwable): String =
+ val sw = StringWriter()
+ t.printStackTrace(PrintWriter(sw))
+ sw.toString
+```
+
+{% endtab %}
+{% endtabs %}
+
+在那个方法中：
+
+- 第一行将 `StringWriter` 的新实例分配给值绑定器 `sw`
+- 第二行将堆栈跟踪内容存储到 `StringWriter`
+- 第三行产生堆栈跟踪的 `String` 表示
+
+## 默认参数值
+
+方法参数可以有默认值。
+在此示例中，为 `timeout` 和 `protocol` 参数提供了默认值：
+
+{% tabs method_9 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_9 %}
+
+```scala
+def makeConnection(timeout: Int = 5_000, protocol: String = "http") = {
+ println(f"timeout = ${timeout}%d, protocol = ${protocol}%s")
+ // more code here ...
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_9 %}
+
+```scala
+def makeConnection(timeout: Int = 5_000, protocol: String = "http") =
+ println(f"timeout = ${timeout}%d, protocol = ${protocol}%s")
+ // more code here ...
+```
+
+{% endtab %}
+{% endtabs %}
+
+由于参数具有默认值，因此可以通过以下方式调用该方法：
+
+{% tabs method_10 %}
+{% tab 'Scala 2 and 3' for=method_10 %}
+
+```scala
+makeConnection() // timeout = 5000, protocol = http
+makeConnection(2_000) // timeout = 2000, protocol = http
+makeConnection(3_000, "https") // timeout = 3000, protocol = https
+```
+
+{% endtab %}
+{% endtabs %}
+
+以下是关于这些示例的一些要点：
+
+- 在第一个示例中，没有提供任何参数，因此该方法使用默认参数值 `5_000` 和 `http`
+- 在第二个示例中，为 `timeout` 值提供了 `2_000`，因此它与 `protocol` 的默认值一起使用
+- 在第三个示例中，为两个参数提供了值，因此它们都被使用
+
+请注意，通过使用默认参数值，消费者似乎可以使用三种不同的重载方法。
+
+## 命名参数
+
+如果您愿意，也可以在调用方法时使用方法参数的名称。
+例如，`makeConnection` 也可以通过以下方式调用：
+
+{% tabs method_11 %}
+{% tab 'Scala 2 and 3' for=method_11 %}
+
+```scala
+makeConnection(timeout=10_000)
+makeConnection(protocol="https")
+makeConnection(timeout=10_000, protocol="https")
+makeConnection(protocol="https", timeout=10_000)
+```
+
+{% endtab %}
+{% endtabs %}
+
+在某些框架中，命名参数被大量使用。
+当多个方法参数具有相同类型时，它们也非常有用：
+
+{% tabs method_12 %}
+{% tab 'Scala 2 and 3' for=method_12 %}
+
+```scala
+engage(true, true, true, false)
+```
+
+{% endtab %}
+{% endtabs %}
+
+如果没有 IDE 的帮助，代码可能难以阅读，但这段代码更加清晰和明显：
+
+{% tabs method_13 %}
+{% tab 'Scala 2 and 3' for=method_13 %}
+
+```scala
+engage(
+ speedIsSet = true,
+ directionIsSet = true,
+ picardSaidMakeItSo = true,
+ turnedOffParkingBrake = false
+)
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 关于不带参数的方法的建议
+
+当一个方法不带参数时，它的 _arity_ 级别为 _arity-0_。
+类似地，当一个方法采用一个参数时，它是一个_arity-1_方法。
+当您创建 arity-0 方法时：
+
+- 如果方法执行副作用，例如调用`println`，用空括号声明方法
+- 如果该方法不执行副作用——例如获取集合的大小，这类似于访问集合上的字段——请去掉括号
+
+例如，这个方法会产生副作用，所以它用空括号声明：
+
+{% tabs method_14 %}
+{% tab 'Scala 2 and 3' for=method_14 %}
+
+```scala
+def speak() = println("hi")
+```
+
+{% endtab %}
+{% endtabs %}
+
+这样做需要方法的调用者在调用方法时使用括号：
+
+{% tabs method_15 %}
+{% tab 'Scala 2 and 3' for=method_15 %}
+
+```scala
+speak // error: "method speak must be called with () argument"
+speak() // prints "hi"
+```
+
+{% endtab %}
+{% endtabs %}
+
+虽然这只是一个约定，但遵循它可以显着提高代码的可读性：它可以让您更容易一目了然地理解 arity-0 方法执行副作用。
+
+{% comment %}
+Some of that wording comes from this page: https://docs.scala-lang.org/style/method-invocation.html
+{% endcomment %}
+
+## 使用 `if` 作为方法体
+
+因为 `if`/`else` 表达式返回一个值，所以它们可以用作方法的主体。
+这是一个名为 `isTruthy` 的方法，它实现了 Perl 对 `true` 和 `false` 的定义：
+
+{% tabs method_16 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_16 %}
+
+```scala
+def isTruthy(a: Any) = {
+ if (a == 0 || a == "" || a == false)
+ false
+ else
+ true
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_16 %}
+
+```scala
+def isTruthy(a: Any) =
+ if a == 0 || a == "" || a == false then
+ false
+ else
+ true
+```
+
+{% endtab %}
+{% endtabs %}
+
+这些示例显示了该方法的工作原理：
+
+{% tabs method_17 %}
+{% tab 'Scala 2 and 3' for=method_17 %}
+
+```scala
+isTruthy(0) // false
+isTruthy("") // false
+isTruthy("hi") // true
+isTruthy(1.0) // true
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 使用 `match` 作为方法体
+
+`match` 表达式也可以用作整个方法体，而且经常如此。
+这是 `isTruthy` 的另一个版本，用 `match` 表达式编写：
+
+{% tabs method_18 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_18 %}
+
+```scala
+def isTruthy(a: Any) = a match {
+ case 0 | "" | false => false
+ case _ => true
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_18 %}
+
+```scala
+def isTruthy(a: Matchable) = a match
+ case 0 | "" | false => false
+ case _ => true
+```
+
+> 此方法的工作方式与之前使用 `if`/`else` 表达式的方法一样。我们使用 `Matchable` 而不是 `Any` 作为参数的类型来接受任何支持模式匹配的值。
+
+> 有关 `Matchable` trait 的更多详细信息，请参阅 [参考文档][reference_matchable]。
+
+[reference_matchable]: {{ site.scala3ref }}/other-new-features/matchable.html
+{% endtab %}
+{% endtabs %}
+
+## 控制类中的可见性
+
+在类、对象、trait和枚举中，Scala 方法默认是公共的，所以这里创建的 `Dog` 实例可以访问 `speak` 方法：
+
+{% tabs method_19 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_19 %}
+
+```scala
+class Dog {
+ def speak() = println("Woof")
+}
+
+val d = new Dog
+d.speak() // prints "Woof"
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_19 %}
+
+```scala
+class Dog:
+ def speak() = println("Woof")
+
+val d = new Dog
+d.speak() // prints "Woof"
+```
+
+{% endtab %}
+{% endtabs %}
+
+方法也可以标记为 `private`。
+这使得它们对当前类是私有的，因此它们不能在子类中被调用或重载：
+
+{% tabs method_20 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_20 %}
+
+```scala
+class Animal {
+ private def breathe() = println("I’m breathing")
+}
+
+class Cat extends Animal {
+ // this method won’t compile
+ override def breathe() = println("Yo, I’m totally breathing")
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_20 %}
+
+```scala
+class Animal:
+ private def breathe() = println("I’m breathing")
+
+class Cat extends Animal:
+ // this method won’t compile
+ override def breathe() = println("Yo, I’m totally breathing")
+```
+
+{% endtab %}
+{% endtabs %}
+
+如果你想让一个方法对当前类私有，并且允许子类调用它或覆盖它，将该方法标记为 `protected`，如本例中的 `speak` 方法所示：
+
+{% tabs method_21 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_21 %}
+
+```scala
+class Animal {
+ private def breathe() = println("I’m breathing")
+ def walk() = {
+ breathe()
+ println("I’m walking")
+ }
+ protected def speak() = println("Hello?")
+}
+
+class Cat extends Animal {
+ override def speak() = println("Meow")
+}
+
+val cat = new Cat
+cat.walk()
+cat.speak()
+cat.breathe() // won’t compile because it’s private
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_21 %}
+
+```scala
+class Animal:
+ private def breathe() = println("I’m breathing")
+ def walk() =
+ breathe()
+ println("I’m walking")
+ protected def speak() = println("Hello?")
+
+class Cat extends Animal:
+ override def speak() = println("Meow")
+
+val cat = new Cat
+cat.walk()
+cat.speak()
+cat.breathe() // won’t compile because it’s private
+```
+
+{% endtab %}
+{% endtabs %}
+
+`protected` 设置意味着：
+
+- 方法（或字段）可以被同一类的其他实例访问
+- 对当前包中的其他代码是不可见的
+- 它适用于子类
+
+## 对象可以包含方法
+
+之前你看到trait和类可以有方法。
+Scala `object` 关键字用于创建单例类，对象也可以包含方法。
+这是对一组“实用程序”方法进行分组的好方法。
+例如，此对象包含一组处理字符串的方法：
+
+{% tabs method_22 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_22 %}
+
+```scala
+object StringUtils {
+
+ /**
+ * Returns a string that is the same as the input string, but
+ * truncated to the specified length.
+ */
+ def truncate(s: String, length: Int): String = s.take(length)
+
+ /**
+ * Returns true if the string contains only letters and numbers.
+ */
+ def lettersAndNumbersOnly_?(s: String): Boolean =
+ s.matches("[a-zA-Z0-9]+")
+
+ /**
+ * Returns true if the given string contains any whitespace
+ * at all. Assumes that `s` is not null.
+ */
+ def containsWhitespace(s: String): Boolean =
+ s.matches(".*\\s.*")
+
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_22 %}
+
+```scala
+object StringUtils:
+
+ /**
+ * Returns a string that is the same as the input string, but
+ * truncated to the specified length.
+ */
+ def truncate(s: String, length: Int): String = s.take(length)
+
+ /**
+ * Returns true if the string contains only letters and numbers.
+ */
+ def lettersAndNumbersOnly_?(s: String): Boolean =
+ s.matches("[a-zA-Z0-9]+")
+
+ /**
+ * Returns true if the given string contains any whitespace
+ * at all. Assumes that `s` is not null.
+ */
+ def containsWhitespace(s: String): Boolean =
+ s.matches(".*\\s.*")
+
+end StringUtils
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 扩展方法
+
+扩展方法在上下文抽象一章的[扩展方法部分][extension]中讨论。
+有很多情况，你想向封闭类添加功能。
+如该部分所示，假设您有一个 `Circle` 类，但您无法更改其源代码。
+例如，它可以在第三方库中这样定义：
+
+{% tabs method_23 %}
+{% tab 'Scala 2 and 3' for=method_23 %}
+
+```scala
+case class Circle(x: Double, y: Double, radius: Double)
+```
+
+{% endtab %}
+{% endtabs %}
+
+当你想给这个类添加方法时，你可以将它们定义为扩展方法，像这样：
+
+{% tabs method_24 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_24 %}
+
+```scala
+implicit class CircleOps(c: Circle) {
+ def circumference: Double = c.radius * math.Pi * 2
+ def diameter: Double = c.radius * 2
+ def area: Double = math.Pi * c.radius * c.radius
+}
+```
+在 Scala 2 中使用 `implicit class`，在[这](/overviews/core/implicit-classes.html)找到更多细节。
+
+{% endtab %}
+{% tab 'Scala 3' for=method_24 %}
+
+```scala
+extension (c: Circle)
+ def circumference: Double = c.radius * math.Pi * 2
+ def diameter: Double = c.radius * 2
+ def area: Double = math.Pi * c.radius * c.radius
+```
+在 Scala 3 中使用新的 `extension` 结构。更多细节可以看[本书][extension]的章节，或者 [Scala 3 参考][reference-ext]。
+
+[reference-ext]: {{ site.scala3ref }}/contextual/extension-methods.html
+[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}
+{% endtab %}
+{% endtabs %}
+
+现在，当您有一个名为 `aCircle` 的 `Circle` 实例时，您可以像这样调用这些方法：
+
+{% tabs method_25 %}
+{% tab 'Scala 2 and 3' for=method_25 %}
+
+```scala
+aCircle.circumference
+aCircle.diameter
+aCircle.area
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 更多
+
+还有更多关于方法的知识，包括如何：
+
+- 调用超类的方法
+- 定义和使用传名参数
+- 编写一个带有函数参数的方法
+- 创建内嵌方法
+- 处理异常
+- 使用可变参数作为输入参数
+- 编写具有多个参数组的方法（部分应用的函数）
+- 创建具有泛型类型参数的方法
+
+{% comment %}
+Jamie: there really needs better linking here - previously it was to the Scala 3 Reference, which doesnt cover any
+of this
+{% endcomment %}
+
+有关这些特性的更多详细信息，请看本书其它章节。
+
+[reference_extension_methods]: {{ site.scala3ref }}/contextual/extension-methods.html
+[reference_matchable]: {{ site.scala3ref }}/other-new-features/matchable.html
diff --git a/_zh-cn/overviews/scala3-book/methods-summary.md b/_zh-cn/overviews/scala3-book/methods-summary.md
new file mode 100644
index 0000000000..472c6230a1
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/methods-summary.md
@@ -0,0 +1,28 @@
+---
+title: 总结
+type: section
+description: This section summarizes the previous sections on Scala 3 methods.
+language: zh-cn
+num: 27
+previous-page: methods-main-methods
+next-page: fun-intro
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+还有更多关于方法的知识，包括如何：
+
+- 调用超类的方法
+- 定义和使用按名称参数
+- 编写一个带有函数参数的方法
+- 创建内嵌方法
+- 处理异常
+- 使用可变参数输入参数
+- 编写具有多个参数组的方法（部分应用的函数）
+- 创建具有泛型类型参数的方法
+
+[reference]: {{ site.scala3ref }}/overview.html
diff --git a/_zh-cn/overviews/scala3-book/packaging-imports.md b/_zh-cn/overviews/scala3-book/packaging-imports.md
new file mode 100644
index 0000000000..bc928dbe67
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/packaging-imports.md
@@ -0,0 +1,632 @@
+---
+title: 打包和导入
+type: chapter
+description: A discussion of using packages and imports to organize your code, build related modules of code, control scope, and help prevent namespace collisions.
+language: zh-cn
+num: 36
+previous-page: fun-summary
+next-page: collections-intro
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 使用 *包* 创建命名空间，让您可以模块化程序并帮助防止命名空间冲突。
+Scala 支持 Java 使用的包命名样式，也支持 C++ 和 C# 等语言使用的“花括号”命名空间表示法。
+
+Scala 导入成员的方法也类似于 Java，并且更灵活。
+使用 Scala，您可以：
+
+- 导入包、类、对象、traits 和方法
+- 将导入语句放在任何地方
+- 导入成员时隐藏和重命名成员
+
+这些特性在以下示例中进行了演示。
+
+## 创建一个包
+
+通过在 Scala 文件的顶部声明一个或多个包名称来创建包。
+例如，当您的域名是 _acme.com_ 并且您正在使用名为 _myapp_ 的应用程序中的 _model_ 包中工作时，您的包声明如下所示：
+
+{% tabs packaging-imports-0 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+package com.acme.myapp.model
+
+class Person ...
+```
+{% endtab %}
+{% endtabs %}
+
+按照约定，包名应全部小写，正式命名约定为 *\.\.\.\*。
+
+虽然不是必需的，但包名称通常遵循目录结构名称，因此如果您遵循此约定，则此项目中的 `Person` 类将在 *MyApp/src/main/scala/com/acme/myapp/model/Person.scala* 文件中找到。
+
+### 在同一个文件中使用多个包
+
+上面显示的语法适用于整个源文件：文件中的所有定义
+`Person.scala` 属于 `com.acme.myapp.model` 包，根据包子句
+在文件的开头。
+
+或者，可以编写仅适用于定义的包子句
+他们包含：
+
+{% tabs packaging-imports-1 class=tabs-scala-version %}
+{% tab 'Scala 2' %}```scala
+package users {
+
+ package administrators { // the full name of this package is users.administrators
+ class AdminUser // the full name of this class users.administrators.AdminUser
+ }
+ package normalusers { // the full name of this package is users.normalusers
+ class NormalUser // the full name of this class is users.normalusers.NormalUser
+ }
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-1 %}
+
+```scala
+package users:
+
+ package administrators: // the full name of this package is users.administrators
+ class AdminUser // the full name of this class is users.administrators.AdminUser
+
+ package normalusers: // the full name of this package is users.normalusers
+ class NormalUser // the full name of this class is users.normalusers.NormalUser
+```
+{% endtab %}
+{% endtabs %}
+
+请注意，包名称后跟一个冒号，并且其中的定义
+一个包是缩进的。
+
+这种方法的优点是它允许包嵌套，并提供更明显的范围和封装控制，尤其是在同一个文件中。
+
+## 导入语句，第 1 部分
+
+导入语句用于访问其他包中的实体。
+导入语句分为两大类：
+
+- 导入类、trait、对象、函数和方法
+- 导入 `given` 子句
+
+如果您习惯于 Java 之类的语言，则第一类 import 语句与 Java 使用的类似，只是语法略有不同，因此具有更大的灵活性。
+这些示例展示了其中的一些灵活性：
+
+{% tabs packaging-imports-2 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import users._ // import everything from the `users` package
+import users.User // import only the `User` class
+import users.{User, UserPreferences} // import only two selected members
+import users.{UserPreferences as UPrefs} // rename a member as you import it
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-2 %}
+
+```scala
+import users.* // import everything from the `users` package
+import users.User // import only the `User` class
+import users.{User, UserPreferences} // import only two selected members
+import users.{UserPreferences as UPrefs} // rename a member as you import it
+```
+
+{% endtab %}
+{% endtabs %}
+
+这些示例旨在让您了解第一类 `import` 语句的工作原理。
+在接下来的小节中对它们进行了更多解释。
+
+导入语句还用于将 `given` 实例导入本范围。
+这些将在本章末尾讨论。
+
+继续之前的注意事项：
+
+> 访问同一包的成员不需要导入子句。
+
+### 导入一个或多个成员
+
+在 Scala 中，您可以从包中导入一个成员，如下所示：
+
+{% tabs packaging-imports-3 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+import scala.concurrent.Future
+```
+{% endtab %}
+{% endtabs %}
+
+和这样的多个成员：
+
+{% tabs packaging-imports-4 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+import scala.concurrent.Future
+import scala.concurrent.Promise
+import scala.concurrent.blocking
+```
+{% endtab %}
+{% endtabs %}
+
+导入多个成员时，您可以像这样更简洁地导入它们：
+
+{% tabs packaging-imports-5 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+import scala.concurrent.{Future, Promise, blocking}
+```
+{% endtab %}
+{% endtabs %}
+
+当您想从 *scala.concurrent* 包中导入所有内容时，请使用以下语法：
+
+{% tabs packaging-imports-6 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import scala.concurrent._
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-6 %}
+
+```scala
+import scala.concurrent.*
+```
+{% endtab %}
+{% endtabs %}
+
+### 在导入时重命名成员
+
+有时，在导入实体时重命名实体会有所帮助，以避免名称冲突。
+例如，如果您想同时使用 Scala `List` 类和 *java.util.List* 类，可以在导入时重命名 *java.util.List* 类：
+
+{% tabs packaging-imports-7 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import java.util.{List => JavaList}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-7 %}
+
+```scala
+import java.util.{List as JavaList}
+```
+{% endtab %}
+{% endtabs %}
+
+现在您使用名称 `JavaList` 来引用该类，并使用 `List` 来引用 Scala 列表类。
+
+您还可以使用以下语法一次重命名多个成员：
+
+{% tabs packaging-imports-8 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import java.util.{Date => JDate, HashMap => JHashMap, _}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-8 %}
+
+```scala
+import java.util.{Date as JDate, HashMap as JHashMap, *}
+```
+
+{% endtab %}
+{% endtabs %}
+
+那行代码说，“重命名 `Date` 和 `HashMap` 类，如图所示，并导入 _java.util_ 包中的所有其他内容，而不重命名任何其他成员。”
+
+### 在导入时隐藏成员
+
+您还可以在导入过程中*隐藏*成员。
+这个 `import` 语句隐藏了 *java.util.Random* 类，同时导入 *java.util 中的所有其他内容* 包裹：
+
+{% tabs packaging-imports-9 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import java.util.{Random => _, _}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-9 %}
+
+```scala
+import java.util.{Random as _, *}
+```
+{% endtab %}
+{% endtabs %}
+
+如果您尝试访问 `Random` 类，它将无法正常工作，但您可以访问该包中的所有其他成员：
+
+{% tabs packaging-imports-10 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val r = new Random // won’t compile
+new ArrayList // works
+```
+{% endtab %}
+{% endtabs %}
+
+#### 隐藏多个成员
+
+要在导入过程中隐藏多个成员，请在使用最终通配符导入之前列出它们：
+
+{% tabs packaging-imports-11 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+scala> import java.util.{List => _, Map => _, Set => _, _}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-11 %}
+
+```scala
+scala> import java.util.{List as _, Map as _, Set as _, *}
+```
+{% endtab %}
+{% endtabs %}
+
+这些类再次被隐藏，但您可以使用 *java.util* 中的所有其他类：
+
+{% tabs packaging-imports-12 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> new ArrayList[String]
+val res0: java.util.ArrayList[String] = []
+```
+{% endtab %}
+{% endtabs %}
+
+因为这些 Java 类是隐藏的，所以您也可以使用 Scala 的 `List`、`Set` 和 `Map` 类而不会发生命名冲突：
+
+{% tabs packaging-imports-13 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val a = List(1, 2, 3)
+val a: List[Int] = List(1, 2, 3)
+
+scala> val b = Set(1, 2, 3)
+val b: Set[Int] = Set(1, 2, 3)
+
+scala> val c = Map(1 -> 1, 2 -> 2)
+val c: Map[Int, Int] = Map(1 -> 1, 2 -> 2)
+```
+{% endtab %}
+{% endtabs %}
+
+### 在任何地方使用导入
+
+在 Scala 中，`import` 语句可以在任何地方。
+它们可以在源代码文件的顶部使用：
+
+{% tabs packaging-imports-14 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+package foo
+
+import scala.util.Random
+
+class ClassA {
+ def printRandom(): Unit = {
+ val r = new Random // use the imported class
+ // more code here...
+ }
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-14 %}
+
+```scala
+package foo
+
+import scala.util.Random
+
+class ClassA:
+ def printRandom:
+ val r = new Random // use the imported class
+ // more code here...
+```
+{% endtab %}
+{% endtabs %}
+
+如果您愿意，您还可以使用更接近需要它们的点的 `import` 语句：
+
+{% tabs packaging-imports-15 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+package foo
+
+class ClassA {
+ import scala.util.Random // inside ClassA
+ def printRandom(): Unit = {
+ val r = new Random
+ // more code here...
+ }
+}
+
+class ClassB {
+ // the Random class is not visible here
+ val r = new Random // this code will not compile
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-15 %}
+
+```scala
+package foo
+
+class ClassA:
+ import scala.util.Random // inside ClassA
+ def printRandom {
+ val r = new Random
+ // more code here...
+
+class ClassB:
+ // the Random class is not visible here
+ val r = new Random // this code will not compile
+```
+
+{% endtab %}
+{% endtabs %}
+
+### “静态”导入
+
+当您想以类似于 Java “静态导入”方法的方式导入成员时——因此您可以直接引用成员名称，而不必在它们前面加上类名——使用以下方法。
+
+使用此语法导入 Java `Math` 类的所有静态成员：
+
+{% tabs packaging-imports-16 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import java.lang.Math._
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-16 %}
+
+```scala
+import java.lang.Math.*
+```
+{% endtab %}
+{% endtabs %}
+
+现在您可以访问静态的 `Math` 类方法，例如 `sin` 和 `cos`，而不必在它们前面加上类名：
+
+{% tabs packaging-imports-17 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+import java.lang.Math._
+
+val a = sin(0) // 0.0
+val b = cos(PI) // -1.0
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-17 %}
+
+```scala
+import java.lang.Math.*
+
+val a = sin(0) // 0.0
+val b = cos(PI) // -1.0
+```
+{% endtab %}
+{% endtabs %}
+
+### 默认导入的包
+
+两个包被隐式导入到所有源代码文件的范围内：
+
+- java.lang.*
+- scala.*
+
+Scala 对象 `Predef` 的成员也是默认导入的。
+
+> 如果您想知道为什么可以使用 `List`、`Vector`、`Map` 等类，而无需导入它们，它们是可用的，因为 `Predef` 对象中的定义。
+
+### 处理命名冲突
+
+在极少数情况下会出现命名冲突，您需要从项目的根目录导入一些东西，在包名前加上 `_root_`：
+
+{% tabs packaging-imports-18 class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+package accounts
+
+import _root_.accounts._
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=packaging-imports-18 %}
+
+```scala
+package accounts
+
+import _root_.accounts.*
+```
+{% endtab %}
+{% endtabs %}
+
+## 导入 `given` 实例
+
+正如您将在 [上下文抽象][contextual] 一章中看到的，`import` 语句的一种特殊形式用于导入 `given` 实例。
+基本形式如本例所示：
+
+{% tabs packaging-imports-19 %}
+{% tab 'Scala 3 only' %}
+```scala
+object A:
+ class TC
+ given tc: TC
+ def f(using TC) = ???
+
+object B:
+ import A.* // import all non-given members
+ import A.given // import the given instance
+```
+{% endtab %}
+{% endtabs %}
+
+在此代码中，对象 `B` 的 `import A.*` 子句导入了 `A` 的所有成员 *除了* `given` 实例 `tc`。
+相反，第二个导入，`import A.given`，*仅*导入那个 `given` 实例。
+两个 `import` 子句也可以合并为一个：
+
+{% tabs packaging-imports-20 %}
+{% tab 'Scala 3 only' %}
+```scala
+object B:
+ import A.{given, *}
+```
+{% endtab %}
+{% endtabs %}
+
+### 讨论
+
+通配符选择器 `*` 将除给定或扩展之外的所有定义带入范围，而 `given` 选择器将所有*给定*——包括那些由扩展产生的定义——带入范围。
+
+这些规则有两个主要好处：
+
+- 范围内的给定来自哪里更清楚。
+ 特别是，不可能在一长串其他通配符导入中隐藏导入的给定。
+- 它可以在不导入任何其他内容的情况下导入所有给定。
+ 这一点特别重要，因为给定可以是匿名的，所以通常使用命名导入是不切实际的。
+
+### 按类型导入
+
+由于给定可以是匿名的，因此按名称导入它们并不总是可行的，通常使用通配符导入。
+*按类型导入* 为通配符导入提供了更具体的替代方案，这使得导入的内容更加清晰：
+
+{% tabs packaging-imports-21 %}
+{% tab 'Scala 3 only' %}
+```scala
+import A.{given TC}
+```
+{% endtab %}
+{% endtabs %}
+
+这会在 `A` 中导入任何具有符合 `TC` 的类型的 `given`。
+导入多种类型的给定 `T1,...,Tn` 由多个 `given` 选择器表示：
+
+{% tabs packaging-imports-22 %}
+{% tab 'Scala 3 only' %}
+```scala
+import A.{given T1, ..., given Tn}
+```
+{% endtab %}
+{% endtabs %}
+
+导入参数化类型的所有 `given` 实例由通配符参数表示。
+例如，当你有这个 `object` 时：
+
+{% tabs packaging-imports-23 %}
+{% tab 'Scala 3 only' %}
+```scala
+object Instances:
+ given intOrd: Ordering[Int]
+ given listOrd[T: Ordering]: Ordering[List[T]]
+ given ec: ExecutionContext = ...
+ given im: Monoid[Int]
+```
+{% endtab %}
+{% endtabs %}
+
+此导入语句导入 `intOrd`、`listOrd` 和 `ec` 实例，但省略了 `im` 实例，因为它不符合任何指定的边界：
+
+{% tabs packaging-imports-24 %}
+{% tab 'Scala 3 only' %}
+```scala
+import Instances.{given Ordering[?], given ExecutionContext}
+```
+{% endtab %}
+{% endtabs %}
+
+按类型导入可以与按名称导入混合。
+如果两者都存在于导入子句中，则按类型导入排在最后。
+例如，这个 import 子句导入了 `im`、`intOrd` 和 `listOrd`，但省略了 `ec`：
+
+{% tabs packaging-imports-25 %}
+{% tab 'Scala 3 only' %}
+```scala
+import Instances.{im, given Ordering[?]}
+```
+{% endtab %}
+{% endtabs %}
+
+### 一个例子
+
+作为一个具体的例子，假设你有这个 `MonthConversions` 对象，它包含两个 `given` 定义：
+
+{% tabs packaging-imports-26 %}
+{% tab 'Scala 3 only' %}
+
+```scala
+object MonthConversions:
+ trait MonthConverter[A]:
+ def convert(a: A): String
+
+ given intMonthConverter: MonthConverter[Int] with
+ def convert(i: Int): String =
+ i match
+ case 1 => "January"
+ case 2 => "February"
+ // more cases here ...
+
+ given stringMonthConverter: MonthConverter[String] with
+ def convert(s: String): String =
+ s match
+ case "jan" => "January"
+ case "feb" => "February"
+ // more cases here ...
+```
+{% endtab %}
+{% endtabs %}
+
+要将这些给定导入当前范围，请使用以下两个 `import` 语句：
+
+{% tabs packaging-imports-27 %}
+{% tab 'Scala 3 only' %}
+
+```scala
+import MonthConversions.*
+import MonthConversions.{given MonthConverter[?]}
+```
+{% endtab %}
+{% endtabs %}
+
+现在您可以创建一个使用这些 `given` 实例的方法：
+
+{% tabs packaging-imports-28 %}
+{% tab 'Scala 3 only' %}
+
+```scala
+def genericMonthConverter[A](a: A)(using monthConverter: MonthConverter[A]): String =
+ monthConverter.convert(a)
+```
+{% endtab %}
+{% endtabs %}
+
+然后您可以在您的应用程序中使用该方法：
+
+{% tabs packaging-imports-29 %}
+{% tab 'Scala 3 only' %}
+
+```scala
+@main def main =
+ println(genericMonthConverter(1)) // January
+ println(genericMonthConverter("jan")) // January
+```
+{% endtab %}
+{% endtabs %}
+
+如前所述， `import given` 语法的主要设计优势之一是明确范围内的给定来自何处，并且在这些 `import` 语句中，很清楚地表明给定是来自 `MonthConversions` 对象。
+
+[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %}
diff --git a/_zh-cn/overviews/scala3-book/scala-features.md b/_zh-cn/overviews/scala3-book/scala-features.md
new file mode 100644
index 0000000000..9c8d02f085
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/scala-features.md
@@ -0,0 +1,535 @@
+---
+title: Scala 3 特性
+type: chapter
+description: This page discusses the main features of the Scala 3 programming language.
+language: zh-cn
+num: 2
+previous-page: introduction
+next-page: why-scala-3
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+_Scala_ 这个名字来源于 _scalable_ 一词。正如其名，Scala 语言被用于支撑高流量网站以及分析庞大的数据集。
+本节介绍了使 Scala 成为一门可扩展语言的特性。
+这些特性分为三个部分：
+
+- 高级语言特性
+- 底层语言特性
+- Scala 生态系统特性
+
+{% comment %}
+I think of this section as being like an “elevator pitch.”
+{% endcomment %}
+
+## 高级特性
+
+从宏观视角来看 Scala，您可以对它做出以下陈述：
+
+- 它是一种高级编程语言
+- 它具有简明易读的语法
+- 它是静态类型的（但使人感觉是动态的）
+- 它有一个表达力强大的类型系统
+- 它是一种函数式编程（FP）语言
+- 它是一种面向对象的编程（OOP）语言
+- 它支持 FP 与 OOP 的融合
+- 上下文抽象提供了一种清晰的方式来实现 _表达式推断_
+- 它在 JVM（和浏览器）上运行
+- 它与 Java 代码无缝交互
+- 它可被用于服务器端应用（包括微服务）、大数据应用，也可以在浏览器中与 Scala.js 共同使用
+
+以下部分将对这些特性进行简要介绍。
+
+### 一门高级语言
+
+Scala 至少在两个方面被认为是一门高级语言。
+首先，像 Java 和许多其他现代语言一样，您不需要与指针和内存管理等底层概念打交道。
+
+其次，通过使用 lambda 与高阶函数，您可以在非常高的层次上编写代码。
+正如函数式编程的说法，在 Scala 中，您编写您想要 _“什么”_，而不是 _“如何”_ 去实现它。
+也就是说，我们不会像这样编写命令式代码：
+
+{% tabs scala-features-1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=scala-features-1 %}
+```scala
+import scala.collection.mutable.ListBuffer
+
+def double(ints: List[Int]): List[Int] = {
+ val buffer = new ListBuffer[Int]()
+ for (i <- ints) {
+ buffer += i * 2
+ }
+ buffer.toList
+}
+
+val oldNumbers = List(1, 2, 3)
+val newNumbers = double(oldNumbers)
+```
+{% endtab %}
+{% tab 'Scala 3' for=scala-features-1 %}
+```scala
+import scala.collection.mutable.ListBuffer
+
+def double(ints: List[Int]): List[Int] =
+ val buffer = new ListBuffer[Int]()
+ for i <- ints do
+ buffer += i * 2
+ buffer.toList
+
+val oldNumbers = List(1, 2, 3)
+val newNumbers = double(oldNumbers)
+```
+{% endtab %}
+{% endtabs %}
+
+这段代码指示编译器逐步执行特定操作。
+相反，我们使用像这样的高阶函数与 lambda 来编写高层次的函数式代码以计算出相同的结果：
+
+{% tabs scala-features-2 %}
+{% tab 'Scala 2 and 3' for=scala-features-2 %}
+```scala
+val newNumbers = oldNumbers.map(_ * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+如您所见，该代码更简洁、更容易阅读且更易于维护。
+
+### 简明的语法
+
+Scala 具有简明易读的语法。例如，变量的创建十分简洁，其类型也很明确。
+
+{% tabs scala-features-3 %}
+{% tab 'Scala 2 and 3' for=scala-features-3 %}
+```scala
+val nums = List(1,2,3)
+val p = Person("Martin", "Odersky")
+```
+{% endtab %}
+{% endtabs %}
+
+高阶函数与 lambda 使代码简明易读：
+
+{% tabs scala-features-4 %}
+{% tab 'Scala 2 and 3' for=scala-features-4 %}
+```scala
+nums.map(i => i * 2) // long form
+nums.map(_ * 2) // short form
+
+nums.filter(i => i > 1)
+nums.filter(_ > 1)
+```
+{% endtab %}
+{% endtabs %}
+
+特质（Traits）、类（Class）和方法（Method）都是用简洁、轻巧的语法定义的。
+
+{% tabs scala-features-5 class=tabs-scala-version %}
+{% tab 'Scala 2' for=scala-features-5 %}
+```scala mdoc
+trait Animal {
+ def speak(): Unit
+}
+
+trait HasTail {
+ def wagTail(): Unit
+}
+
+class Dog extends Animal with HasTail {
+ def speak(): Unit = println("Woof")
+ def wagTail(): Unit = println("⎞⎜⎛ ⎞⎜⎛")
+}
+```
+{% endtab %}
+{% tab 'Scala 3' for=scala-features-5 %}
+```scala
+trait Animal:
+ def speak(): Unit
+
+trait HasTail:
+ def wagTail(): Unit
+
+class Dog extends Animal, HasTail:
+ def speak(): Unit = println("Woof")
+ def wagTail(): Unit = println("⎞⎜⎛ ⎞⎜⎛")
+```
+{% endtab %}
+{% endtabs %}
+
+研究表明，开发人员花在 _阅读_ 代码和 _编写_ 代码上的时间比例至少为 10:1。因此，编写简洁 _并_ 易读的代码非常重要。
+
+### 动态感受
+
+Scala 是一种静态类型的语言，但由于其类型推断能力，它使人感觉是动态的。所有这些表达式看起来都像 Python 或 Ruby 这样的动态类型语言代码，但其实它们都是 Scala 代码：
+
+{% tabs scala-features-6 class=tabs-scala-version %}
+{% tab 'Scala 2' for=scala-features-6 %}
+```scala
+val s = "Hello"
+val p = Person("Al", "Pacino")
+val sum = nums.reduceLeft(_ + _)
+val y = for (i <- nums) yield i * 2
+val z = nums
+ .filter(_ > 100)
+ .filter(_ < 10_000)
+ .map(_ * 2)
+```
+{% endtab %}
+{% tab 'Scala 3' for=scala-features-6 %}
+```scala
+val s = "Hello"
+val p = Person("Al", "Pacino")
+val sum = nums.reduceLeft(_ + _)
+val y = for i <- nums yield i * 2
+val z = nums
+ .filter(_ > 100)
+ .filter(_ < 10_000)
+ .map(_ * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+正如 Heather Miller 所说，Scala 被认为是一种[强静态类型语言](https://heather.miller.am/blog/types-in-scala.html)。您可以获得静态类型的全部益处：
+
+- 正确性：您可以在编译时捕获大多数错误
+- 强大的 IDE 支持
+ - 可靠的代码补全
+ - 在编译时捕获错误意味着在您打字时捕获错误
+ - 简单而可靠的重构
+- 您可以自信地重构您的代码
+- 方法类型声明告诉读者该方法的作用，并作为文档提供帮助
+- 可扩展性与可维护性：类型有助于在任意大小的应用程序与开发团队中确保正确性
+- 强类型结合优秀的推断能力可实现[上下文抽象]({{ site.scala3ref }}/contextual)等机制，这允许您省略样板代码。通常，这些样板代码可由编译器根据类型定义及给定的上下文推断出来。
+
+{% comment %}
+In that list:
+- 'Correctness' and 'Scalability' come from Heather Miller’s page
+- the IDE-related quotes in this section come from the Scala.js website:
+ - catch most errors in the IDE
+ - Easy and reliable refactoring
+ - Reliable code completion
+{% endcomment %}
+
+### 富有表现力的类型系统
+
+{% comment %}
+- this text comes from the current [ScalaTour](https://docs.scala-lang.org/tour/tour-of-scala.html).
+- TODO: all of the URLs will have to be updated
+
+- i removed these items until we can replace them:
+* [Compound types](/tour/compound-types.html)
+* [conversions](/tour/implicit-conversions.html)
+* [Explicitly typed self references](/tour/self-types.html)
+{% endcomment %}
+
+Scala 的类型系统在编译时强制要求以安全与连贯的方式使用抽象概念。特别是，该类型系统支持：
+
+- [推断类型]({% link _zh-cn/overviews/scala3-book/types-inferred.md %})
+- [泛型类]({% link _zh-cn/overviews/scala3-book/types-generics.md %})
+- [型变]({% link _zh-cn/overviews/scala3-book/types-variance.md %})
+- [类型上界](/tour/upper-type-bounds.html) 与 [类型下界](/tour/lower-type-bounds.html)
+- [多态方法](/tour/polymorphic-methods.html)
+- [交叉类型]({% link _zh-cn/overviews/scala3-book/types-intersection.md %})
+- [联合类型]({% link _zh-cn/overviews/scala3-book/types-union.md %})
+- [类型 Lambda]({{ site.scala3ref }}/new-types/type-lambdas.html)
+- [`given` 实例与 `using` 子句]({% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %})
+- [扩展方法]({% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %})
+- [类型类]({% link _zh-cn/overviews/scala3-book/ca-type-classes.md %})
+- [多元相等]({% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %})
+- [不透明类型别名]({% link _zh-cn/overviews/scala3-book/types-opaque-types.md %})
+- [开放类]({{ site.scala3ref }}/other-new-features/open-classes.html)
+- [匹配类型]({{ site.scala3ref }}/new-types/match-types.html)
+- [依赖函数类型]({{ site.scala3ref }}/new-types/dependent-function-types.html)
+- [多态函数类型]({{ site.scala3ref }}/new-types/polymorphic-function-types.html)
+- [上下文边界]({{ site.scala3ref }}/contextual/context-bounds.html)
+- [上下文函数]({{ site.scala3ref }}/contextual/context-functions.html)
+- 作为对象成员的[内部类](/tour/inner-classes.html) 与 [抽象类型](/tour/abstract-type-members.html)
+
+通过结合使用，这些特性为编程抽象的安全重用及软件的类型安全扩展提供了强大的基础。
+
+### 一门函数式编程语言
+
+Scala 是一门函数式编程（FP）语言，也就是说：
+
+- 函数是值，可以像任何其他值一样被传递
+- 直接支持高阶函数
+- 原生地支持 Lambda
+- Scala 中的一切都是会返回值的表达式
+- 从语法上来说，使用不可变变量很容易并且此行为被鼓励
+- 在标准库中有大量的不可变集合类
+- 这些集合类带有许多函数式方法：它们不改变集合本身，而是返回数据的更新副本
+
+### 一门面向对象语言
+
+Scala 是一门面向对象编程（OOP）语言。
+每个值都是一个类的实例，每个“运算符”都是一个方法。
+
+在 Scala 中，所有类型都继承自顶层类 `Any`，其直接子类是 `AnyVal`（_值类型_，例如 `Int` 与 `Boolean`）和 `AnyRef`（_引用类型_，与 Java 中相同）。
+这意味着 Scala 中不存在 Java 中原始类型和包装类型的区别（例如 `int` 与 `Integer`）。
+装箱与拆箱对用户来说是完全透明的。
+
+{% comment %}
+- AnyRef above is wrong in case of strict null checking, no? On the other hand, maybe too much information to state this here
+- probably not worth to mention (too advanced at this point) there is AnyKind
+- Add the “types hierarchy” image here?
+{% endcomment %}
+
+### 支持 FP 与 OOP 融合
+
+{% comment %}
+NOTE: This text in the first line comes from this slide: https://x.com/alexelcu/status/996408359514525696
+{% endcomment %}
+
+Scala 的本质是函数式编程和面向对象编程的融合：
+
+- 函数用于代表逻辑
+- 对象用于模块化
+
+正如 [Martin Odersky 所说](https://jaxenter.com/current-state-scala-odersky-interview-129495.html)，“Scala 旨在表明函数式编程与面向对象编程的融合是切实可行的。”
+
+### 表达式推断，更加清晰
+
+继 Haskell 之后，Scala 是第二种具有某种形式的 _隐式_ 的流行语言。
+在 Scala 3 中，这些概念经过了重新考虑并更清晰地实现。
+
+其核心思想是 _表达式推断_：给定一个类型，编译器会合成一个具有该类型的“规范”表达式。
+在 Scala 中，一个上下文参数直接导致一个被推断出的参数项的出现。该参数项也可以被显式地写出来。
+
+此概念的用例包括实现[类型类]({% link _overviews/scala3-book/ca-type-classes.md %})、建立上下文、依赖注入、表达能力、计算新类型以及证明它们之间的关系。
+
+Scala 3 使此过程比以往任何时候都更加清晰。
+请在[参考文档]({{ site.scala3ref }}/contextual)中阅读关于上下文抽象的内容。
+
+### 客户端与服务器
+
+Scala 代码在 Java 虚拟机（JVM）上运行，因此您可以获得它的全部益处：
+
+- 安全性
+- 性能
+- 内存管理
+- 可移植性与平台独立性
+- 能够使用大量的现有 Java 和 JVM 库
+
+除了在 JVM 上运行外，Scala 还可以通过 Scala.js （以及开源的第三方工具以集成流行的 JavaScript 库）在浏览器中运行，并且可以使用Scala Native 与 GraalVM 构建原生可执行文件。
+
+### 与 Java 无缝交互
+
+您可以在 Scala 应用程序中使用 Java 类和库，也可以在 Java 应用程序中使用 Scala 代码。
+对于第二点来说，诸如 [Akka](https://akka.io) 和 [Play Framework](https://www.playframework.com) 之类的大型库是用 Scala 编写的，并且它们可以在 Java 应用程序中使用。
+
+对于第一点来说，Scala 应用程序中每天都会用到 Java 类和库。
+例如，在 Scala 中，您可以使用 Java 的 `BufferedReader` 和 `FileReader` 来读取文件：
+
+{% tabs scala-features-7 %}
+{% tab 'Scala 2 and 3' for=scala-features-7 %}
+```scala
+import java.io.*
+val br = BufferedReader(FileReader(filename))
+// read the file with `br` ...
+```
+{% endtab %}
+{% endtabs %}
+
+在 Scala 中使用 Java 代码通常是无缝衔接的。
+
+Java 集合也可以在 Scala 中使用， 如果您想将 Scala 丰富的集合类方法与其一起使用，只需几行代码即可转换它们：
+
+{% tabs scala-features-8 %}
+{% tab 'Scala 2 and 3' for=scala-features-8 %}
+```scala
+import scala.jdk.CollectionConverters.*
+val scalaList: Seq[Integer] = JavaClass.getJavaList().asScala.toSeq
+```
+{% endtab %}
+{% endtabs %}
+
+### 丰富的库
+
+正如您将在本页的第三部分中所看到的那样，已经有诸如此类的 Scala 库和框架被编写出来用于支撑高流量网站以及分析庞大的数据集：
+
+1. [Play Framework](https://www.playframework.com) 是一种用于创建高度可扩展应用程序的轻量级、无状态、对开发者及Web友好的架构
+2. [Apache Spark](https://spark.apache.org) 是一种面向大规模数据处理的统一分析引擎，内置流、SQL、机器学习和图形处理等模块
+
+[Awesome Scala 列表](https://github.com/lauris/awesome-scala)展示了开发人员为构建 Scala 应用程序而创建的许多其他开源工具。
+
+除了服务器端编程之外，[Scala.js](https://www.scala-js.org) 是一款用于编写 JavaScript 应用的强类型替代方案。其开源的第三方库包含支持与 Facebook 的 React、jQuery 及其他库等集成的工具。
+
+{% comment %}
+The Lower-Level Features section is like the second part of an elevator pitch.
+Assuming you told someone about the previous high-level features and then they say, “Tell me more,” this is what you might tell them.
+{% endcomment %}
+
+## 底层语言特性
+
+上一节介绍了 Scala 3 的高级特性，有趣的是，您可以从高层次上对 Scala 2 和 Scala 3 作出相同的表述。
+十年前，Scala 就为各种理想特性打下了坚实基础，正如您在本节中即将看到的那样，这些效益在 Scala 3 中得到了提高。
+
+以小见大，从程序员日常使用的语言特性来看，Scala 3 比 Scala 2 具有显著优势：
+
+- 可以用枚举更简洁地创建代数数据类型（ADT）
+- 更简明易读的语法：
+ - “干净”的控制结构语法更容易阅读
+ - 可选的大括号
+ - 代码中包含更少的符号，因此会产生更少的视觉噪音，使其更容易阅读
+ - 创建类实例时一般不再需要 `new` 关键字
+ - 弃用了包对象，转而使用更简单的“顶层”定义
+- 更清晰的语法：
+ - 移除了 `implicit` 关键字的多种不同用法，这些用法被更显而易见的关键字所取代，如 `given`、 `using`、和 `extension`，以此将关注重点放在意图而不是机制上（详见 [Givens][givens] 部分）
+ - [扩展方法][extension]通过更加清晰简单的机制取代了隐式类
+ - 为类添加了 `open` 修饰符，使开发者能够有意识地声明一个类是可以被修改的，从而限制对代码库的临时扩展
+ - [多元相等][multiversal]排除了用 `==` 和 `!=` 进行无意义的比较（即试图将 `Person` 与 `Planet` 进行比较）
+ - 宏的实现变得更加容易
+ - 联合与交叉提供了一种灵活的方式以建模类型
+ - 特质参数取代并简化了早期初始化器
+ - [不透明类型别名][opaque_types]取代了值类的大多数用途，并确保不进行装箱
+ - 导出子句提供了一种简单而通用的方式来表现聚合，它可以取代之前继承自类的包对象的外观模式
+ - 删除了过程语法并更改了可变参数语法，这增加了语言一致性
+ - `@infix` 注解使得您想让一个方法被如何应用更加显而易见
+ - [`@targetName`]({{ site.scala3ref }}/other-new-features/targetName.html) 方法注解为方法定义了一个候补名称。这提高了与 Java 的互操作性，并允许您为符号运算符提供别名
+
+在这里演示所有这些特性会占用太多空间，请通过上述内容中的链接来查看这些特性的实际效果。
+所有这些特性都在[概述文档][reference]的*新特性*、*变更的特性*、与*删除的特性*等页面中进行了详细讨论。
+
+{% comment %}
+CHECKLIST OF ALL ADDED, UPDATED, AND REMOVED FEATURES
+=====================================================
+
+New Features
+------------
+- trait parameters
+- super traits
+- creator applications
+- export clauses
+- opaque type aliases
+- open classes
+- parameter untupling
+- kind polymorphism
+- tupled function
+- threadUnsafe annotation
+- new control syntax
+- optional braces (experimental)
+- explicit nulls
+- safe initialization
+
+CHANGED FEATURES
+----------------
+- numeric literals
+- structural types
+- operators
+- wildcard types
+- type checking
+- type inference
+- implicit resolution
+- implicit conversions
+- overload resolution
+- match expressions
+- vararg patterns
+- pattern bindings
+- pattern matching
+- eta expansion
+- compiler plugins
+- lazy vals initialization
+- main functions
+
+DROPPED FEATURES
+----------------
+- DelayedInit
+- macros
+- existential types
+- type projection
+- do/while syntax
+- procedure syntax
+- package objects
+- early initializers
+- class shadowing
+- limit 22
+- XML literals
+- symbol literals
+- auto-application
+- weak conformance
+- nonlocal returns
+- [this] qualifier
+ - private[this] and protected[this] access modifiers are deprecated
+ and will be phased out
+{% endcomment %}
+
+## Scala 生态系统
+
+Scala 拥有一个充满活力的生态系统，有满足各种需求的库和框架。
+[Awesome Scala 列表](https://github.com/lauris/awesome-scala)提供了数百个可供 Scala 开发者使用的开源项目，[Scaladex](https://index.scala-lang.org) 则提供了 Scala 库的可搜索索引。
+以下列出了一些比较著名的库：
+
+### Web 开发
+
+- [Play Framework](https://www.playframework.com) 遵循 Ruby on Rails 模型，是一种用于高度可扩展应用程序的轻量级、无状态、对开发者及Web友好的架构
+- [Scalatra](https://scalatra.org) 是一个小型的、高性能的、异步的网络框架，其灵感来自于 Sinatra
+- [Finatra](https://twitter.github.io/finatra) 是基于 TwitterServer 和 Finagle 构建的 Scala 服务
+- [Scala.js](https://www.scala-js.org) 是 JavaScript 的强类型替代品，它提供了一种更安全的方式以构建稳健的前端 Web 应用程序
+- [ScalaJs-React](https://github.com/japgolly/scalajs-react) 将 Facebook 的 React 库整合至 Scala.js，并努力使其尽可能类型安全和 Scala 友好
+
+HTTP(S) 库：
+
+- [Akka-http](https://akka.io)
+- [Finch](https://github.com/finagle/finch)
+- [Http4s](https://github.com/http4s/http4s)
+- [Sttp](https://github.com/softwaremill/sttp)
+
+JSON 库：
+
+- [Argonaut](https://github.com/argonaut-io/argonaut)
+- [Circe](https://github.com/circe/circe)
+- [Json4s](https://github.com/json4s/json4s)
+- [Play-JSON](https://github.com/playframework/play-json)
+
+序列化：
+
+- [ScalaPB](https://github.com/scalapb/ScalaPB)
+
+### 科学和数据分析
+
+- [Algebird](https://github.com/twitter/algebird)
+- [Spire](https://github.com/typelevel/spire)
+- [Squants](https://github.com/typelevel/squants)
+
+### 大数据
+
+- [Apache Spark](https://github.com/apache/spark)
+- [Apache Flink](https://github.com/apache/flink)
+
+### 人工智能，机器学习
+
+- [BigDL](https://github.com/intel-analytics/BigDL) （用于 Apache Spark 的分布式深度学习框架）
+- [TensorFlow Scala](https://github.com/eaplatanios/tensorflow_scala)
+
+### 函数式编程 & 函数式响应式编程
+
+函数式编程：
+
+- [Cats](https://github.com/typelevel/cats)
+- [Zio](https://github.com/zio/zio)
+
+函数式响应式编程（FRP）
+
+- [fs2](https://github.com/typelevel/fs2)
+- [monix](https://github.com/monix/monix)
+
+### 构建工具
+
+- [sbt](https://www.scala-sbt.org)
+- [Gradle](https://gradle.org)
+- [Mill](https://github.com/lihaoyi/mill)
+
+## 总结
+
+如此页所示，Scala 在高层、日常编程层面以及贯穿开发者生态系统都具有许多出色的编程语言特性。
+
+
+[reference]: {{ site.scala3ref }}/overview.html
+[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %}
+[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}
+[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %}
+[opaque_types]: {% link _zh-cn/overviews/scala3-book/types-opaque-types.md %}
diff --git a/_zh-cn/overviews/scala3-book/scala-for-java-devs.md b/_zh-cn/overviews/scala3-book/scala-for-java-devs.md
new file mode 100644
index 0000000000..c8f449fd56
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/scala-for-java-devs.md
@@ -0,0 +1,1279 @@
+---
+title: 向 Java 开发者介绍Scala
+type: chapter
+description: This page is for Java developers who are interested in learning about Scala 3.
+language: zh-cn
+num: 73
+previous-page: interacting-with-java
+next-page: scala-for-javascript-devs
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+{% include_relative scala4x.css %}
+:9: error: type mismatch;
+ found : Double
+ required: Int
+ f"$height%4d"
+ ^
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=f-interpolator-error %}
+```scala
+val height: Double = 1.9d
+
+scala> f"$height%4d"
+-- Error: ----------------------------------------------------------------------
+1 |f"$height%4d"
+ | ^^^^^^
+ | Found: (height : Double), Required: Int, Long, Byte, Short, BigInt
+1 error found
+
+```
+{% endtab %}
+{% endtabs %}
+
+`f` 插值器使用来自 Java 的字符串格式化工具。格式化允许在 `%` 字符后，在[Formatter javadoc][java-format-docs] 中有说明。
+如果没有 `%` 字符在变量之后，那么 `%s` (`String`) 作为缺省的格式化工具。
+
+最后，像在 Java 里，使用 `%%` 来让 `%` 字符出现在输出字符中：
+
+{% tabs literal-percent %}
+{% tab 'Scala 2 and 3' for=literal-percent %}
+```scala
+println(f"3/19 is less than 20%%") // "3/19 is less than 20%"
+```
+{% endtab %}
+{% endtabs %}
+
+### `raw` 插值器
+
+raw 插值器 和 `s` 插值器很像，除了它不动字符串内的转义符。这里有一个处理字符串的例子：
+
+{% tabs example-9 %}
+{% tab 'Scala 2 and 3' for=example-9 %}
+```scala
+scala> s"a\nb"
+res0: String =
+a
+b
+```
+{% endtab %}
+{% endtabs %}
+
+这里 `s` 字符串插值器把 `\n` 替换成回车字符。`raw` 插值器不会做那些。
+
+{% tabs example-10 %}
+{% tab 'Scala 2 and 3' for=example-10 %}
+```scala
+scala> raw"a\nb"
+res1: String = a\nb
+```
+{% endtab %}
+{% endtabs %}
+
+当你希望避免像 `\n` 这样的表达式转义成回车符，raw 插值器会有用。
+
+除了这三种自带的字符串插值器外，你还可以定义自己的插值器。
+
+## 高级用法
+
+字面量 `s"Hi $name"` 被 Scala 当成 _过程_ 字符串字面量来进行分析。
+这意味着编译器对这个字面量额外做了一些工作。具体的处理后的字符串
+和字符串插入器可以在 [SIP-11][sip-11] 中找到描述，但这里用一个快速的例子来展示它
+是如何工作的。
+
+### 定制插值器
+
+在 Scala 中，所有被处理过的字符串字面量都是简单的代码转换。任何时候当编译器遇到
+形式如下，处理过的字符串字面量时：
+
+{% tabs example-11 %}
+{% tab 'Scala 2 and 3' for=example-11 %}
+```scala
+id"string content"
+```
+{% endtab %}
+{% endtabs %}
+
+编译器把这段代码转换成 在 [StringContext](https://www.scala-lang.org/api/current/scala/StringContext.html) 实例之上调用 (`id`) 方法.
+该方法也在隐式作用域有效。
+为了定义我们自己的字符串插值器，我们需要创建一个 implicit class (Scala 2) 或者一个 `extension` 方法（Scala 3）方法，这样可以把新方法添加到 `StringContext` 中。
+
+作为一个小例子，让我们假定 `Point` 类，并假定我们想创建一个定制化的插值器，它把 `p"a,b"` into a 转换成 `Point` 对象。
+
+{% tabs custom-interpolator-1 %}
+{% tab 'Scala 2 and 3' for=custom-interpolator-1 %}
+```scala
+case class Point(x: Double, y: Double)
+
+val pt = p"1,-2" // Point(1.0,-2.0)
+```
+{% endtab %}
+{% endtabs %}
+
+我们首先实现一个如下的 `StringContext` 扩展来创建一个定制的 `p`-插值器：
+
+{% tabs custom-interpolator-2 class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=custom-interpolator-2 %}
+```scala
+implicit class PointHelper(val sc: StringContext) extends AnyVal {
+ def p(args: Any*): Point = ???
+}
+```
+
+**注意：** 在 Scala 2.x 中重要的一点是继承自 `AnyVal` ，从而防止运行时对每个插值器进行实例化。
+更多内容见 [值类][value-classes] 文档。
+
+{% endtab %}
+
+{% tab 'Scala 3' for=custom-interpolator-2 %}
+```scala
+extension (sc: StringContext)
+ def p(args: Any*): Point = ???
+```
+{% endtab %}
+
+{% endtabs %}
+
+一旦这个扩展在作用域，当 Scala 编译器遇到 `p"some string"` 时，它将
+`some string` 中每一个嵌入到字符串中的变量转换为字符串和表达式参数。
+
+例如 `p"1, $someVar"` 将转变成：
+
+{% tabs extension-desugaring class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=extension-desugaring %}
+```scala
+new StringContext("1, ", "").p(someVar)
+```
+
+隐式类将用来重写成以下的样子：
+
+```scala
+new PointHelper(new StringContext("1, ", "")).p(someVar)
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=extension-desugaring %}
+```scala
+StringContext("1, ","").p(someVar)
+```
+
+{% endtab %}
+
+{% endtabs %}
+
+作为结果，每一个处理过的字符串片段都暴露在 `StringContext.parts` 成员内，而在字符串中的任何
+表达式的值都传递给该方法的 `args` 参数。
+
+### 实现的例子
+
+我们这个天真的 Point 插值器方法的实现看着像以下的代码，
+但是更复杂的方法可能会用更加精确的控制用于处理字符串 `parts` 和 表达式 `args`,
+这样可以替代目前重用 `s`-插值器。
+
+{% tabs naive-implementation class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=naive-implementation %}
+```scala
+implicit class PointHelper(val sc: StringContext) extends AnyVal {
+ def p(args: Double*): Point = {
+ // reuse the `s`-interpolator and then split on ','
+ val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) }
+ Point(pts(0), pts(1))
+ }
+}
+
+val x=12.0
+
+p"1, -2" // Point(1.0, -2.0)
+p"${x/5}, $x" // Point(2.4, 12.0)
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=naive-implementation %}
+```scala
+extension (sc: StringContext)
+ def p(args: Double*): Point = {
+ // reuse the `s`-interpolator and then split on ','
+ val pts = sc.s(args: _*).split(",", 2).map { _.toDoubleOption.getOrElse(0.0) }
+ Point(pts(0), pts(1))
+ }
+
+val x=12.0
+
+p"1, -2" // Point(1.0, -2.0)
+p"${x/5}, $x" // Point(2.4, 12.0)
+```
+{% endtab %}
+{% endtabs %}
+
+虽然字符串插值器刚开始是用来创建某种字符串形式，但使用上面的定制插值器可以有强大的句法简写，
+并且社区已经制造了一些语法便捷的用途，如 ANSI 终端颜色扩展，可执行 SQL 查询，神奇的
+`$"identifier"` 表达，还有更多其它的。
+
+[java-format-docs]: https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Formatter.html#detail
+[value-classes]: {% link _overviews/core/value-classes.md %}
+[sip-11]: {% link _sips/sips/string-interpolation.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-collections.md b/_zh-cn/overviews/scala3-book/taste-collections.md
new file mode 100644
index 0000000000..966872f1a3
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-collections.md
@@ -0,0 +1,156 @@
+---
+title: 集合
+type: section
+description: This page provides a high-level overview of the main features of the Scala 3 programming language.
+language: zh-cn
+num: 13
+previous-page: taste-objects
+next-page: taste-contextual-abstractions
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 库具有一组丰富的集合类，这些类具有一组丰富的方法。
+集合类有不可变和可变两种形式。
+
+## 创建列表
+
+为了让您了解这些类的工作原理，下面是一些使用 `List` 类的示例，该类是不可变的链接列表类。
+这些示例显示了创建填充的 `List` 的不同方法：
+
+{% tabs collection_1 %}
+{% tab 'Scala 2 and 3' for=collection_1 %}
+
+```scala
+val a = List(1, 2, 3) // a: List[Int] = List(1, 2, 3)
+
+// Range methods
+val b = (1 to 5).toList // b: List[Int] = List(1, 2, 3, 4, 5)
+val c = (1 to 10 by 2).toList // c: List[Int] = List(1, 3, 5, 7, 9)
+val e = (1 until 5).toList // e: List[Int] = List(1, 2, 3, 4)
+val f = List.range(1, 5) // f: List[Int] = List(1, 2, 3, 4)
+val g = List.range(1, 10, 3) // g: List[Int] = List(1, 4, 7)
+```
+
+{% endtab %}
+{% endtabs %}
+
+## `List`方法
+
+拥有填充的列表后，以下示例将显示可以对其调用的一些方法。
+请注意，这些都是函数式方法，这意味着它们不会改变调用的集合，而是返回包含更新元素的新集合。
+每个表达式返回的结果显示在每行的注释中：
+
+{% tabs collection_2 %}
+{% tab 'Scala 2 and 3' for=collection_2 %}
+
+```scala
+// a sample list
+val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10)
+
+a.drop(2) // List(30, 40, 10)
+a.dropWhile(_ < 25) // List(30, 40, 10)
+a.filter(_ < 25) // List(10, 20, 10)
+a.slice(2,4) // List(30, 40)
+a.tail // List(20, 30, 40, 10)
+a.take(3) // List(10, 20, 30)
+a.takeWhile(_ < 30) // List(10, 20)
+
+// flatten
+val a = List(List(1,2), List(3,4))
+a.flatten // List(1, 2, 3, 4)
+
+// map, flatMap
+val nums = List("one", "two")
+nums.map(_.toUpperCase) // List("ONE", "TWO")
+nums.flatMap(_.toUpperCase) // List('O', 'N', 'E', 'T', 'W', 'O')
+```
+
+{% endtab %}
+{% endtabs %}
+
+这些示例显示了如何使用 `foldLeft` 和 `reduceLeft` 方法来对整数序列中的值求和：
+
+{% tabs collection_3 %}
+{% tab 'Scala 2 and 3' for=collection_3 %}
+
+```scala
+val firstTen = (1 to 10).toList // List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10)
+
+firstTen.reduceLeft(_ + _) // 55
+firstTen.foldLeft(100)(_ + _) // 155 (100 is a “seed” value)
+```
+
+{% endtab %}
+{% endtabs %}
+
+Scala 集合类还有更多可用的方法，它们在[集合章节][collections]和 [API 文档][api]中进行了演示。
+
+## 元组
+
+Scala _元组_ 是一种类型，可让您轻松地将不同类型的集合放在同一个容器中。
+例如，给定以下 `Person` 样例类：
+
+{% tabs collection_4 %}
+{% tab 'Scala 2 and 3' for=collection_4 %}
+
+```scala
+case class Person(name: String)
+```
+
+{% endtab %}
+{% endtabs %}
+
+这是演示你如创建一个元组，这个元组包含 `Int`, `String`, 和定制的 `Person` 值：
+
+{% tabs collection_5 %}
+{% tab 'Scala 2 and 3' for=collection_5 %}
+
+```scala
+val t = (11, "eleven", Person("Eleven"))
+```
+
+{% endtab %}
+{% endtabs %}
+
+有元组后，可以通过将其值绑定到变量来访问，也可以通过数字访问它们：
+
+{% tabs collection_6 %}
+{% tab 'Scala 2 and 3' for=collection_6 %}
+
+```scala
+t(0) // 11
+t(1) // "eleven"
+t(2) // Person("Eleven")
+```
+
+{% endtab %}
+{% endtabs %}
+
+您还可以使用以下 _解构_ 的办法将元组字段分配变量名：
+
+{% tabs collection_7 %}
+{% tab 'Scala 2 and 3' for=collection_7 %}
+
+```scala
+val (num, str, person) = t
+
+// result:
+// val num: Int = 11
+// val str: String = eleven
+// val person: Person = Person(Eleven)
+```
+
+{% endtab %}
+{% endtabs %}
+
+有些情况更适合使用元组， 那就是当你想要将异构类型的集合放在一个小的类似集合的结构中。
+有关更多元组详细信息，请参阅 [参考文档][reference]。
+
+[collections]: {% link _zh-cn/overviews/scala3-book/collections-intro.md %}
+[api]: https://scala-lang.org/api/3.x/
+[reference]: {{ site.scala3ref }}/overview.html
diff --git a/_zh-cn/overviews/scala3-book/taste-contextual-abstractions.md b/_zh-cn/overviews/scala3-book/taste-contextual-abstractions.md
new file mode 100644
index 0000000000..cfa5db2f45
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-contextual-abstractions.md
@@ -0,0 +1,77 @@
+---
+title: 上下文抽象
+type: section
+description: This section provides an introduction to Contextual Abstractions in Scala 3.
+language: zh-cn
+num: 14
+previous-page: taste-collections
+next-page: taste-toplevel-definitions
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+{% comment %}
+TODO: Now that this is a separate section, it needs a little more content.
+{% endcomment %}
+
+在某些情况下，可以省略在方法调用中你认为是重复的的某些参数。
+
+这些参数之所以称为 _上下文参数_，是因为它们是由编译器从方法调用周围的上下文中推断出来的。
+
+例如，考虑一个程序，该程序按两个条件对地址列表进行排序：城市名称，然后是街道名称。
+
+{% tabs contextual_1 %}
+{% tab 'Scala 2 and 3' for=contextual_1 %}
+
+```scala
+val addresses: List[Address] = ...
+
+addresses.sortBy(address => (address.city, address.street))
+```
+{% endtab %}
+{% endtabs %}
+
+`sortBy` 方法调用一个函数，该函数为每个地址返回值，这个值会用来与其他地址比较。
+在本例中，我们传递一个函数，该函数返回一对，该对包含城市名称和街道名称。
+
+请注意，我们只指示 _怎么_ 比较的，而不是 _如何_ 来执行比较。
+排序算法如何知道如何比较 `String` 对的？
+
+实际上，`sortBy` 方法采用第二个参数---一个上下文参数---该参数由编译器推断。
+它不会出现在上面的示例中，因为它是由编译器提供的。
+
+第二个参数实现 _如何_ 进行比较。
+省略它很方便，因为我们知道 `String` 通常使用词典顺序进行比较。
+
+但是，也可以显式传递它：
+
+{% tabs contextual_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=contextual_2 %}
+
+```scala
+addresses.sortBy(address => (address.city, address.street))(Ordering.Tuple2(Ordering.String, Ordering.String))
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=contextual_2 %}
+
+```scala
+addresses.sortBy(address => (address.city, address.street))(using Ordering.Tuple2(Ordering.String, Ordering.String))
+```
+{% endtab %}
+{% endtabs %}
+
+在本例中，`Ordering.Tuple2(Ordering.String, Ordering.String)` 实例正是编译器以其他方式推断的实例。
+换句话说，这两个示例生成相同的程序。
+
+_上下文抽象_ 用于避免重复代码。
+它们帮助开发人员编写可扩展且同时简洁的代码段。
+
+有关更多详细信息，请参阅本书的[上下文抽象章节][contextual]，以及[参考文档][reference]。
+
+[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %}
+[reference]: {{ site.scala3ref }}/overview.html
diff --git a/_zh-cn/overviews/scala3-book/taste-control-structures.md b/_zh-cn/overviews/scala3-book/taste-control-structures.md
new file mode 100644
index 0000000000..a6d0196ee5
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-control-structures.md
@@ -0,0 +1,546 @@
+---
+title: 控制结构
+type: section
+description: This section demonstrates Scala 3 control structures.
+language: zh-cn
+num: 8
+previous-page: taste-vars-data-types
+next-page: taste-modeling
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 具有您在其他编程语言中可以找到的控制结构，并且还具有强大的 `for` 表达式和 `match` 表达式：
+
+- `if`/`else`
+- `for` 循环和表达式
+- `match` 表达式
+- `while` 循环
+- `try`/`catch`
+
+这些结构在以下示例中进行了说明。
+
+## `if`/`else`
+
+Scala 的 `if`/`else` 控制结构看起来与其他语言相似：
+
+{% tabs if-else class=tabs-scala-version %}
+{% tab 'Scala 2' for=if-else %}
+
+```scala
+if (x < 0) {
+ println("negative")
+} else if (x == 0) {
+ println("zero")
+} else {
+ println("positive")
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=if-else %}
+
+```scala
+if x < 0 then
+ println("negative")
+else if x == 0 then
+ println("zero")
+else
+ println("positive")
+```
+
+{% endtab %}
+{% endtabs %}
+
+请注意，这确实是一个 _表达式_ ---不是一个 _语句_。
+这意味着它返回一个值，因此您可以将结果赋值给一个变量：
+
+{% tabs if-else-expression class=tabs-scala-version %}
+{% tab 'Scala 2' for=if-else-expression %}
+
+```scala
+val x = if (a < b) { a } else { b }
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=if-else-expression %}
+
+```scala
+val x = if a < b then a else b
+```
+
+{% endtab %}
+{% endtabs %}
+
+正如您将在本书中看到的那样，_所有_ Scala 控制结构都可以用作表达式。
+
+> 表达式返回结果，而语句不返回。
+> 语句通常用于它们的副作用，例如使用 `println` 打印到控制台。
+
+## `for` 循环和表达式
+
+`for` 关键字用于创建 `for` 循环。
+这个例子展示了如何打印 `List` 中的每个元素：
+
+{% tabs for-loop class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-loop %}
+
+```scala
+val ints = List(1, 2, 3, 4, 5)
+
+for (i <- ints) println(i)
+```
+
+> 代码 `i <- ints` 被称为_生成器_，在括号内的生成器后面是_循环体_。
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-loop %}
+
+
+```scala
+val ints = List(1, 2, 3, 4, 5)
+
+for i <- ints do println(i)
+```
+
+> 代码 `i <- ints` 被称为 _生成器_，紧随 `do` 关键字的代码是 _循环体_。
+
+{% endtab %}
+{% endtabs %}
+
+### 守卫
+
+您还可以在 `for` 循环中使用一个或多个 `if` 表达式。
+这些被称为 _守卫_。
+此示例打印 `ints` 中大于 `2` 的所有数字：
+
+{% tabs for-guards class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-guards %}
+
+```scala
+for (i <- ints if i > 2)
+ println(i)
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-guards %}
+
+```scala
+for
+ i <- ints
+ if i > 2
+do
+ println(i)
+```
+
+{% endtab %}
+{% endtabs %}
+
+您可以使用多个生成器和守卫。
+此循环遍历数字 `1` 到 `3`，并且对于每个数字，它还遍历字符 `a` 到 `c`。
+然而，它也有两个守卫，所以唯一一次调用 print 语句是当 `i` 的值为 `2` 并且 `j` 是字符 `b` 时：
+
+{% tabs for-guards-multi class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-guards-multi %}
+
+```scala
+for {
+ i <- 1 to 3
+ j <- 'a' to 'c'
+ if i == 2
+ if j == 'b'
+} {
+ println(s"i = $i, j = $j") // prints: "i = 2, j = b"
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-guards-multi %}
+
+```scala
+for
+ i <- 1 to 3
+ j <- 'a' to 'c'
+ if i == 2
+ if j == 'b'
+do
+ println(s"i = $i, j = $j") // prints: "i = 2, j = b"
+```
+
+{% endtab %}
+{% endtabs %}
+
+### `for` 表达式
+
+`for` 关键字更强大：当您使用 `yield` 关键字代替 `do` 时，您会创建 `for` _表达式_用于计算和产生结果。
+
+几个例子演示了这一点。
+使用与上一个示例相同的 `ints` 列表，此代码创建一个新列表，其中新列表中每个元素的值是原始列表中元素值的两倍：
+
+{% tabs for-expression_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-expression_1 %}
+
+````
+scala> val doubles = for (i <- ints) yield i * 2
+val doubles: List[Int] = List(2, 4, 6, 8, 10)
+````
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-expression_1 %}
+
+````
+scala> val doubles = for i <- ints yield i * 2
+val doubles: List[Int] = List(2, 4, 6, 8, 10)
+````
+
+{% endtab %}
+{% endtabs %}
+
+Scala 的控制结构语法很灵活，`for` 表达式可以用其他几种方式编写，具体取决于您的偏好：
+
+{% tabs for-expressioni_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-expressioni_2 %}
+
+```scala
+val doubles = for (i <- ints) yield i * 2
+val doubles = for (i <- ints) yield (i * 2)
+val doubles = for { i <- ints } yield (i * 2)
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-expressioni_2 %}
+
+```scala
+val doubles = for i <- ints yield i * 2 // 如上所示的风格
+val doubles = for (i <- ints) yield i * 2
+val doubles = for (i <- ints) yield (i * 2)
+val doubles = for { i <- ints } yield (i * 2)
+```
+
+{% endtab %}
+{% endtabs %}
+
+此示例显示如何将列表中每个字符串的第一个字符大写：
+
+{% tabs for-expressioni_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-expressioni_3 %}
+
+```scala
+val names = List("chris", "ed", "maurice")
+val capNames = for (name <- names) yield name.capitalize
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-expressioni_3 %}
+
+```scala
+val names = List("chris", "ed", "maurice")
+val capNames = for name <- names yield name.capitalize
+```
+
+{% endtab %}
+{% endtabs %}
+
+最后，这个 `for` 表达式遍历一个字符串列表，并返回每个字符串的长度，但前提是该长度大于 `4`：
+
+{% tabs for-expressioni_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=for-expressioni_4 %}
+
+```scala
+val fruits = List("apple", "banana", "lime", "orange")
+
+val fruitLengths =
+ for (f <- fruits if f.length > 4) yield f.length
+
+// fruitLengths: List[Int] = List(5, 6, 6)
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=for-expressioni_4 %}
+
+```scala
+val fruits = List("apple", "banana", "lime", "orange")
+
+val fruitLengths = for
+ f <- fruits
+ if f.length > 4
+yield
+ // 在这里你可以
+ // 使用多行代码
+ f.length
+
+//fruitLengths: List[Int] = List(5, 6, 6)
+```
+
+{% endtab %}
+{% endtabs %}
+
+`for` 循环和表达式更多细节在本书的 [控制结构部分][control] 中，和 [参考文档]({{ site.scala3ref }}/other-new-features/control-syntax.html) 中。
+
+## `match` 表达式
+
+Scala 有一个 `match` 表达式，它最基本的用途类似于 Java `switch` 语句：
+
+{% tabs match class=tabs-scala-version %}
+{% tab 'Scala 2' for=match %}
+
+```scala
+val i = 1
+
+// later in the code ...
+i match {
+ case 1 => println("one")
+ case 2 => println("two")
+ case _ => println("other")
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=match %}
+
+```scala
+val i = 1
+
+// later in the code ...
+i match
+ case 1 => println("one")
+ case 2 => println("two")
+ case _ => println("other")
+```
+
+{% endtab %}
+{% endtabs %}
+
+但是，`match` 确实是一个表达式，这意味着它会根据模式匹配返回一个结果，您可以将其绑定到一个变量：
+
+{% tabs match-expression_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=match-expression_1 %}
+
+```scala
+val result = i match {
+ case 1 => "one"
+ case 2 => "two"
+ case _ => "other"
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=match-expression_1 %}
+
+
+```scala
+val result = i match
+ case 1 => "one"
+ case 2 => "two"
+ case _ => "other"
+```
+
+{% endtab %}
+{% endtabs %}
+
+`match` 不仅限于使用整数值，它可以用于任何数据类型：
+
+{% tabs match-expression_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=match-expression_2 %}
+
+```scala
+val p = Person("Fred")
+
+// later in the code
+p match {
+ case Person(name) if name == "Fred" =>
+ println(s"$name says, Yubba dubba doo")
+
+ case Person(name) if name == "Bam Bam" =>
+ println(s"$name says, Bam bam!")
+
+ case _ => println("Watch the Flintstones!")
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=match-expression_2 %}
+
+```scala
+val p = Person("Fred")
+
+// later in the code
+p match
+ case Person(name) if name == "Fred" =>
+ println(s"$name says, Yubba dubba doo")
+
+ case Person(name) if name == "Bam Bam" =>
+ println(s"$name says, Bam bam!")
+
+ case _ => println("Watch the Flintstones!")
+```
+
+{% endtab %}
+{% endtabs %}
+
+事实上，`match` 表达式可以用许多模式的不同类型来测试变量。
+此示例显示 (a) 如何使用 `match` 表达式作为方法的主体，以及 (b) 如何匹配显示的所有不同类型：
+
+{% tabs match-expression_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=match-expression_3 %}
+
+```scala
+// getClassAsString is a method that takes a single argument of any type.
+def getClassAsString(x: Any): String = x match {
+ case s: String => s"'$s' is a String"
+ case i: Int => "Int"
+ case d: Double => "Double"
+ case l: List[_] => "List"
+ case _ => "Unknown"
+}
+
+// examples
+getClassAsString(1) // Int
+getClassAsString("hello") // 'hello' is a String
+getClassAsString(List(1, 2, 3)) // List
+```
+
+因为 `getClassAsString` 方法获取 `Any` 类型的参数值，所以它可以解耦任意模式类型。
+
+{% endtab %}
+
+{% tab 'Scala 3' for=match-expression_3 %}
+
+```scala
+// getClassAsString 是一个接受任何类型的单个参数的方法。
+def getClassAsString(x: Matchable): String = x match
+ case s: String => s"'$s' is a String"
+ case i: Int => "Int"
+ case d: Double => "Double"
+ case l: List[_] => "List"
+ case _ => "Unknown"
+
+// examples
+getClassAsString(1) // Int
+getClassAsString("hello") // 'hello' is a String
+getClassAsString(List(1, 2, 3)) // List
+```
+
+`getClassAsString` 方法将 [Matchable]({{ site.scala3ref }}/other-new-features/matchable.html) 类型的值作为参数，它可以是
+任何支持模式匹配的类型（某些类型不支持模式匹配，因为这可能打破封装）。
+
+{% endtab %}
+{% endtabs %}
+
+Scala 中的模式匹配还有 _更多_ 内容。
+模式可以嵌套，模式的结果可以绑定，模式匹配甚至可以是用户自定义的。
+有关详细信息，请参阅 [控制结构章节][control] 中的模式匹配示例。
+
+## `try`/`catch`/`finally`
+
+Scala 的 `try`/`catch`/`finally` 控制结构让你捕获异常。
+它类似于 Java，但其语法与 `match` 表达式一致：
+
+{% tabs try class=tabs-scala-version %}
+{% tab 'Scala 2' for=try %}
+
+```scala
+try {
+ writeTextToFile(text)
+} catch {
+ case ioe: IOException => println("Got an IOException.")
+ case nfe: NumberFormatException => println("Got a NumberFormatException.")
+} finally {
+ println("Clean up your resources here.")
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=try %}
+
+```scala
+try
+ writeTextToFile(text)
+catch
+ case ioe: IOException => println("Got an IOException.")
+ case nfe: NumberFormatException => println("Got a NumberFormatException.")
+finally
+ println("Clean up your resources here.")
+```
+
+{% endtab %}
+{% endtabs %}
+
+## `while` 循环
+
+Scala 还有一个 `while` 循环结构。
+它的单行语法如下所示：
+
+{% tabs while_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=while_1 %}
+
+```scala
+while (x >= 0) { x = f(x) }
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=while_1 %}
+
+```scala
+while x >= 0 do x = f(x)
+```
+为了兼容性，Scala 3 仍然支持 Scala 2 语法。
+
+{% endtab %}
+{% endtabs %}
+
+`while` 循环多行语法如下所示：
+
+{% tabs while_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=while_2 %}
+
+```scala
+var x = 1
+
+while (x < 3) {
+ println(x)
+ x += 1
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=while_2 %}
+
+```scala
+var x = 1
+
+while
+ x < 3
+do
+ println(x)
+ x += 1
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 自定义控制结构
+
+由于传名参数、中缀表示法、流畅接口、可选括号、扩展方法和高阶函数等功能，您还可以创建自己的代码，就像控制结构一样工作。
+您将在 [控制结构][control] 部分了解更多信息。
+
+[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-functions.md b/_zh-cn/overviews/scala3-book/taste-functions.md
new file mode 100644
index 0000000000..71cea44649
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-functions.md
@@ -0,0 +1,87 @@
+---
+title: 头等函数
+type: section
+description: This page provides an introduction to functions in Scala 3.
+language: zh-cn
+num: 11
+previous-page: taste-methods
+next-page: taste-objects
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala具有函数式编程语言中您期望的大多数功能，包括：
+
+- Lambdas（匿名函数）
+- 高阶函数 （HOFs）
+- 标准库中的不可变集合
+
+Lambdas（也称为 _匿名函数_）是保持代码简洁但可读性的重要组成部分。
+
+`List` 类的 `map` 方法是高阶函数的典型示例---一个将函数作为参数的函数。
+
+这两个示例是等效的，并演示如何通过将 lambda 传递到 `map` 方法中，将列表中的每个数字乘以 `2`：
+
+
+{% tabs function_1 %}
+{% tab 'Scala 2 and 3' for=function_1 %}
+
+```scala
+val a = List(1, 2, 3).map(i => i * 2) // List(2,4,6)
+val b = List(1, 2, 3).map(_ * 2) // List(2,4,6)
+```
+
+{% endtab %}
+{% endtabs %}
+
+这些示例也等效于以下代码，该代码使用 `double` 方法而不是lambda：
+
+{% tabs function_2 %}
+{% tab 'Scala 2 and 3' for=function_2 %}
+
+```scala
+def double(i: Int): Int = i * 2
+
+val a = List(1, 2, 3).map(i => double(i)) // List(2,4,6)
+val b = List(1, 2, 3).map(double) // List(2,4,6)
+```
+
+{% endtab %}
+{% endtabs %}
+
+> 如果您以前从未见过 `map` 方法，它会将给定的函数应用于列表中的每个元素，从而生成一个包含结果值的新列表。
+
+将 lambda 传递给集合类上的高阶函数（如 `List`）是 Scala 体验的一部分，您每天都会这样做。
+
+## 不可变集合
+
+当您使用不可变集合（如 `List`，`Vector`）以及不可变的 `Map` 和 `Set` 类时，重要的是要知道这些函数不会改变它们被调用的集合；相反，它们返回包含更新数据的新集合。
+因此，以“流式”的风格将它们链接在一起以解决问题也很常见。
+
+例如，此示例演示如何对一个集合进行两次筛选，然后将其余集合中的每个元素乘某个数：
+
+{% tabs function_3 %}
+{% tab 'Scala 2 and 3' for=function_3 %}
+
+```scala
+// a sample list
+val nums = (1 to 10).toList // List(1,2,3,4,5,6,7,8,9,10)
+
+// methods can be chained together as needed
+val x = nums.filter(_ > 3)
+ .filter(_ < 7)
+ .map(_ * 10)
+
+// result: x == List(40, 50, 60)
+```
+
+{% endtab %}
+{% endtabs %}
+
+除了在整个标准库中使用的高阶函数外，您还可以[创建自己的][higher-order] 高阶函数。
+
+[higher-order]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-hello-world.md b/_zh-cn/overviews/scala3-book/taste-hello-world.md
new file mode 100644
index 0000000000..cebe30f7fa
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-hello-world.md
@@ -0,0 +1,202 @@
+---
+title: Hello, World!
+type: section
+description: This section demonstrates a Scala 3 'Hello, World!' example.
+language: zh-cn
+num: 5
+previous-page: taste-intro
+next-page: taste-repl
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+> **提示**：在以下示例中，尝试选择您喜欢的 Scala 版本。
+>
+
+## 你的第一个 Scala 程序
+
+Scala “Hello, world!” 例子展示如下。
+首先，把以下代码写入 _Hello.scala_:
+
+
+{% tabs hello-world-demo class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=hello-world-demo %}
+```scala
+object hello {
+ def main(args: Array[String]) = {
+ println("Hello, World!")
+ }
+}
+```
+> 代码中，在名为 `hello` 的 Scala `object` 中，我们定义了一个名称为 `main` 的方法。
+> 在 Scala 中 `object` 类似 `class`，但定义了一个可以传递的单例实例。
+> `main` 用名为 `args` 的输入参数，该参数必须是 `Array[String]` 类型（暂时忽略 `args`）。
+
+{% endtab %}
+
+{% tab 'Scala 3' for=hello-world-demo %}
+```scala
+@main def hello() = println("Hello, World!")
+```
+> 代码中， `hello` 是方法。
+> 它使用 `def` 定义，并用 `@main` 注释的手段把它声明为“main”方法。
+> 使用 `println` 方法，它在标准输出 （STDOUT）中打印了 `"Hello, world!"` 字符串。
+
+{% endtab %}
+
+{% endtabs %}
+
+
+下一步，用 `scalac` 编译代码：
+
+```bash
+$ scalac Hello.scala
+```
+
+如果你是从 Java 转到 Scala，`scalac` 就像 `javac`，所以该命令会创建几个文件：
+
+
+{% tabs hello-world-outputs class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=hello-world-outputs %}
+```bash
+$ ls -1
+hello$.class
+hello.class
+hello.scala
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=hello-world-outputs %}
+```bash
+$ ls -1
+hello$package$.class
+hello$package.class
+hello$package.tasty
+hello.scala
+hello.class
+hello.tasty
+```
+{% endtab %}
+
+{% endtabs %}
+
+
+与 Java 一样，_.class_ 文件是字节码文件，它们已准备好在 JVM 中运行。
+
+现在您可以使用 `scala` 命令运行 `hello` 方法：
+
+```bash
+$ scala hello
+Hello, world!
+```
+
+假设它运行成功，那么恭喜，您刚刚编译并运行了您的第一个 Scala 应用程序。
+
+> 在 [Scala 工具][scala_tools] 章节中可以找到 sbt 和其他使 Scala 开发更容易的工具相关的更多信息。
+
+## 要求用户输入
+
+在下一个示例中，让我们在问候用户之前询问用户名！
+
+有几种方法可以从命令行读取输入，但一种简单的方法是使用
+_scala.io.StdIn_ 对象中的 `readline` 方法。要使用它，您需要先导入它，如下所示：
+
+{% tabs import-readline %}
+{% tab 'Scala 2 and 3' for=import-readline %}
+```scala
+import scala.io.StdIn.readLine
+```
+{% endtab %}
+{% endtabs %}
+
+为了演示其工作原理，让我们创建一个小示例。将此源代码放在名为 _helloInteractive.scala_ 的文件里：
+
+
+{% tabs hello-world-interactive class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=hello-world-interactive %}
+```scala
+import scala.io.StdIn.readLine
+
+object helloInteractive {
+
+ def main(args: Array[String]) = {
+ println("Please enter your name:")
+ val name = readLine()
+
+ println("Hello, " + name + "!")
+ }
+
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=hello-world-interactive %}
+```scala
+import scala.io.StdIn.readLine
+
+@main def helloInteractive() =
+ println("Please enter your name:")
+ val name = readLine()
+
+ println("Hello, " + name + "!")
+```
+{% endtab %}
+
+{% endtabs %}
+
+
+在此代码中，我们将 `readLine` 的结果保存到一个名为 `name` 的变量中，然后
+使用字符串上的 `+` 运算符将 `“Hello， ”` 与 `name` 和 `"!"` 连接起来，生成单一字符串值。
+
+> 您可以通过阅读[变量和数据类型]（/zh-cn/scala3/book/taste-vars-data-types.html）来了解有关使用 `val` 的更多信息。
+
+然后使用 `scalac` 编译代码：
+
+```bash
+$ scalac helloInteractive.scala
+```
+
+然后用 `scala helloInteractive` 运行它，这次程序将在询问您的名字后暂停并等待，
+直到您键入一个名称，然后按键盘上的回车键，如下所示：
+
+```bash
+$ scala helloInteractive
+Please enter your name:
+▌
+```
+
+当您在提示符下输入您的姓名时，最终的交互应如下所示：
+
+```bash
+$ scala helloInteractive
+Please enter your name:
+Alvin Alexander
+Hello, Alvin Alexander!
+```
+
+### 关于导入的说明
+
+正如您在此应用程序中看到的，有时某些方法或我们稍后将看到的其他类型的定义不可用，
+除非您使用如下所示的 `导入` 子句：
+
+{% tabs import-readline-2 %}
+{% tab 'Scala 2 and 3' for=import-readline-2 %}
+```scala
+import scala.io.StdIn.readLine
+```
+{% endtab %}
+{% endtabs %}
+
+导入可通过多种方式帮助您编写代码：
+ - 您可以将代码放在多个文件中，以帮助避免混乱，并帮助导航大型项目。
+ - 您可以使用包含有用功能的代码库，该库可能是由其他人编写
+ - 您可以知道某个定义的来源（特别是如果它没有写入当前文件）。
+
+[scala_tools]: {% link _zh-cn/overviews/scala3-book/scala-tools.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-intro.md b/_zh-cn/overviews/scala3-book/taste-intro.md
new file mode 100644
index 0000000000..0d2f0fdf50
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-intro.md
@@ -0,0 +1,27 @@
+---
+title: Scala 的味道
+type: chapter
+description: This chapter provides a high-level overview of the main features of the Scala 3 programming language.
+language: zh-cn
+num: 4
+previous-page: why-scala-3
+next-page: taste-hello-world
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本章提供的快速导览涉及 Scala 3 编程语言的主要特性。
+在本导览之后，本书的其余部分提供了有关这些特性的更多详细信息，而[参考文档][reference]提供了_许多_ 细节。
+
+## 设置 Scala
+
+在本章和本书的其余部分，我们鼓励您通过复制或手动键入来尝试这些示例。遵循示例所需的工具你可以按照我们的[入门指南][get-started]在自己的计算机上安装。
+
+> 或者，您可以使用 [Scastie](https://scastie.scala-lang.org) 在 Web 浏览器中运行这些示例，这是一个完全在线的编辑器和 Scala 的代码运行器。
+
+[reference]: {{ site.scala3ref }}/overview.html
+[get-started]: {% link _overviews/getting-started/install-scala.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-methods.md b/_zh-cn/overviews/scala3-book/taste-methods.md
new file mode 100644
index 0000000000..521c093a8e
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-methods.md
@@ -0,0 +1,217 @@
+---
+title: 方法
+type: section
+description: This section provides an introduction to defining and using methods in Scala 3.
+language: zh-cn
+num: 10
+previous-page: taste-modeling
+next-page: taste-functions
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+## Scala 方法
+
+Scala 类、样例类、traits、枚举和对象都可以包含方法。
+简单方法的语法如下所示：
+
+{% tabs method_1 %}
+{% tab 'Scala 2 and 3' for=method_1 %}
+
+```scala
+def methodName(param1: Type1, param2: Type2): ReturnType =
+ // the method body
+ // goes here
+```
+
+{% endtab %}
+{% endtabs %}
+
+这有一些例子：
+
+{% tabs method_2 %}
+{% tab 'Scala 2 and 3' for=method_2 %}
+
+```scala
+def sum(a: Int, b: Int): Int = a + b
+def concatenate(s1: String, s2: String): String = s1 + s2
+```
+
+{% endtab %}
+{% endtabs %}
+
+您不必声明方法的返回类型，因此如果您愿意，可以像这样编写这些方法：
+
+{% tabs method_3 %}
+{% tab 'Scala 2 and 3' for=method_3 %}
+
+```scala
+def sum(a: Int, b: Int) = a + b
+def concatenate(s1: String, s2: String) = s1 + s2
+```
+
+{% endtab %}
+{% endtabs %}
+
+这是你如何调用这些方法：
+
+{% tabs method_4 %}
+{% tab 'Scala 2 and 3' for=method_4 %}
+
+```scala
+val x = sum(1, 2)
+val y = concatenate("foo", "bar")
+```
+
+{% endtab %}
+{% endtabs %}
+
+这是一个多行的方法：
+
+{% tabs method_5 class=tabs-scala-version %}
+{% tab 'Scala 2' for=method_5 %}
+
+```scala
+def getStackTraceAsString(t: Throwable): String = {
+ val sw = new StringWriter
+ t.printStackTrace(new PrintWriter(sw))
+ sw.toString
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=method_5 %}
+
+```scala
+def getStackTraceAsString(t: Throwable): String =
+ val sw = new StringWriter
+ t.printStackTrace(new PrintWriter(sw))
+ sw.toString
+```
+
+{% endtab %}
+{% endtabs %}
+
+方法参数也可以具有默认值。
+在此示例中，`timeout` 参数的默认值为 `5000`：
+
+{% tabs method_6 %}
+{% tab 'Scala 2 and 3' for=method_6 %}
+
+```scala
+def makeConnection(url: String, timeout: Int = 5000): Unit =
+ println(s"url=$url, timeout=$timeout")
+```
+
+{% endtab %}
+{% endtabs %}
+
+由于方法声明中提供了默认的 `超时` 值，因此可以通过以下两种方式调用该方法：
+
+{% tabs method_7 %}
+{% tab 'Scala 2 and 3' for=method_7 %}
+
+```scala
+makeConnection("https://localhost") // url=http://localhost, timeout=5000
+makeConnection("https://localhost", 2500) // url=http://localhost, timeout=2500
+```
+
+{% endtab %}
+{% endtabs %}
+
+Scala 还支持在调用方法时使用 _命名参数_，因此如果您愿意，也可以像这样调用该方法：
+
+{% tabs method_8 %}
+{% tab 'Scala 2 and 3' for=method_8 %}
+
+```scala
+makeConnection(
+ url = "https://localhost",
+ timeout = 2500
+)
+```
+
+{% endtab %}
+{% endtabs %}
+
+当多个方法参数具有相同的类型时，命名参数特别有用。
+乍一看，使用此方法，您可能想知道哪些参数设置为 `true` 或 `false`：
+
+{% tabs method_9 %}
+{% tab 'Scala 2 and 3' for=method_9 %}
+
+```scala
+engage(true, true, true, false)
+```
+
+{% endtab %}
+{% endtabs %}
+
+如果没有IDE的帮助，那段代码可能很难阅读，但这个代码要明显得多：
+
+{% tabs method_10 %}
+{% tab 'Scala 2 and 3' for=method_10 %}
+
+```scala
+engage(
+ speedIsSet = true,
+ directionIsSet = true,
+ picardSaidMakeItSo = true,
+ turnedOffParkingBrake = false
+)
+```
+{% endtab %}
+{% endtabs %}
+
+## 扩展方法
+
+_扩展方法_ 允许您向封闭类添加新方法。
+例如，如果要将两个名为 `hello` 和 `aloha` 的方法添加到 `String` 类中，请将它们声明为扩展方法：
+
+{% tabs extension0 %}
+{% tab 'Scala 3 Only' %}
+
+```scala
+extension (s: String)
+ def hello: String = s"Hello, ${s.capitalize}!"
+ def aloha: String = s"Aloha, ${s.capitalize}!"
+
+"world".hello // "Hello, World!"
+"friend".aloha // "Aloha, Friend!"
+```
+
+{% endtab %}
+{% endtabs %}
+
+`extension` 关键字声明了括号内的参数将定义一个或多个扩展方法。
+如此示例所示，可以在扩展方法体中使用 `String` 类型的参数 `s`。
+
+下一个示例演示如何将 `makeInt` 方法添加到 `String` 类。
+在这里，`makeInt` 采用一个名为 `radix` 的参数。
+该代码不考虑可能的字符串到整数转换错误，但跳过细节，示例显示了它的工作原理：
+
+{% tabs extension %}
+{% tab 'Scala 3 Only' %}
+
+```scala
+extension (s: String)
+ def makeInt(radix: Int): Int = Integer.parseInt(s, radix)
+
+"1".makeInt(2) // Int = 1
+"10".makeInt(2) // Int = 2
+"100".makeInt(2) // Int = 4
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 参见
+
+Scala方法可以更强大：它们可以采用类型参数和上下文参数。
+它们在[领域建模][data-1]一节中有详细介绍。
+
+[data-1]: {% link _zh-cn/overviews/scala3-book/domain-modeling-tools.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-modeling.md b/_zh-cn/overviews/scala3-book/taste-modeling.md
new file mode 100644
index 0000000000..ca39aafe34
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-modeling.md
@@ -0,0 +1,428 @@
+---
+title: 领域建模
+type: section
+description: This section provides an introduction to data modeling in Scala 3.
+language: zh-cn
+num: 9
+previous-page: taste-control-structures
+next-page: taste-methods
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+{% comment %}
+NOTE: I kept the OOP section first, assuming that most readers will be coming from an OOP background.
+{% endcomment %}
+
+Scala 同时支持函数式编程 (FP) 和面向对象编程 (OOP)，以及这两种范式的融合。
+本节简要概述了 OOP 和 FP 中的数据建模。
+
+## OOP 领域建模
+
+以 OOP 风格编写代码时，用于数据封装的两个主要工具是 _traits_ 和 _classes_。
+
+{% comment %}
+NOTE: Julien had a comment, “in OOP we don’t really model data.
+It’s more about modeling operations, imho.”
+
+How to resolve? Is there a good DDD term to use here?
+{% endcomment %}
+
+### Traits
+
+Scala trait 可以用作简单的接口，但它们也可以包含抽象和具体的方法和字段，并且它们可以有参数，就像类一样。
+它们为您提供了一种将行为组织成小型模块化单元的好方法。
+稍后，当您想要创建属性和行为的具体实现时，类和对象可以扩展特征，根据需要混合尽可能多的特征以实现所需的行为。
+
+作为如何将 traits 用作接口的示例，以下是三个 traits，它们为狗和猫等动物定义了结构良好并且模块化的行为：
+
+{% tabs traits class=tabs-scala-version %}
+{% tab 'Scala 2' for=traits %}
+
+```scala
+trait Speaker {
+ def speak(): String // has no body, so it’s abstract
+}
+
+trait TailWagger {
+ def startTail(): Unit = println("tail is wagging")
+ def stopTail(): Unit = println("tail is stopped")
+}
+
+trait Runner {
+ def startRunning(): Unit = println("I’m running")
+ def stopRunning(): Unit = println("Stopped running")
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=traits %}
+
+
+```scala
+trait Speaker:
+ def speak(): String // has no body, so it’s abstract
+
+trait TailWagger:
+ def startTail(): Unit = println("tail is wagging")
+ def stopTail(): Unit = println("tail is stopped")
+
+trait Runner:
+ def startRunning(): Unit = println("I’m running")
+ def stopRunning(): Unit = println("Stopped running")
+```
+
+{% endtab %}
+{% endtabs %}
+
+鉴于这些特征，这里有一个 `Dog` 类，它扩展了所有这些特征，同时为抽象 `speak` 方法提供了一种行为：
+
+{% tabs traits-class class=tabs-scala-version %}
+{% tab 'Scala 2' for=traits-class %}
+
+```scala
+class Dog(name: String) extends Speaker with TailWagger with Runner {
+ def speak(): String = "Woof!"
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=traits-class %}
+
+```scala
+class Dog(name: String) extends Speaker, TailWagger, Runner:
+ def speak(): String = "Woof!"
+```
+
+{% endtab %}
+{% endtabs %}
+
+请注意该类如何使用 `extends` 关键字扩展 traits。
+
+类似地，这里有一个 `Cat` 类，它实现了这些相同的 traits，同时还覆盖了它继承的两个具体方法：
+
+{% tabs traits-override class=tabs-scala-version %}
+{% tab 'Scala 2' for=traits-override %}
+
+```scala
+class Cat(name: String) extends Speaker with TailWagger with Runner {
+ def speak(): String = "Meow"
+ override def startRunning(): Unit = println("Yeah ... I don’t run")
+ override def stopRunning(): Unit = println("No need to stop")
+}
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=traits-override %}
+
+```scala
+class Cat(name: String) extends Speaker, TailWagger, Runner:
+ def speak(): String = "Meow"
+ override def startRunning(): Unit = println("Yeah ... I don’t run")
+ override def stopRunning(): Unit = println("No need to stop")
+```
+
+{% endtab %}
+{% endtabs %}
+
+这些示例显示了如何使用这些类：
+
+{% tabs traits-use class=tabs-scala-version %}
+{% tab 'Scala 2' for=traits-use %}
+
+```scala
+val d = new Dog("Rover")
+println(d.speak()) // prints "Woof!"
+
+val c = new Cat("Morris")
+println(c.speak()) // "Meow"
+c.startRunning() // "Yeah ... I don’t run"
+c.stopRunning() // "No need to stop"
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=traits-use %}
+
+```scala
+val d = Dog("Rover")
+println(d.speak()) // prints "Woof!"
+
+val c = Cat("Morris")
+println(c.speak()) // "Meow"
+c.startRunning() // "Yeah ... I don’t run"
+c.stopRunning() // "No need to stop"
+```
+
+{% endtab %}
+{% endtabs %}
+
+如果该代码有意义---太好了，您把 traits 作为接口感到舒服。
+如果没有，请不要担心，它们在 [Domain Modeling][data-1] 章节中有更详细的解释。
+
+### 类
+
+Scala _classes_ 用于 OOP 风格的编程。
+这是一个模拟“人”的类的示例。在 OOP 中，字段通常是可变的，所以 `firstName` 和 `lastName` 都被声明为 `var` 参数：
+
+{% tabs class_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=class_1 %}
+
+```scala
+class Person(var firstName: String, var lastName: String) {
+ def printFullName() = println(s"$firstName $lastName")
+}
+
+val p = new Person("John", "Stephens")
+println(p.firstName) // "John"
+p.lastName = "Legend"
+p.printFullName() // "John Legend"
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=class_1 %}
+
+```scala
+class Person(var firstName: String, var lastName: String):
+ def printFullName() = println(s"$firstName $lastName")
+
+val p = Person("John", "Stephens")
+println(p.firstName) // "John"
+p.lastName = "Legend"
+p.printFullName() // "John Legend"
+```
+
+{% endtab %}
+{% endtabs %}
+
+请注意，类声明创建了一个构造函数：
+
+{% tabs class_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=class_2 %}
+
+```scala
+// this code uses that constructor
+val p = new Person("John", "Stephens")
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=class_2 %}
+
+```scala
+// 此代码使用该构造函数
+val p = Person("约翰", "斯蒂芬斯")
+```
+
+{% endtab %}
+{% endtabs %}
+
+[Domain Modeling][data-1] 章节中介绍了构造函数和其他与类相关的主题。
+
+## FP 领域建模
+
+{% comment %}
+NOTE: Julien had a note about expecting to see sealed traits here.
+I didn’t include that because I didn’t know if enums are intended
+to replace the Scala2 “sealed trait + case class” pattern. How to resolve?
+{% endcomment %}
+
+以 FP 风格编写代码时，您将使用以下结构：
+
+- 代数数据类型（ADT）来定义数据
+- Traits 来定义数据上的功能
+
+### 枚举和 Sum Types
+
+Sum types 是在 Scala 中给代数数据类型（ADT）建模的一种方法。
+
+`enum` 构造是在 Scala 3 中对代数数据类型 (ADT) 进行建模的好方法。
+
+例如，披萨具有三个主要属性：
+
+- 面饼大小
+- 面饼类型
+- 馅料
+
+这些是用枚举简洁地建模的，它们是只包含单例值的 sum types：
+
+{% tabs enum_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=enum_1 %}
+
+在 Scala 2 中，用 `sealed` 类和 `case object` 组合在一起来定义枚举:
+
+```scala
+sealed abstract class CrustSize
+object CrustSize {
+ case object Small extends CrustSize
+ case object Medium extends CrustSize
+ case object Large extends CrustSize
+}
+
+sealed abstract class CrustType
+object CrustType {
+ case object Thin extends CrustType
+ case object Thick extends CrustType
+ case object Regular extends CrustType
+}
+
+sealed abstract class Topping
+object Topping {
+ case object Cheese extends Topping
+ case object Pepperoni extends Topping
+ case object BlackOlives extends Topping
+ case object GreenOlives extends Topping
+ case object Onions extends Topping
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=enum_1 %}
+
+Scala 3 提供了 `enum` 结构来定义枚举：
+
+```scala
+enum CrustSize:
+ case Small, Medium, Large
+
+enum CrustType:
+ case Thin, Thick, Regular
+
+enum Topping:
+ case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions
+```
+
+{% endtab %}
+{% endtabs %}
+
+一旦你有了一个枚举，你就可以按照你通常使用特征、类或对象的所有方式来使用枚举：
+
+{% tabs enum_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=enum_2 %}
+
+```scala
+import CrustSize._
+val currentCrustSize = Small
+
+// enums in a `match` expression
+currentCrustSize match {
+ case Small => println("Small crust size")
+ case Medium => println("Medium crust size")
+ case Large => println("Large crust size")
+}
+
+// enums in an `if` statement
+if (currentCrustSize == Small) println("Small crust size")
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=enum_2 %}
+
+```scala
+import CrustSize.*
+val currentCrustSize = Small
+
+// enums in a `match` expression
+currentCrustSize match
+ case Small => println("Small crust size")
+ case Medium => println("Medium crust size")
+ case Large => println("Large crust size")
+
+// enums in an `if` statement
+if currentCrustSize == Small then println("Small crust size")
+```
+
+{% endtab %}
+{% endtabs %}
+
+下面是另一个如何在 Scala 中创建 sum type 的示例，它不能被叫作枚举，因为 `succ` 样例类有参数：的示例：
+
+{% tabs enum_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=enum_3 %}
+
+```scala
+sealed abstract class Nat
+object Nat {
+ case object Zero extends Nat
+ case class Succ(pred: Nat) extends Nat
+}
+```
+
+Sum Types 在本书的[领域建模]({% link _overviews/scala3-book/domain-modeling-tools.md %})部分有详细的介绍。
+
+{% endtab %}
+{% tab 'Scala 3' for=enum_3 %}
+
+```scala
+enum Nat:
+ case Zero
+ case Succ(pred: Nat)
+```
+
+枚举在本书的 [领域建模]({% link _overviews/scala3-book/domain-modeling-tools.md %})部分和 [参考文档]({{ site.scala3ref }}/enums/enums.html) 中有详细介绍。
+
+{% endtab %}
+{% endtabs %}
+
+### Product Types
+
+product type 是代数数据类型（ADT），它只含有一个形状，例如一个单例对象，在Scala 中用 `case` 对象来代表；或者是一个可以获取字段的不可变结构，用 `case` 类来代表。
+
+`case` 类具有 `class` 的所有功能，还包含其他功能，使它们对函数式编程很有用。
+当编译器在 `class` 前面看到 `case` 关键字时，它具有以下效果和好处：
+
+- 样例类构造函数参数默认为 public `val` 字段，因此字段是不可变的，并且为每个参数生成访问器方法。
+- 生成一个 `unapply` 方法，它允许您在 `match` 表达式中以更多方式使用 样例类。
+- 在类中生成一个 `copy` 方法。
+ 这提供了一种在不更改原始对象的情况下创建对象的更新副本的方法。
+- 生成 `equals` 和 `hashCode` 方法来实现结构相等等式。
+- 生成一个默认的 `toString` 方法，有助于调试。
+
+{% comment %}
+NOTE: Julien had a comment about how he decides when to use case classes vs classes. Add something here?
+{% endcomment %}
+
+您_可以_自己手动将所有这些方法添加到一个类中，但是由于这些功能在函数式编程中非常常用，因此使用“case”类要方便得多。
+
+这段代码演示了几个 `case` 类的特性：
+
+{% tabs case-class %}
+{% tab 'Scala 2 and 3' for=case-class %}
+
+```scala
+// define a case class
+case class Person(
+ name: String,
+ vocation: String
+)
+
+// create an instance of the case class
+val p = Person("Reginald Kenneth Dwight", "Singer")
+
+// a good default toString method
+p // : Person = Person(Reginald Kenneth Dwight,Singer)
+
+// can access its fields, which are immutable
+p.name // "Reginald Kenneth Dwight"
+p.name = "Joe" // error: can’t reassign a val field
+
+// when you need to make a change, use the `copy` method
+// to “update as you copy”
+val p2 = p.copy(name = "Elton John")
+p2 // : Person = Person(Elton John,Singer)
+```
+
+{% endtab %}
+{% endtabs %}
+
+有关 `case` 类的更多详细信息，请参阅 [领域建模][data-1] 部分。
+
+[data-1]: {% link _zh-cn/overviews/scala3-book/domain-modeling-tools.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-objects.md b/_zh-cn/overviews/scala3-book/taste-objects.md
new file mode 100644
index 0000000000..3d3ec5457e
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-objects.md
@@ -0,0 +1,172 @@
+---
+title: 单例对象
+type: section
+description: This section provides an introduction to the use of singleton objects in Scala 3.
+language: zh-cn
+num: 12
+previous-page: taste-functions
+next-page: taste-collections
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+在 Scala 中，`object` 关键字创建一个单例对象。
+换句话说，对象定义了一个只有一个实例的类。
+
+对象有多种用途：
+
+- 它们用于创建实用程序方法的集合。
+- _伴生对象_ 与一个类同名二者在同一个文件里。
+ 在此情况下，该类也称为 _伴生类_。
+- 它们用于实现 traits，再用 traits 来创建 _模块_。
+
+## “实用工具”方法
+
+因为 `object` 是单例，所以它的方法可以像 Java 类中的 `static` 方法一样被访问。
+例如，此 `StringUtils` 对象包含一个与字符串相关的方法的小型集合：
+
+{% tabs object_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=object_1 %}
+
+```scala
+object StringUtils {
+ def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty
+ def leftTrim(s: String): String = s.replaceAll("^\\s+", "")
+ def rightTrim(s: String): String = s.replaceAll("\\s+$", "")
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=object_1 %}
+
+```scala
+object StringUtils:
+ def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty
+ def leftTrim(s: String): String = s.replaceAll("^\\s+", "")
+ def rightTrim(s: String): String = s.replaceAll("\\s+$", "")
+```
+
+{% endtab %}
+{% endtabs %}
+
+由于 `StringUtils` 是一个单例，因此可以直接在对象上调用其方法：
+
+{% tabs object_2 %}
+{% tab 'Scala 2 and 3' for=object_2 %}
+
+```scala
+val x = StringUtils.isNullOrEmpty("") // true
+val x = StringUtils.isNullOrEmpty("a") // false
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 伴生对象
+
+伴生类或对象可以访问其伙伴的私有成员。
+对不特定于伴生类实例的方法和值使用伴生对象。
+
+此示例演示了伴生类中的 `area` 方法如何访问其伴生对象中的私有 `calculateArea` 方法：
+
+{% tabs object_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=object_3 %}
+
+```scala
+import scala.math._
+
+class Circle(radius: Double) {
+ import Circle._
+ def area: Double = calculateArea(radius)
+}
+
+object Circle {
+ private def calculateArea(radius: Double): Double =
+ Pi * pow(radius, 2.0)
+}
+
+val circle1 = new Circle(5.0)
+circle1.area // Double = 78.53981633974483
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=object_3 %}
+
+```scala
+import scala.math.*
+
+class Circle(radius: Double):
+ import Circle.*
+ def area: Double = calculateArea(radius)
+
+object Circle:
+ private def calculateArea(radius: Double): Double =
+ Pi * pow(radius, 2.0)
+
+val circle1 = Circle(5.0)
+circle1.area // Double = 78.53981633974483
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 从 traits 创建模块
+
+对象还可用于实现创建模块的 trait。
+这种技术需要两个traits，并将它们结合起来创建一个具体的 `object`：
+
+{% tabs object_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=object_4 %}
+
+```scala
+trait AddService {
+ def add(a: Int, b: Int) = a + b
+}
+
+trait MultiplyService {
+ def multiply(a: Int, b: Int) = a * b
+}
+
+// implement those traits as a concrete object
+object MathService extends AddService with MultiplyService
+
+// use the object
+import MathService._
+println(add(1,1)) // 2
+println(multiply(2,2)) // 4
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=object_4 %}
+
+```scala
+trait AddService:
+ def add(a: Int, b: Int) = a + b
+
+trait MultiplyService:
+ def multiply(a: Int, b: Int) = a * b
+
+// implement those traits as a concrete object
+object MathService extends AddService, MultiplyService
+
+// use the object
+import MathService.*
+println(add(1,1)) // 2
+println(multiply(2,2)) // 4
+```
+
+{% endtab %}
+{% endtabs %}
+
+{% comment %}
+NOTE: I don’t know if this is worth keeping, but I’m leaving it here as a comment for now.
+
+> You may read that objects are used to _reify_ traits into modules.
+> _Reify_ means, “to take an abstract concept and turn it into something concrete.” This is what happens in these examples, but “implement” is a more familiar word for most people than “reify.”
+{% endcomment %}
+
+
diff --git a/_zh-cn/overviews/scala3-book/taste-repl.md b/_zh-cn/overviews/scala3-book/taste-repl.md
new file mode 100644
index 0000000000..2b043bef03
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-repl.md
@@ -0,0 +1,92 @@
+---
+title: The REPL
+type: section
+description: This section provides an introduction to the Scala REPL.
+language: zh-cn
+num: 6
+previous-page: taste-hello-world
+next-page: taste-vars-data-types
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala REPL（“Read-Evaluate-Print-Loop”）是一个命令行解释器，您可以将其用作“游乐场”区域来测试 Scala 代码。
+你可以通过运行 `scala` 或 `scala3` 命令来启动一个 REPL 会话，具体取决于您在操作系统命令行中的安装，您将看到如下所示的“欢迎”提示：
+
+{% tabs command-line class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=command-line %}
+```bash
+$ scala
+Welcome to Scala {{site.scala-version}} (OpenJDK 64-Bit Server VM, Java 1.8.0_342).
+Type in expressions for evaluation. Or try :help.
+
+scala> _
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=command-line %}
+```bash
+$ scala
+Welcome to Scala {{site.scala-3-version}} (1.8.0_322, Java OpenJDK 64-Bit Server VM).
+Type in expressions for evaluation. Or try :help.
+
+scala> _
+```
+{% endtab %}
+
+{% endtabs %}
+
+REPL 是一个命令行解释器，所以它就在那里等着你输入一些东西。
+现在您可以输入 Scala 表达式来查看它们是如何工作的：
+
+{% tabs expression-one %}
+{% tab 'Scala 2 and 3' for=expression-one %}
+````
+scala> 1 + 1
+val res0: Int = 2
+
+scala> 2 + 2
+val res1: Int = 4
+````
+{% endtab %}
+{% endtabs %}
+
+如输出所示，如果您不为表达式的结果分配变量，REPL 会为您创建名为 `res0`、`res1` 等的变量。
+您可以在后续表达式中使用这些变量名称：
+
+{% tabs expression-two %}
+{% tab 'Scala 2 and 3' for=expression-two %}
+````
+scala> val x = res0 * 10
+val x: Int = 20
+````
+{% endtab %}
+{% endtabs %}
+
+请注意，REPL 输出还显示了表达式的结果。
+
+您可以在 REPL 中运行各种实验。
+这个例子展示了如何创建然后调用一个 `sum` 方法：
+
+{% tabs expression-three %}
+{% tab 'Scala 2 and 3' for=expression-three %}
+````
+scala> def sum(a: Int, b: Int): Int = a + b
+def sum(a: Int, b: Int): Int
+
+scala> sum(2, 2)
+val res2: Int = 4
+````
+{% endtab %}
+{% endtabs %}
+
+如果您更喜欢基于浏览器的游乐场环境，也可以使用 [scastie.scala-lang.org](https://scastie.scala-lang.org)。
+
+如果您更喜欢在文本编辑器中而不是在控制台提示符中编写代码，您可以使用 [worksheet]。
+
+[worksheet]: {% link _zh-cn/overviews/scala3-book/tools-worksheets.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-summary.md b/_zh-cn/overviews/scala3-book/taste-summary.md
new file mode 100644
index 0000000000..1fee593727
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-summary.md
@@ -0,0 +1,35 @@
+---
+title: 总结
+type: section
+description: This page provides a summary of the previous 'Taste of Scala' sections.
+language: zh-cn
+num: 16
+previous-page: taste-toplevel-definitions
+next-page: first-look-at-types
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+在前面的部分中，您看到了：
+
+- 如何使用 Scala REPL
+- 如何使用 `val` 和 `var` 创建变量
+- 一些常见的数据类型
+- 控制结构
+- 如何使用 OOP 和 FP 样式对现实世界进行建模
+- 如何创建和使用方法
+- 如何使用lambdas（匿名函数）和高阶函数
+- 如何将对象用于多种目的
+- [上下文抽象][contextual]的介绍
+
+我们还提到，如果您更喜欢使用基于浏览器的游乐场环境而不是 Scala REPL，您还可以使用[Scastie](https://scastie.scala-lang.org)。
+
+Scala还有更多功能在这次旋风之旅中没有涵盖。
+有关更多详细信息，请参阅本书的其余部分和[参考文档][reference]。
+
+[reference]: {{ site.scala3ref }}/overview.html
+[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %}
diff --git a/_zh-cn/overviews/scala3-book/taste-toplevel-definitions.md b/_zh-cn/overviews/scala3-book/taste-toplevel-definitions.md
new file mode 100644
index 0000000000..7deb81d9de
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-toplevel-definitions.md
@@ -0,0 +1,80 @@
+---
+title: 顶层定义
+type: section
+description: This page provides an introduction to top-level definitions in Scala 3
+language: zh-cn
+num: 15
+previous-page: taste-contextual-abstractions
+next-page: taste-summary
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+在 Scala 3 中，各种定义都可以在源代码文件的 “顶层” 编写。
+例如，您可以创建一个名为 _MyCoolApp.scala_ 的文件，并将以下内容放入其中：
+
+{% tabs toplevel_1 %}
+{% tab 'Scala 3 only' for=toplevel_1 %}
+
+```scala
+import scala.collection.mutable.ArrayBuffer
+
+enum Topping:
+ case Cheese, Pepperoni, Mushrooms
+
+import Topping.*
+class Pizza:
+ val toppings = ArrayBuffer[Topping]()
+
+val p = Pizza()
+
+extension (s: String)
+ def capitalizeAllWords = s.split(" ").map(_.capitalize).mkString(" ")
+
+val hwUpper = "hello, world".capitalizeAllWords
+
+type Money = BigDecimal
+
+// more definitions here as desired ...
+
+@main def myApp =
+ p.toppings += Cheese
+ println("show me the code".capitalizeAllWords)
+```
+
+{% endtab %}
+{% endtabs %}
+
+如代码中展示的，无需将这些定义放在 `package`, `class` 或其他构造中。
+
+## 替换包对象
+
+如果你熟悉Scala 2，这种方法可以取代 _包对象_。
+但是，虽然更易于使用，但它们的工作方式类似：当您将定义放在名为 _foo_ 的包中时，您可以在 _foo_ 包内的所有其他包内访问该定义，例如在此示例中的 _foo.bar_ 包中：
+
+{% tabs toplevel_2 %}
+{% tab 'Scala 3 only' for=toplevel_2 %}
+
+```scala
+package foo {
+ def double(i: Int) = i * 2
+}
+
+package foo {
+ package bar {
+ @main def fooBarMain =
+ println(s"${double(1)}") // this works
+ }
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+本示例中使用大括号来强调包嵌套。
+
+这种方法的好处是，您可以将定义放在名为 _com.acme.myapp_ 的包下，然后可以在 _com.acme.myapp.model_、_com.acme.myapp.controller_ 等中引用这些定义。
diff --git a/_zh-cn/overviews/scala3-book/taste-vars-data-types.md b/_zh-cn/overviews/scala3-book/taste-vars-data-types.md
new file mode 100644
index 0000000000..2c5a80e5a0
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/taste-vars-data-types.md
@@ -0,0 +1,293 @@
+---
+title: 变量和数据类型
+type: section
+description: This section demonstrates val and var variables, and some common Scala data types.
+language: zh-cn
+num: 7
+previous-page: taste-repl
+next-page: taste-control-structures
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本节介绍 Scala 变量和数据类型。
+
+## 两种类型的变量
+
+当你在 Scala 中创建一个新变量时，你声明该变量是不可变的还是可变的：
+
+
+
+
+
+这些示例展示了如何创建 `val` 和 `var` 变量：
+
+{% tabs var-express-1 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+// immutable
+val a = 0
+
+// mutable
+var b = 1
+```
+
+{% endtab %}
+{% endtabs %}
+
+在应用程序中，不能重新给一个 `val` 变量赋值。
+如果您尝试重新赋值一个 `val` 变量，将导致编译器错误：
+
+{% tabs var-express-2 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val msg = "Hello, world"
+msg = "Aloha" // "reassignment to val" error; this won’t compile
+```
+
+{% endtab %}
+{% endtabs %}
+
+相反，可以给 `var` 变量重新赋值：
+
+{% tabs var-express-3 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+var msg = "Hello, world"
+msg = "Aloha" // 因为可以重新分配 var，所以可以编译
+```
+
+{% endtab %}
+{% endtabs %}
+
+## 声明变量类型
+
+创建变量时，您可以显式声明其类型，或让编译器推断类型：
+
+{% tabs var-express-4 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val x: Int = 1 // 显式
+val x = 1 // 隐式的；编译器推断类型
+```
+
+{% endtab %}
+{% endtabs %}
+
+第二种形式称为 _类型推断_，它是帮助保持此类代码简洁的好方法。
+Scala 编译器通常可以为您推断数据类型，如以下 REPL 示例的输出所示：
+
+{% tabs var-express-5 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+scala> val x = 1
+val x: Int = 1
+
+scala> val s = "a string"
+val s: String = a string
+
+scala> val nums = List(1, 2, 3)
+val nums: List[Int] = List(1, 2, 3)
+```
+
+{% endtab %}
+{% endtabs %}
+
+如果您愿意，您始终可以显式声明变量的类型，但在像这样的简单赋值中，不须要这样：
+
+{% tabs var-express-6 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val x: Int = 1
+val s: String = "a string"
+val p: Person = Person("Richard")
+```
+
+{% endtab %}
+{% endtabs %}
+
+请注意，使用这种方法会感觉代码太啰嗦。
+
+{% comment %}
+TODO: Jonathan had an early comment on the text below: “While it might feel like this, I would be afraid that people automatically assume from this statement that everything is always boxed.” Suggestion on how to change this?
+{% endcomment %}
+
+## 内置数据类型
+
+Scala 带有你所期望的标准数值数据类型，它们都是类的成熟（full-blown）实例。
+在 Scala 中，一切都是对象。
+
+这些示例展示了如何声明数值类型的变量：
+
+{% tabs var-express-7 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val b: Byte = 1
+val i: Int = 1
+val l: Long = 1
+val s: Short = 1
+val d: Double = 2.0
+val f: Float = 3.0
+```
+
+{% endtab %}
+{% endtabs %}
+
+因为 `Int` 和 `Double` 是默认的数字类型，所以您通常创建它们而不显式声明数据类型：
+
+{% tabs var-express-8 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val i = 123 // 默认为 Int
+val j = 1.0 // 默认为 Double
+```
+
+{% endtab %}
+{% endtabs %}
+
+在您的代码中，您还可以将字符 `L`、`D` 和 `F`（或者它们对应的小写字母）加到数字后面以指定它们是 `Long`、`Double` 或 `Float` 值：
+
+{% tabs var-express-9 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val x = 1_000L // val x: Long = 1000
+val y = 2.2D // val y: Double = 2.2
+val z = 3.3F // val z: Float = 3.3
+```
+
+{% endtab %}
+{% endtabs %}
+
+当您需要非常大的数字时，请使用 `BigInt` 和 `BigDecimal` 类型：
+
+{% tabs var-express-10 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+var a = BigInt(1_234_567_890_987_654_321L)
+var b = BigDecimal(123_456.789)
+```
+
+{% endtab %}
+{% endtabs %}
+
+其中 `Double` 和 `Float` 是近似十进制数，`BigDecimal` 用于精确算术。
+
+Scala 还有 `String` 和 `Char` 数据类型：
+
+{% tabs var-express-11 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val name = "Bill" // String
+val c = 'a' // Char
+```
+
+{% endtab %}
+{% endtabs %}
+
+### 字符串
+
+Scala 字符串类似于 Java 字符串，但它们有两个很棒的附加特性：
+
+- 他们支持字符串插值
+- 创建多行字符串很容易
+
+#### 字符串插值
+
+字符串插值提供了一种非常易读的方式在字符串中使用变量。
+例如，给定这三个变量：
+
+{% tabs var-express-12 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val firstName = "John"
+val mi = 'C'
+val lastName = "Doe"
+```
+
+{% endtab %}
+{% endtabs %}
+
+您可以将这些变量组合在一个字符串中，如下所示：
+
+{% tabs var-express-13 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+println(s"Name: $firstName $mi $lastName") // "Name: John C Doe"
+```
+
+{% endtab %}
+{% endtabs %}
+
+只需在字符串前面加上字母 `s`，然后在字符串中的变量名之前放置一个 `$` 符号。
+
+要将任意表达式嵌入字符串中，请将它们括在花括号中：
+
+{% tabs var-express-14 %}
+{% tab 'Scala 2 and 3' %}
+
+``` scala
+println(s"2 + 2 = ${2 + 2}") // 打印 "2 + 2 = 4"
+
+val x = -1
+println(s"x.abs = ${x.abs}") // 打印 "x.abs = 1"
+```
+
+{% endtab %}
+{% endtabs %}
+
+放在字符串前面的 `s` 只是一种可能的插值器。
+如果使用 `f` 而不是 `s`，则可以在字符串中使用 `printf` 样式的格式化语法。
+此外，字符串插值器只是一种特殊方法，可以定义自己的方法。
+例如，有一些数据库方向的类库定义了非常强大的 `sql` 插值器。
+
+#### 多行字符串
+
+多行字符串是通过将字符串包含在三个双引号内来创建的：
+
+{% tabs var-express-15 %}
+{% tab 'Scala 2 and 3' %}
+
+```scala
+val quote = """The essence of Scala:
+ Fusion of functional and object-oriented
+ programming in a typed setting."""
+```
+
+{% endtab %}
+{% endtabs %}
+
+> 有关字符串插值器和多行字符串的更多详细信息，请参阅[“类型初探”章节][first-look]。
+
+[first-look]: {% link _zh-cn/overviews/scala3-book/first-look-at-types.md %}
diff --git a/_zh-cn/overviews/scala3-book/tools-sbt.md b/_zh-cn/overviews/scala3-book/tools-sbt.md
new file mode 100644
index 0000000000..2b1720c2c9
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/tools-sbt.md
@@ -0,0 +1,496 @@
+---
+title: 使用 sbt 构建和测试 Scala 项目
+type: section
+description: This section looks at a commonly-used build tool, sbt, and a testing library, ScalaTest.
+language: zh-cn
+num: 70
+previous-page: scala-tools
+next-page: tools-worksheets
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+在本节中，您将看到 Scala 项目中常用的两个工具：
+
+- [sbt](https://www.scala-sbt.org) 构建工具
+- [ScalaTest](https://www.scalatest.org)，一个源代码测试框架
+
+我们将首先展示如何使用 sbt 构建您的 Scala 项目，然后我们将展示如何一起使用 sbt 和 ScalaTest 来测试您的 Scala 项目。
+
+> 如果您想了解帮助您将 Scala 2 代码迁移到 Scala 3 的工具，请参阅我们的 [Scala 3 迁移指南](/scala3/guides/migration/compatibility-intro.html)。
+
+## 使用 sbt 构建 Scala 项目
+
+您可以使用多种不同的工具来构建您的 Scala 项目，包括 Ant、Maven、Gradle、Mill 等。
+但是名为 _sbt_ 的工具是第一个专门为 Scala 创建的构建工具。
+
+> 要安装 sbt，请参阅 [其下载页面](https://www.scala-sbt.org/download.html) 或我们的 [Getting Started][getting_started] 页面。
+
+### 创建一个 “Hello, world” 项目
+
+只需几个步骤，您就可以创建一个 sbt “Hello, world” 项目。
+首先，创建一个工作目录，然后进入该目录：
+
+```bash
+$ mkdir hello
+$ cd hello
+```
+
+在 `hello` 目录下，创建一个子目录 `project`：
+
+```bash
+$ mkdir project
+```
+
+在 `project` 目录中创建一个名为 _build.properties_ 的文件，其中
+以下内容：
+
+```text
+sbt.version=1.10.11
+```
+
+然后在包含此行的项目根目录中创建一个名为 _build.sbt_ 的文件：
+
+```scala
+scalaVersion := "{{ site.scala-3-version }}"
+```
+
+现在创建一个名为 _Hello.scala_ 的文件——名称的第一部分无关紧要——使用这一行：
+
+```scala
+@main def helloWorld = println("Hello, world")
+```
+
+这就是你所要做的。
+
+您应该具有如下的项目结构：
+
+~~~ bash
+$ tree
+.
+├── build.sbt
+├── Hello.scala
+└── project
+ └── build.properties
+~~~
+
+现在使用 `sbt` 命令运行项目：
+
+```bash
+$ sbt run
+```
+
+您应该会看到如下所示的输出，包括程序中的 `"Hello, world"`：
+
+```bash
+$ sbt run
+[info] welcome to sbt 1.5.4 (AdoptOpenJDK Java 11.x)
+[info] loading project definition from project ...
+[info] loading settings for project from build.sbt ...
+[info] compiling 1 Scala source to target/scala-3.0.0/classes ...
+[info] running helloWorld
+Hello, world
+[success] Total time: 2 s
+```
+
+sbt 启动器——`sbt` 命令行工具——加载文件 _project/build.properties_ 中设置的 sbt 版本，它加载文件 _build.sbt_ 中设置的 Scala 编译器版本，编译 _Hello.scala_ 文件中的代码，并运行生成的字节码。
+
+当你查看你的目录时，你会看到 sbt 有一个名为 _target_ 的目录。
+这些是 sbt 使用的工作目录。
+
+如您所见，使用 sbt 创建和运行一个小的 Scala 项目只需要几个简单的步骤。
+
+### 在大型项目中使用 sbt
+
+对于一个小项目，这就是 sbt 运行所需的全部内容。
+对于需要许多源代码文件、依赖项或 sbt 插件的大型项目，您需要创建一个有组织的目录结构。
+本节的其余部分演示了 sbt 使用的结构。
+
+### sbt 目录结构
+
+与 Maven 一样，sbt 使用标准的项目目录结构。
+这样做的一个很好的好处是，一旦你对它的结构感到满意，它就可以很容易地处理其他 Scala/sbt 项目。
+
+首先要知道的是，在项目的根目录下，sbt 需要一个如下所示的目录结构：
+
+```text
+.
+├── build.sbt
+├── project/
+│ └── build.properties
+├── src/
+│ ├── main/
+│ │ ├── java/
+│ │ ├── resources/
+│ │ └── scala/
+│ └── test/
+│ ├── java/
+│ ├── resources/
+│ └── scala/
+└── target/
+```
+
+如果您想将非托管依赖项---JAR 文件---添加到您的项目中，您还可以在根目录下添加一个 _lib_ 目录。
+
+如果您要创建一个包含 Scala 源代码文件和测试的项目，但不会使用任何 Java 源代码文件，并且不需要任何“资源”——例如嵌入式图像、配置文件、等等---这就是你在_src_目录下真正需要的：
+
+```text
+.
+└── src/
+ ├── main/
+ │ └── scala/
+ └── test/
+ └── scala/
+```
+
+### 带有 sbt 目录结构的 “Hello, world”
+
+{% comment %}
+LATER: using something like `sbt new scala/scala3.g8` may eventually
+ be preferable, but that seems to have a few bugs atm (creates
+ a 'target' directory above the root; renames the root dir;
+ uses 'dottyVersion'; 'name' doesn’t match the supplied name;
+ config syntax is a little hard for beginners.)
+{% endcomment %}
+
+创建这个目录结构很简单。
+有一些工具可以为你做到这一点，但假设你使用的是 Unix/Linux 系统，你可以使用这些命令来创建你的第一个 sbt 项目目录结构：
+
+```bash
+$ mkdir HelloWorld
+$ cd HelloWorld
+$ mkdir -p src/{main,test}/scala
+$ mkdir project target
+```
+
+在运行这些命令后运行 `find .` 命令时，您应该会看到以下结果：
+
+```bash
+$ find .
+.
+./project
+./src
+./src/main
+./src/main/scala
+./src/test
+./src/test/scala
+./target
+```
+
+如果你看到上面那样，那么没有问题，可以进行下一步了。
+
+> 还有其他方法可以为 sbt 项目创建文件和目录。
+> 一种方法是使用 `sbt new` 命令，[在 scala-sbt.org 上有文档](https://www.scala-sbt.org/1.x/docs/Hello.html)。
+> 该方法未在此处显示，因为它创建的某些文件比像这样的介绍所必需的要复杂。
+
+### 创建第一个 build.sbt 文件
+
+此时，您只需要另外两件事来运行 “Hello, world” 项目：
+
+- 一个 _build.sbt_ 文件
+- 一个 _Hello.scala_ 文件
+
+对于像这样的小项目，_build.sbt_ 文件只需要一个 `scalaVersion` 条目，但我们将添加您通常看到的三行：
+
+```scala
+name := "HelloWorld"
+version := "0.1"
+scalaVersion := "{{ site.scala-3-version }}"
+```
+
+因为 sbt 项目使用标准的目录结构，所以 sbt 可以找到它需要的所有其他内容。
+
+现在你只需要添加一个小小的“Hello, world”程序。
+
+### “Hello, world” 程序
+
+在大型项目中，您所有的 Scala 源代码文件都将放在 _src/main/scala_ 和 _src/test/scala_ 目录下，但是对于像这样的小示例项目，您可以将源代码文件放在您项目的根目录下。
+因此，在根目录中创建一个名为 _HelloWorld.scala_ 的文件，其中包含以下内容：
+
+```scala
+@main def helloWorld = println("Hello, world")
+```
+
+该代码定义了一个 Scala 3 “main” 方法，该方法在运行时打印 `"Hello, world"`。
+
+现在，使用 `sbt run` 命令编译并运行您的项目：
+
+```bash
+$ sbt run
+
+[info] welcome to sbt
+[info] loading settings for project ...
+[info] loading project definition
+[info] loading settings for project root from build.sbt ...
+[info] Compiling 1 Scala source ...
+[info] running helloWorld
+Hello, world
+[success] Total time: 4 s
+```
+
+第一次运行 `sbt` 时，它会下载所需的所有内容，这可能需要一些时间才能运行，但之后它会变得更快。
+
+此外，一旦你完成了这第一步，你会发现以交互方式运行 sbt 会快得多。
+为此，首先单独运行 `sbt` 命令：
+
+```bash
+$ sbt
+
+[info] welcome to sbt
+[info] loading settings for project ...
+[info] loading project definition ...
+[info] loading settings for project root from build.sbt ...
+[info] sbt server started at
+ local:///${HOME}/.sbt/1.0/server/7d26bae822c36a31071c/sock
+sbt:hello-world> _
+```
+
+然后在这个 sbt shell 中，执行它的 `run` 命令：
+
+````
+sbt:hello-world> run
+
+[info] running helloWorld
+Hello, world
+[success] Total time: 0 s
+````
+
+这要快得多。
+
+如果您在 sbt 命令提示符下键入 `help`，您将看到可以运行的其他命令的列表。
+但现在，只需键入 `exit`（或按 `CTRL-D`）离开 sbt shell。
+
+### 使用项目模板
+
+手动创建项目结构可能很乏味。谢天谢地，sbt 可以基于模板为你创建项目。
+
+要从模板创建 Scala 3 项目，请在 shell 中运行以下命令：
+
+~~~
+$ sbt new scala/scala3.g8
+~~~
+
+Sbt 将加载模板，提出一些问题，并在子目录中创建项目文件：
+
+~~~
+$ tree scala-3-project-template
+scala-3-project-template
+├── build.sbt
+├── project
+│ └── build.properties
+├── README.md
+└── src
+ ├── main
+ │ └── scala
+ │ └── Main.scala
+ └── test
+ └── scala
+ └── Test1.scala
+~~~
+
+> 如果要创建与 Scala 2 交叉编译的 Scala 3 项目，请使用模板 `scala/scala3-cross.g8`：
+>
+> ~~~
+> $ sbt new scala/scala3-cross.g8
+> ~~~
+
+在 [sbt 文档](https://www.scala-sbt.org/1.x/docs/sbt-new-and-Templates.html#sbt+new+) 中了解有关 `sbt new` 和项目模板的更多信息。
+
+### Scala 的其他构建工具
+
+虽然 sbt 被广泛使用，但您还可以使用其他工具来构建 Scala 项目：
+
+- [ant](https://ant.apache.org/)
+- [Gradle](https://gradle.org/)
+- [Maven](https://maven.apache.org/)
+- [mill](https://com-lihaoyi.github.io/mill/)
+
+#### Coursier
+
+在相关说明中，[Coursier](https://get-coursier.io/docs/overview) 是一个“依赖解析器”，在功能上类似于 Maven 和 Ivy。
+它是用 Scala 从头开始编写的，“包含函数式编程原则”，并且可以并行下载工件以实现快速下载。
+sbt 使用它来处理大多数依赖关系解析，并且作为一个命令行工具，它可以用于在您的系统上轻松安装 sbt、Java 和 Scala 等工具，如我们的 [Getting Started][getting_started] 页面所示。
+
+来自 `launch` 网页的这个示例显示了 `cs launch` 命令可用于从依赖项启动应用程序：
+
+```scala
+$ cs launch org.scalameta::scalafmt-cli:2.4.2 -- --help
+scalafmt 2.4.2
+Usage: scalafmt [options] [...]
+
+ -h, --help prints this usage text
+ -v, --version print version
+ more ...
+```
+
+有关详细信息，请参阅 Coursier 的 [启动页面](https://get-coursier.io/docs/cli-launch)。
+
+## 使用 sbt 和 ScalaTest
+
+[ScalaTest](https://www.scalatest.org) 是 Scala 项目的主要测试库之一。
+在本节中，您将看到创建使用 ScalaTest 的 Scala/sbt 项目所需的步骤。
+
+### 1) 创建项目目录结构
+
+与上一课一样，使用以下命令为名为 _HelloScalaTest_ 的项目创建一个 sbt 项目目录结构：
+
+```bash
+$ mkdir HelloScalaTest
+$ cd HelloScalaTest
+$ mkdir -p src/{main,test}/scala
+$ mkdir project
+```
+
+### 2) 创建 build.properties 和 build.sbt 文件
+
+接下来，把下面这行代码用于在项目的 _project/_ 子目录中创建一个 _build.properties_ 文件：
+
+```text
+sbt.version=1.10.11
+```
+
+接下来，在项目的根目录中创建一个 _build.sbt_ 文件，其中包含以下内容：
+
+```scala
+name := "HelloScalaTest"
+version := "0.1"
+scalaVersion := "{{site.scala-3-version}}"
+
+libraryDependencies ++= Seq(
+ "org.scalatest" %% "scalatest" % "3.2.19" % Test
+)
+```
+
+该文件的前三行与第一个示例基本相同。
+`libraryDependencies` 行告诉 sbt 包含包含 ScalaTest 所需的依赖项（JAR 文件）。
+
+> ScalaTest 文档一直很优秀，您始终可以在 [安装 ScalaTest](https://www.scalatest.org/install) 页面上找到有关这些行应该是什么样子的最新信息。
+
+### 3) 创建一个 Scala 源代码文件
+
+接下来，创建一个可用于演示 ScalaTest 的 Scala 程序。
+首先，在 _src/main/scala_ 下创建一个名为 _math_ 的目录：
+
+```bash
+$ mkdir src/main/scala/math
+ ----
+```
+
+然后，在该目录中，使用以下内容创建一个名为 _MathUtils.scala_ 的文件：
+
+```scala
+package math
+
+object MathUtils:
+ def double(i: Int) = i * 2
+```
+
+该方法提供了一种演示 ScalaTest 的简单方法。
+
+{% comment %}
+Because this project doesn’t have a `main` method, we don’t try to run it with `sbt run`; we just compile it with `sbt compile`:
+
+````
+$ sbt compile
+
+[info] welcome to sbt
+[info] loading settings for project ...
+[info] loading project definition ...
+[info] loading settings for project ...
+[info] Executing in batch mode. For better performance use sbt's shell
+[success] Total time: 1 s
+````
+
+With that compiled, let’s create a ScalaTest file to test the `double` method.
+{% endcomment %}
+
+### 4) 创建你的第一个 ScalaTest 测试
+
+ScalaTest 非常灵活，并提供了几种不同的方式来编写测试。
+一个简单的入门方法是使用 ScalaTest `AnyFunSuite` 编写测试。
+首先，在 _src/test/scala_ 目录下创建一个名为 _math_ 的目录：
+
+```bash
+$ mkdir src/test/scala/math
+ ----
+```
+
+接下来，在该目录中创建一个名为 _MathUtilsTests.scala_ 的文件，其内容如下：
+
+```scala
+package math
+
+import org.scalatest.funsuite.AnyFunSuite
+
+class MathUtilsTests extends AnyFunSuite:
+
+ // test 1
+ test("'double' should handle 0") {
+ val result = MathUtils.double(0)
+ assert(result == 0)
+ }
+
+ // test 2
+ test("'double' should handle 1") {
+ val result = MathUtils.double(1)
+ assert(result == 2)
+ }
+
+ test("test with Int.MaxValue") (pending)
+
+end MathUtilsTests
+```
+
+此代码演示了 ScalaTest `AnyFunSuite` 方法。
+几个重要的点：
+
+- 你的测试类应该继承 `AnyFunSuite`
+- 如图所示，您可以通过为每个 `test` 指定一个唯一的名称来创建测试
+- 在每个测试结束时，您应该调用 `assert` 来测试条件是否已满足
+- 当你知道你想写一个测试，但你现在不想写它时，将测试创建为“待定”，语法如上例所示
+
+像这样使用 ScalaTest 类似于 JUnit，所以如果你是从 Java 转到 Scala 的，希望这看起来相似。
+
+现在您可以使用 `sbt test` 命令运行这些测试。
+跳过前几行输出，结果如下所示：
+
+````
+sbt:HelloScalaTest> test
+
+[info] Compiling 1 Scala source ...
+[info] MathUtilsTests:
+[info] - 'double' should handle 0
+[info] - 'double' should handle 1
+[info] - test with Int.MaxValue (pending)
+[info] Total number of tests run: 2
+[info] Suites: completed 1, aborted 0
+[info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 1
+[info] All tests passed.
+[success] Total time: 1 s
+````
+
+如果一切正常，您将看到类似的输出。
+欢迎来到使用 sbt 和 ScalaTest 测试 Scala 应用程序的世界。
+
+### 支持多种类型的测试
+
+此示例演示了一种类似于 xUnit _测试驱动开发_(TDD) 样式测试的测试样式，并具有_行为驱动开发_(BDD) 样式的一些优点。
+
+如前所述，ScalaTest 很灵活，您还可以用其它风格来编写测试，例如类似于 Ruby 的 RSpec 的风格。
+您还可以使用伪对象、基于属性的测试，并使用 ScalaTest 来测试 Scala.js 代码。
+
+有关可用的不同测试风格的更多详细信息，请参阅 [ScalaTest 网站](https://www.scalatest.org) 上的用户指南。
+
+## 从这往哪儿走
+
+有关 sbt 和 ScalaTest 的更多信息，请参阅以下资源：
+
+- [sbt 文档](https://www.scala-sbt.org/1.x/docs/)
+- [ScalaTest 网站](https://www.scalatest.org/)
+
+
+[getting_started]: {{ site.baseurl }}/scala3/getting-started.html
diff --git a/_zh-cn/overviews/scala3-book/tools-worksheets.md b/_zh-cn/overviews/scala3-book/tools-worksheets.md
new file mode 100644
index 0000000000..214b744d8b
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/tools-worksheets.md
@@ -0,0 +1,65 @@
+---
+title: worksheet
+type: section
+description: This section looks at worksheets, an alternative to Scala projects.
+language: zh-cn
+num: 71
+previous-page: tools-sbt
+next-page: interacting-with-java
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+工作表是在保存时评估的 Scala 文件，并把每个表达式的结果
+显示在程序右侧的列中。工作表就像是加了激素的[REPL 会话][REPL session]，并且
+享受一流的编辑器支持：自动补全、超链接、交互式错误输入等。
+工作表使用扩展名 `.worksheet.sc` 。
+
+下面，我们将展示如何在 IntelliJ 和 VS Code（带有 Metals 扩展）中使用工作表。
+
+1. 打开一个 Scala 项目，或者创建一个。
+ - 要在 IntelliJ 中创建项目，选择“File”->“New”->“Project...”， 在左侧栏中选择“Scala”，
+ 单击“下一步”设置项目名称和位置。
+ - 要在 VS Code 中创建项目，请运行命令“Metals: New Scala project”，选择
+ 种子 `scala/scala3.g8`，设置项目位置，在新的 VS Code 窗口中打开它，然后
+ 导入其构建。
+1. 在 `src/main/scala/` 目录下创建一个名为 `hello.worksheet.sc` 的文件。
+ - 在 IntelliJ 中，右键单击目录 `src/main/scala/`，然后选择“New”，然后
+ 是“文件”。
+ - 在 VS Code 中，右键单击目录`src/main/scala/`，然后选择“New File”。
+1. 在编辑器中粘贴以下内容：
+ ~~~
+ println("Hello, world!")
+
+ val x = 1
+ x + x
+ ~~~
+
+1. 评估工作表。
+ - 在 IntelliJ 中，单击编辑器顶部的绿色箭头以评估工作表。
+ - 在 VS Code 中，保存文件。
+
+ 您应该在右侧面板 (IntelliJ) 上看到每一行的评估结果，或者
+ 作为注释（VS Code）。
+
+
+
+在 IntelliJ 中评估的工作表。
+
+
+
+在 VS Code 中评估的工作表（带有 Metals 扩展）。
+
+请注意，工作表将使用项目定义的 Scala 版本（通常在文件`build.sbt`中，
+设置 `scalaVersion` 键）。
+
+另请注意，工作表没有 [程序入口点][program entry point]。作为替代，顶级语句和表达式
+从上到下进行评估。
+
+
+[REPL session]: {% link _zh-cn/overviews/scala3-book/taste-repl.md %}
+[program entry point]: {% link _zh-cn/overviews/scala3-book/methods-main-methods.md %}
diff --git a/_zh-cn/overviews/scala3-book/types-adts-gadts.md b/_zh-cn/overviews/scala3-book/types-adts-gadts.md
new file mode 100644
index 0000000000..4d1604e187
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-adts-gadts.md
@@ -0,0 +1,213 @@
+---
+title: 代数数据类型
+type: section
+description: This section introduces and demonstrates algebraic data types (ADTs) in Scala 3.
+language: zh-cn
+num: 53
+previous-page: types-union
+next-page: types-variance
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+代数数据类型 (ADT) 可以使用 `enum` 构造创建，因此我们将在查看 ADT 之前简要回顾一下枚举。
+
+## 枚举
+
+_enumeration_ 用于定义由一组命名值组成的类型：
+
+```scala
+enum Color:
+ case Red, Green, Blue
+```
+
+这可以看作是以下的简写：
+
+```scala
+enum Color:
+ case Red extends Color
+ case Green extends Color
+ case Blue extends Color
+```
+
+#### 参数
+
+枚举可以参数化：
+
+```scala
+enum Color(val rgb: Int):
+ case Red extends Color(0xFF0000)
+ case Green extends Color(0x00FF00)
+ case Blue extends Color(0x0000FF)
+```
+
+这样，每个不同的变体都有一个值成员 `rgb`，它被分配了相应的值：
+
+```scala
+println(Color.Green.rgb) // prints 65280
+```
+
+#### 自定义
+
+枚举也可以有自定义：
+
+```scala
+enum Planet(mass: Double, radius: Double):
+
+ private final val G = 6.67300E-11
+ def surfaceGravity = G * mass / (radius * radius)
+ def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity
+
+ case Mercury extends Planet(3.303e+23, 2.4397e6)
+ case Venus extends Planet(4.869e+24, 6.0518e6)
+ case Earth extends Planet(5.976e+24, 6.37814e6)
+ // 5 or 6 more planets ...
+```
+
+像类和 `case` 类一样，你也可以为枚举定义一个伴生对象：
+
+```scala
+object Planet:
+ def main(args: Array[String]) =
+ val earthWeight = args(0).toDouble
+ val mass = earthWeight / Earth.surfaceGravity
+ for (p <- values)
+ println(s"Your weight on $p is ${p.surfaceWeight(mass)}")
+```
+
+## 代数数据类型 (ADTs)
+
+`enum` 概念足够通用，既支持_代数数据类型_（ADT）和它的通用版本（GADT）。
+本示例展示了如何将 `Option` 类型表示为 ADT：
+
+```scala
+enum Option[+T]:
+ case Some(x: T)
+ case None
+```
+
+这个例子创建了一个带有协变类型参数 `T` 的 `Option` 枚举，它由两种情况组成， `Some` 和 `None`。
+`Some` 是_参数化_的，它带有值参数 `x`；它是从 `Option` 继承的 `case` 类的简写。
+由于 `None` 没有参数化，它被视为普通的 `enum` 值。
+
+前面示例中省略的 `extends` 子句也可以显式给出：
+
+```scala
+enum Option[+T]:
+ case Some(x: T) extends Option[T]
+ case None extends Option[Nothing]
+```
+
+与普通的 `enum` 值一样，`enum` 的情况是在 `enum` 的伴生对象中定义的，因此它们被引用为 `Option.Some` 和 `Option.None`（除非定义是在导入时单独列出）：
+
+```scala
+scala> Option.Some("hello")
+val res1: t2.Option[String] = Some(hello)
+
+scala> Option.None
+val res2: t2.Option[Nothing] = None
+```
+
+与其他枚举用途一样，ADT 可以定义更多的方法。
+例如，这里又是一个 `Option`，它的伴生对象中有一个 `isDefined` 方法和一个 `Option(...)` 构造函数：
+
+```scala
+enum Option[+T]:
+ case Some(x: T)
+ case None
+
+ def isDefined: Boolean = this match
+ case None => false
+ case Some(_) => true
+
+object Option:
+ def apply[T >: Null](x: T): Option[T] =
+ if (x == null) None else Some(x)
+```
+
+枚举和 ADT 共享相同的句法结构，因此它们可以
+被简单地视为光谱的两端，把二者混搭是完全可能的。
+例如，下面的代码给出了一个
+`Color` 的实现，可以使用三个枚举值或使用
+RGB 值的参数化情况：
+
+```scala
+enum Color(val rgb: Int):
+ case Red extends Color(0xFF0000)
+ case Green extends Color(0x00FF00)
+ case Blue extends Color(0x0000FF)
+ case Mix(mix: Int) extends Color(mix)
+```
+
+#### 递归枚举
+
+到目前为止，我们定义的所有枚举都由值或样例类的不同变体组成。
+枚举也可以是递归的，如下面的自然数编码示例所示：
+
+```scala
+enum Nat:
+ case Zero
+ case Succ(n: Nat)
+```
+
+例如，值 `Succ(Succ(Zero))` 表示一元编码中的数字 `2`。
+列表可以以非常相似的方式定义：
+
+```scala
+enum List[+A]:
+ case Nil
+ case Cons(head: A, tail: List[A])
+```
+
+## 广义代数数据类型 (GADT)
+
+上面的枚举表示法非常简洁，可以作为建模数据类型的完美起点。
+由于我们总是可以更明确，因此也可以表达更强大的类型：广义代数数据类型 (GADT)。
+
+这是一个 GADT 示例，其中类型参数 (`T`) 指定存储在框中的内容：
+
+```scala
+enum Box[T](contents: T):
+ case IntBox(n: Int) extends Box[Int](n)
+ case BoolBox(b: Boolean) extends Box[Boolean](b)
+```
+
+特定构造函数（`IntBox` 或 `BoolBox`）上的模式匹配可恢复类型信息：
+
+```scala
+def extract[T](b: Box[T]): T = b match
+ case IntBox(n) => n + 1
+ case BoolBox(b) => !b
+```
+
+只有在第一种情况下返回一个 `Int` 才是安全的，因为我们从 pattern 匹配输入是一个“IntBox”。
+
+## 去除语法糖的枚举
+
+_从概念上讲_，枚举可以被认为是定义一个密封类及其伴生对象。
+让我们看看上面的 `Color` 枚举的无语法糖版本：
+
+```scala
+sealed abstract class Color(val rgb: Int) extends scala.reflect.Enum
+object Color:
+ case object Red extends Color(0xFF0000) { def ordinal = 0 }
+ case object Green extends Color(0x00FF00) { def ordinal = 1 }
+ case object Blue extends Color(0x0000FF) { def ordinal = 2 }
+ case class Mix(mix: Int) extends Color(mix) { def ordinal = 3 }
+
+ def fromOrdinal(ordinal: Int): Color = ordinal match
+ case 0 => Red
+ case 1 => Green
+ case 2 => Blue
+ case _ => throw new NoSuchElementException(ordinal.toString)
+```
+
+请注意，上面的去除语法糖被简化了，我们故意省略了[一些细节][desugar-enums]。
+
+虽然枚举可以使用其他构造手动编码，但使用枚举更简洁，并且还附带了一些额外的实用程序（例如 `fromOrdinal` 方法）。
+
+[desugar-enums]: {{ site.scala3ref }}/enums/desugarEnums.html
diff --git a/_zh-cn/overviews/scala3-book/types-dependent-function.md b/_zh-cn/overviews/scala3-book/types-dependent-function.md
new file mode 100644
index 0000000000..37084f1647
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-dependent-function.md
@@ -0,0 +1,175 @@
+---
+title: 依赖函数类型
+type: section
+description: This section introduces and demonstrates dependent function types in Scala 3.
+language: zh-cn
+num: 57
+previous-page: types-structural
+next-page: types-others
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+*依赖函数类型*描述函数类型，其中结果类型可能取决于函数的参数值。
+依赖类型和依赖函数类型的概念更高级，您通常只会在设计自己的库或使用高级库时遇到它。
+
+## 依赖方法类型
+
+让我们考虑以下可以存储不同类型值的异构数据库示例。
+键包含有关相应值的类型的信息：
+
+```scala
+trait Key { type Value }
+
+trait DB {
+ def get(k: Key): Option[k.Value] // a dependent method
+}
+```
+
+给定一个键，`get` 方法允许我们访问地图并可能返回类型为 `k.Value` 的存储值。
+我们可以将这个_路径依赖类型_解读为：“根据参数 `k` 的具体类型，我们返回一个匹配值”。
+
+例如，我们可以有以下键：
+
+```scala
+object Name extends Key { type Value = String }
+object Age extends Key { type Value = Int }
+```
+
+以下对方法 `get` 的调用现在将键入检查：
+
+```scala
+val db: DB = ...
+val res1: Option[String] = db.get(Name)
+val res2: Option[Int] = db.get(Age)
+```
+
+调用方法 `db.get(Name)` 返回一个 `Option[String]` 类型的值，而调用 `db.get(Age)` 返回一个 `Option[Int]` 类型的值。
+返回类型_依赖_于传递给 `get` 的参数的具体类型---因此名称为_依赖类型_。
+
+## 依赖函数类型
+
+如上所示，Scala 2 已经支持依赖方法类型。
+但是，创建 `DB` 类型的值非常麻烦：
+
+```scala
+// a user of a DB
+def user(db: DB): Unit =
+ db.get(Name) ... db.get(Age)
+
+// creating an instance of the DB and passing it to `user`
+user(new DB {
+ def get(k: Key): Option[k.Value] = ... // implementation of DB
+})
+```
+
+我们需要手动创建一个匿名的 `DB` 内部类，实现 `get` 方法。
+对于依赖于创建许多不同的 `DB` 实例的代码，这是非常乏味的。
+
+ `DB` 只有一个抽象方法 `get` 。
+如果我们可以使用 lambda 语法，那不是很好吗？
+
+```scala
+user { k =>
+ ... // implementation of DB
+```
+
+事实上，现在这在 Scala 3 中是可能的！我们可以将 `DB` 定义为_依赖函数类型_：
+
+```scala
+type DB = (k: Key) => Option[k.Value]
+// ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+// A dependent function type
+```
+
+鉴于 `DB` 的这个定义，上面对 `user` 类型的调用按原样检查。
+
+您可以在 [参考文档][ref] 中阅读有关依赖函数类型内部结构的更多信息。
+
+## 案例研究：数值表达式
+
+假设我们要定义一个抽象数字内部表示的模块。
+例如，这对于实现用于自动派生的库很有用。
+
+我们首先为数字定义我们的模块：
+
+```scala
+trait Nums:
+ // the type of numbers is left abstract
+ type Num
+
+ // some operations on numbers
+ def lit(d: Double): Num
+ def add(l: Num, r: Num): Num
+ def mul(l: Num, r: Num): Num
+```
+
+> 我们省略了 `Nums` 的具体实现，但作为练习，您可以通过分配 `type Num = Double` 来实现 `Nums` 并相应地实现方法。
+
+使用我们的数字抽象的程序现在具有以下类型：
+
+```scala
+type Prog = (n: Nums) => n.Num => n.Num
+
+val ex: Prog = nums => x => nums.add(nums.lit(0.8), x)
+```
+
+计算诸如 `ex` 之类的程序的导数的函数的类型是：
+
+```scala
+def derivative(input: Prog): Double
+```
+
+鉴于依赖函数类型的便利，用不同的程序调用这个函数非常方便：
+
+```scala
+derivative { nums => x => x }
+derivative { nums => x => nums.add(nums.lit(0.8), x) }
+// ...
+```
+
+回想一下，上面编码中的相同程序将是：
+
+```scala
+derivative(new Prog {
+ def apply(nums: Nums)(x: nums.Num): nums.Num = x
+})
+derivative(new Prog {
+ def apply(nums: Nums)(x: nums.Num): nums.Num = nums.add(nums.lit(0.8), x)
+})
+// ...
+```
+
+#### 上下文组合函数
+
+扩展方法、[上下文函数][ctx-fun]和依赖函数的组合为库设计者提供了强大的工具。
+例如，我们可以从上面优化我们的库，如下所示：
+
+```scala
+trait NumsDSL extends Nums:
+ extension (x: Num)
+ def +(y: Num) = add(x, y)
+ def *(y: Num) = mul(x, y)
+
+def const(d: Double)(using n: Nums): n.Num = n.lit(d)
+
+type Prog = (n: NumsDSL) ?=> n.Num => n.Num
+// ^^^
+// prog is now a context function that implicitly
+// assumes a NumsDSL in the calling context
+
+def derivative(input: Prog): Double = ...
+
+// notice how we do not need to mention Nums in the examples below?
+derivative { x => const(1.0) + x }
+derivative { x => x * x + const(2.0) }
+// ...
+```
+
+
+[ref]: {{ site.scala3ref }}/new-types/dependent-function-types.html
+[ctx-fun]: {{ site.scala3ref }}/contextual/context-functions.html
diff --git a/_zh-cn/overviews/scala3-book/types-generics.md b/_zh-cn/overviews/scala3-book/types-generics.md
new file mode 100644
index 0000000000..cdea2a2c4c
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-generics.md
@@ -0,0 +1,91 @@
+---
+title: 泛型
+type: section
+description: This section introduces and demonstrates generics in Scala 3.
+language: zh-cn
+num: 50
+previous-page: types-inferred
+next-page: types-intersection
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+泛型类（或 traits）把在方括号 `[...]` 中的类型作为_参数_进行调用。
+Scala 约定是使用单个字母（如 `A`）来命名这些类型参数。
+然后当需要时，该类型可以在类中用于方法实例参数，或返回类型：
+
+{% tabs stack class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+// here we declare the type parameter A
+// v
+class Stack[A] {
+ private var elements: List[A] = Nil
+ // ^
+ // Here we refer to the type parameter
+ // v
+ def push(x: A): Unit =
+ elements = elements.prepended(x)
+ def peek: A = elements.head
+ def pop(): A = {
+ val currentTop = peek
+ elements = elements.tail
+ currentTop
+ }
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+// here we declare the type parameter A
+// v
+class Stack[A]:
+ private var elements: List[A] = Nil
+ // ^
+ // Here we refer to the type parameter
+ // v
+ def push(x: A): Unit = { elements = elements.prepended(x) }
+ def peek: A = elements.head
+ def pop(): A =
+ val currentTop = peek
+ elements = elements.tail
+ currentTop
+```
+{% endtab %}
+{% endtabs %}
+
+`Stack` 类的这个实现采用任何类型作为参数。
+泛型的美妙之处在于您现在可以创建一个 `Stack[Int]`、`Stack[String]` 等，允许您将 `Stack` 的实现重复用于任意元素类型。
+
+这是创建和使用 `Stack[Int]` 的方式：
+
+{% tabs stack-usage class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val stack = new Stack[Int]
+stack.push(1)
+stack.push(2)
+println(stack.pop()) // prints 2
+println(stack.pop()) // prints 1
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val stack = Stack[Int]
+stack.push(1)
+stack.push(2)
+println(stack.pop()) // prints 2
+println(stack.pop()) // prints 1
+```
+{% endtab %}
+{% endtabs %}
+
+> 有关如何用泛型类型表达可变的详细信息，请参阅[型变（Variance）部分][variance]。
+
+[variance]: {% link _zh-cn/overviews/scala3-book/types-variance.md %}
diff --git a/_zh-cn/overviews/scala3-book/types-inferred.md b/_zh-cn/overviews/scala3-book/types-inferred.md
new file mode 100644
index 0000000000..aa6d3faf18
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-inferred.md
@@ -0,0 +1,58 @@
+---
+title: 类型推断
+type: section
+description: This section introduces and demonstrates inferred types in Scala 3
+language: zh-cn
+num: 49
+previous-page: types-introduction
+next-page: types-generics
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+与其他静态类型编程语言一样，在 Scala 中，您可以在创建新变量时_声明_类型：
+
+{% tabs xy %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val x: Int = 1
+val y: Double = 1
+```
+{% endtab %}
+{% endtabs %}
+
+在这些示例中，类型分别_明确地_声明为 `Int` 和 `Double` 。
+但是，在 Scala 中，您通常不必在定义值绑定器时声明类型：
+
+{% tabs abm %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = 1
+val b = List(1, 2, 3)
+val m = Map(1 -> "one", 2 -> "two")
+```
+{% endtab %}
+{% endtabs %}
+
+当你这样做时，Scala _推断_类型，如下面的 REPL 交互所示：
+
+{% tabs abm2 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+scala> val a = 1
+val a: Int = 1
+
+scala> val b = List(1, 2, 3)
+val b: List[Int] = List(1, 2, 3)
+
+scala> val m = Map(1 -> "one", 2 -> "two")
+val m: Map[Int, String] = Map(1 -> one, 2 -> two)
+```
+{% endtab %}
+{% endtabs %}
+
+事实上，大多数变量都是这样定义的，而 Scala 自动推断类型的能力是使它_感觉_像一种动态类型语言的一个特性。
diff --git a/_zh-cn/overviews/scala3-book/types-intersection.md b/_zh-cn/overviews/scala3-book/types-intersection.md
new file mode 100644
index 0000000000..db1d250a4c
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-intersection.md
@@ -0,0 +1,64 @@
+---
+title: 相交类型
+type: section
+description: This section introduces and demonstrates intersection types in Scala 3.
+language: zh-cn
+num: 51
+previous-page: types-generics
+next-page: types-union
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+Scala 3 only
+
+用于类型，`&` 运算符创建一个所谓的_相交类型_。
+`A & B` 类型表示同时是 `A` 类型和 `B` 类型**两者**的值。
+例如，以下示例使用相交类型 `Resettable & Growable[String]`：
+
+{% tabs intersection-reset-grow %}
+{% tab 'Scala 3 Only' %}
+```scala
+trait Resettable:
+ def reset(): Unit
+
+trait Growable[A]:
+ def add(a: A): Unit
+
+def f(x: Resettable & Growable[String]): Unit =
+ x.reset()
+ x.add("first")
+```
+{% endtab %}
+{% endtabs %}
+
+在本例中的方法 `f` 中，参数 `x` 必须*同时*既是 `Resettable` 也是 `Growable[String]`。
+
+相交类型 `A & B` 的_成员_既有 `A` 的所有成员，也有 `B` 的所有成员。
+因此，如图所示，`Resettable & Growable[String]` 具有成员方法 `reset` 和 `add`。
+
+相交类型可用于_结构性_地描述需求。
+也就是说，在我们的示例 `f` 中，我们直接表示只要 `x` 是 `Resettable` 和 `Growable` 的子类型的任意值， 我们就感到满意。
+我们**不**需要创建一个_通用_的辅助 trait，如下所示：
+
+{% tabs normal-trait class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+trait Both[A] extends Resettable with Growable[A]
+def f(x: Both[String]): Unit
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+trait Both[A] extends Resettable, Growable[A]
+def f(x: Both[String]): Unit
+```
+{% endtab %}
+{% endtabs %}
+
+定义 `f` 的两种选择之间有一个重要区别：虽然两者都允许使用 `Both` 的实例调用 `f`，但只有前者允许传递属于 `Resettable` 和 `Growable[String]` 子类型的实例，后者 `Both[String]` _不允许_。
+
+> 请注意，`&` 是_可交换的_：`A & B` 与 `B & A` 的类型相同。
diff --git a/_zh-cn/overviews/scala3-book/types-introduction.md b/_zh-cn/overviews/scala3-book/types-introduction.md
new file mode 100644
index 0000000000..dfe1b6b790
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-introduction.md
@@ -0,0 +1,61 @@
+---
+title: 类型和类型系统
+type: chapter
+description: This chapter provides an introduction to Scala 3 types and the type system.
+language: zh-cn
+num: 48
+previous-page: fp-summary
+next-page: types-inferred
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 是一种独特的语言，因为它是静态类型的，但通常_感觉_它灵活和动态。
+例如，由于类型推断，您可以编写这样的代码而无需显式指定变量类型：
+
+{% tabs hi %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = 1
+val b = 2.0
+val c = "Hi!"
+```
+{% endtab %}
+{% endtabs %}
+
+这使代码感觉是动态类型的。
+并且由于新特性，例如 Scala 3 中的 [联合类型][union-types]，您还可以编写如下代码，非常简洁地表达出期望哪些值作为参数，哪些值作为返回的类型：
+
+{% tabs union-example %}
+{% tab 'Scala 3 Only' %}
+```scala
+def isTruthy(a: Boolean | Int | String): Boolean = ???
+def dogCatOrWhatever(): Dog | Plant | Car | Sun = ???
+```
+{% endtab %}
+{% endtabs %}
+
+正如例子所暗示的，当使用联合类型时，这些类型不必共享一个公共层次结构，您仍然可以接受它们作为参数或从方法中返回它们。
+
+如果您是应用程序开发人员，您将每天使用类型推断和每周使用泛型等功能。
+当您阅读 Scaladoc 中的类和方法时，您还需要对_可变的(variance)_有所了解。
+希望您会发现使用类型可以相当简单，而且使用类型可以为库开发人员提供了很多表达能力、灵活性和控制力。
+
+## 类型的好处
+
+静态类型的编程语言提供了许多好处，包括：
+
+- 帮助提供强大的 IDE 支持
+- 在编译时消除许多类的潜在错误
+- 协助重构
+- 提供强大的文档，因为它经过类型检查，所以不会过时
+
+## Scala 类型系统的特性介绍
+
+鉴于此简要介绍，以下部分将概述 Scala 类型系统的特性。
+
+[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %}
diff --git a/_zh-cn/overviews/scala3-book/types-opaque-types.md b/_zh-cn/overviews/scala3-book/types-opaque-types.md
new file mode 100644
index 0000000000..c8ba8405f5
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-opaque-types.md
@@ -0,0 +1,160 @@
+---
+title: 不透明类型
+type: section
+description: This section introduces and demonstrates opaque types in Scala 3.
+language: zh-cn
+num: 55
+previous-page: types-variance
+next-page: types-structural
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 3 _不透明类型别名_提供没有任何**开销**的类型抽象。
+
+## 抽象开销
+
+假设我们要定义一个提供数字算术运算的模块，这些数字由它们的对数表示。
+当涉及的数值非常大或接近于零时，使用对数有利于提高精度。
+
+把“常规”双精度值与存储为对数的值区分开来很重要，我们引入了一个类 `Logarithm`：
+
+```scala
+class Logarithm(protected val underlying: Double):
+ def toDouble: Double = math.exp(underlying)
+ def + (that: Logarithm): Logarithm =
+ // here we use the apply method on the companion
+ Logarithm(this.toDouble + that.toDouble)
+ def * (that: Logarithm): Logarithm =
+ new Logarithm(this.underlying + that.underlying)
+
+object Logarithm:
+ def apply(d: Double): Logarithm = new Logarithm(math.log(d))
+```
+
+伴生对象上的 apply 方法让我们可以创建 `Logarithm` 类型的值，我们可用如下方式使用：
+
+```scala
+val l2 = Logarithm(2.0)
+val l3 = Logarithm(3.0)
+println((l2 * l3).toDouble) // prints 6.0
+println((l2 + l3).toDouble) // prints 4.999...
+```
+
+虽然 `Logarithm` 类为以这种特殊对数形式存储的 `Double` 值提供了一个很好的抽象，但它带来了严重的性能开销：对于每一个数学运算，我们需要提取基础值，然后将其再次包装在一个 `Logarithm` 的新实例中。
+
+## 模块抽象
+
+让我们考虑另一种实现相同库的方法。
+这次我们没有将 `Logarithm` 定义为一个类，而是使用_类型别名_来定义它。
+首先，我们定义模块的抽象接口：
+
+```scala
+trait Logarithms:
+
+ type Logarithm
+
+ // operations on Logarithm
+ def add(x: Logarithm, y: Logarithm): Logarithm
+ def mul(x: Logarithm, y: Logarithm): Logarithm
+
+ // functions to convert between Double and Logarithm
+ def make(d: Double): Logarithm
+ def extract(x: Logarithm): Double
+
+ // extension methods to use `add` and `mul` as "methods" on Logarithm
+ extension (x: Logarithm)
+ def toDouble: Double = extract(x)
+ def + (y: Logarithm): Logarithm = add(x, y)
+ def * (y: Logarithm): Logarithm = mul(x, y)
+```
+
+现在，让我们通过说类型 `Logarithm` 等于 `Double` 来实现这个抽象接口：
+
+```scala
+object LogarithmsImpl extends Logarithms:
+
+ type Logarithm = Double
+
+ // operations on Logarithm
+ def add(x: Logarithm, y: Logarithm): Logarithm = make(x.toDouble + y.toDouble)
+ def mul(x: Logarithm, y: Logarithm): Logarithm = x + y
+
+ // functions to convert between Double and Logarithm
+ def make(d: Double): Logarithm = math.log(d)
+ def extract(x: Logarithm): Double = math.exp(x)
+```
+
+在 `LogarithmsImpl` 的实现中，等式 `Logarithm = Double` 允许我们实现各种方法。
+
+#### 暴露抽象
+
+但是，这种抽象有点暴露。
+我们必须确保_只_针对抽象接口 `Logarithms` 进行编程，并且永远不要直接使用 `LogarithmsImpl`。
+直接使用 `LogarithmsImpl` 会使等式 `Logarithm = Double` 对用户可见，用户可能会意外使用 `Double`，而实际上是需要 对数双精度。
+例如：
+
+```scala
+import LogarithmsImpl.*
+val l: Logarithm = make(1.0)
+val d: Double = l // type checks AND leaks the equality!
+```
+
+必须将模块分离为抽象接口和实现可能很有用，但只为了隐藏 `Logarithm` 的实现细节，就需要付出很多努力。
+针对抽象模块 `Logarithm` 进行编程可能非常乏味，并且通常需要使用像路径依赖类型这样的高级特性，如下例所示：
+
+```scala
+def someComputation(L: Logarithms)(init: L.Logarithm): L.Logarithm = ...
+```
+
+#### 装箱的开销
+
+类型抽象，例如 `type Logarithm` [抹去](https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure) 到它们的界限（在我们的例子中是 `Any`）。
+也就是说，虽然我们不需要手动包装和解包 `Double` 值，但仍然会有一些与装箱原始类型 `Double` 相关的装箱开销。
+
+## 不透明类型
+
+我们可以简单地使用 Scala 3 中的不透明类型来实现类似的效果，而不是手动将我们的 `Logarithms` 组件拆分为抽象部分和具体实现：
+
+```scala
+object Logarithms:
+//vvvvvv this is the important difference!
+ opaque type Logarithm = Double
+
+ object Logarithm:
+ def apply(d: Double): Logarithm = math.log(d)
+
+ extension (x: Logarithm)
+ def toDouble: Double = math.exp(x)
+ def + (y: Logarithm): Logarithm = Logarithm(math.exp(x) + math.exp(y))
+ def * (y: Logarithm): Logarithm = x + y
+```
+
+`Logarithm` 与 `Double` 相同的事实仅在定义 `Logarithm` 的范围内已知，在上面的示例中对应于对象 `Logarithms`。
+类型相等 `Logarithm = Double` 可用于实现方法（如 `*` 和 `toDouble`）。
+
+然而，在模块之外， `Logarithm` 类型是完全封装的，或者说是“不透明的”。 对于 `Logarithm` 的用户来说，不可能发现 `Logarithm` 实际上是作为 `Double` 实现的：
+
+```scala
+import Logarithms.*
+val l2 = Logarithm(2.0)
+val l3 = Logarithm(3.0)
+println((l2 * l3).toDouble) // prints 6.0
+println((l2 + l3).toDouble) // prints 4.999...
+
+val d: Double = l2 // ERROR: Found Logarithm required Double
+```
+
+尽管我们抽象了 `Logarithm`，但抽象是免费的：
+由于只有一种实现，在运行时对于像 `Double` 这样的原始类型将_没有装箱开销_。
+
+### 不透明类型总结
+
+不透明类型提供了对实现细节的合理抽象，而不会增加性能开销。
+如上图所示，不透明类型使用起来很方便，并且与 [扩展方法][extension] 功能很好地集成在一起。
+
+[extension]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}
diff --git a/_zh-cn/overviews/scala3-book/types-others.md b/_zh-cn/overviews/scala3-book/types-others.md
new file mode 100644
index 0000000000..eec6faada8
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-others.md
@@ -0,0 +1,32 @@
+---
+title: 其他类型
+type: section
+description: This section mentions other advanced types in Scala 3.
+language: zh-cn
+num: 58
+previous-page: types-dependent-function
+next-page: ca-contextual-abstractions-intro
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala还有其他几种高级类型，本书中没有介绍，包括：
+
+- 类型 lambdas
+- 匹配类型
+- 存在类型
+- 高等类型
+- 单例类型
+- 细化类型
+- 种类多态性
+
+有关这些类型的更多详细信息，请参阅[参考文档][reference]。
+有关单例类型参见 Scala 3 规格中的[字面量类型](https://scala-lang.org/files/archive/spec/3.4/03-types.html#literal-types) 一节，
+细化类型参见[细化类型](https://scala-lang.org/files/archive/spec/3.4/03-types.html) 一节。
+
+
+[reference]: {{ site.scala3ref }}/overview.html
diff --git a/_zh-cn/overviews/scala3-book/types-structural.md b/_zh-cn/overviews/scala3-book/types-structural.md
new file mode 100644
index 0000000000..4c12a87901
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-structural.md
@@ -0,0 +1,110 @@
+---
+title: 结构化类型
+type: section
+description: This section introduces and demonstrates structural types in Scala 3.
+language: zh-cn
+num: 56
+previous-page: types-opaque-types
+next-page: types-dependent-function
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+{% comment %}
+NOTE: It would be nice to simplify this more.
+{% endcomment %}
+
+
+一些用例，例如建模数据库访问，在静态类型语言中比在动态类型语言中更尴尬。
+使用动态类型语言，很自然地将行建模为记录或对象，并使用简单的点表示法选择条目，例如 `row.columnName`。
+
+要在静态类型语言中获得相同的体验，需要为数据库操作产生的每个可能的行定义一个类——包括连接和投影产生的行——并设置一个方案以在行和代表它的类之间进行映射。
+
+这需要大量样板文件，这导致开发人员将静态类型的优势换成更简单的方案，其中列名表示为字符串并传递给其他运算符，例如 `row.select("columnName")`。
+这种方法即便放弃了静态类型的优点，也仍然不如动态类型的版本自然。
+
+在您希望在动态上下文中支持简单的点表示法而又不失静态类型优势的情况下，结构化类型会有所帮助。
+它们允许开发人员使用点表示法并配置应如何解析字段和方法。
+
+## 例子
+
+这是一个结构化类型 `Person` 的示例：
+
+```scala
+class Record(elems: (String, Any)*) extends Selectable:
+ private val fields = elems.toMap
+ def selectDynamic(name: String): Any = fields(name)
+
+type Person = Record {
+ val name: String
+ val age: Int
+}
+```
+
+`Person` 类型在其父类型 `Record` 中添加了一个_精细的改进_，它定义了 `name` 和 `age` 字段。
+我们精细的改进是_构造的_，因为 `name` 和 `age` 没有在父类型中定义。
+但是它们仍然作为 `Person` 类的成员存在。
+例如，以下程序将打印 `"Emma is 42 years old."`：
+
+```scala
+val person = Record(
+ "name" -> "Emma",
+ "age" -> 42
+).asInstanceOf[Person]
+
+println(s"${person.name} is ${person.age} years old.")
+```
+
+本例中的父类型 `Record` 是一个通用类，可以在其 `elems` 参数中表示任意记录。
+该参数是一个序列，该序列的元素是 `String` 类型的标签和 `Any` 类型的值组成的对。
+当您将 `Person` 创建为 `Record` 时，您必须使用类型转换断言该记录定义了正确类型的正确字段。
+`Record` 本身的类型太弱了，所以编译器在没有用户帮助的情况下无法知道这一点。
+实际上，结构化类型与其底层通用表示之间的连接很可能由数据库层完成，因此最终用户没必要关注。
+
+`Record` 扩展了标记 trait `scala.Selectable` 并定义了一个方法 `selectDynamic`，它将字段名称映射到其值。
+通过调用此方法来选择结构化类型成员。
+Scala 编译器把选择 `person.name` 和 `person.age` 翻译成：
+
+```scala
+person.selectDynamic("name").asInstanceOf[String]
+person.selectDynamic("age").asInstanceOf[Int]
+```
+
+## 第二个例子
+
+为了强化您刚刚看到的内容，这里有另一个名为 `Book` 的结构化类型，它表示您可能从数据库中读取的一本书：
+
+```scala
+type Book = Record {
+ val title: String
+ val author: String
+ val year: Int
+ val rating: Double
+}
+```
+
+与 `Person` 一样，这是创建 `Book` 实例的方式：
+
+```scala
+val book = Record(
+ "title" -> "The Catcher in the Rye",
+ "author" -> "J. D. Salinger",
+ "year" -> 1951,
+ "rating" -> 4.5
+).asInstanceOf[Book]
+```
+
+## 可选类
+
+除了 `selectDynamic` 之外，`Selectable`类有时还会定义 `applyDynamic` 方法。
+然后可以使用它来翻译是函数调用的结构成员。
+因此，如果 `a` 是 `Selectable` 的一个实例，则像 `a.f(b, c)` 这样的结构调用将转换为：
+
+```scala
+a.applyDynamic("f")(b, c)
+```
+
diff --git a/_zh-cn/overviews/scala3-book/types-union.md b/_zh-cn/overviews/scala3-book/types-union.md
new file mode 100644
index 0000000000..4e1ca79242
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-union.md
@@ -0,0 +1,111 @@
+---
+title: 联合类型
+type: section
+description: This section introduces and demonstrates union types in Scala 3.
+language: zh-cn
+num: 52
+previous-page: types-intersection
+next-page: types-adts-gadts
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+scala3: true
+versionSpecific: true
+---
+
+
+用于类型，`|` 操作符创建一个所谓的_联合类型_。
+类型 `A | B` 表示**要么是** `A` 类型的值，**要么是** `B` 类型的值。
+
+在下面的例子中，`help` 方法接受一个名为 `id` 的联合类型 `Username | Password`，可以是 `Useername` 或 `Password`：
+
+```scala
+case class Username(name: String)
+case class Password(hash: Hash)
+
+def help(id: Username | Password) =
+ val user = id match
+ case Username(name) => lookupName(name)
+ case Password(hash) => lookupPassword(hash)
+ // more code here ...
+```
+
+我们通过使用模式匹配区分二者，从而实现 `help` 方法。
+
+此代码是一种灵活且类型安全的解决方案。
+如果您尝试传入`Useername` 或 `Password` 以外的类型，编译器会将其标记为错误：
+
+```scala
+help("hi") // error: Found: ("hi" : String)
+ // Required: Username | Password
+```
+
+如果您尝试将 `case` 添加到与 `Username` 或 `Password` 类型不匹配的 `match` 表达式中，也会出现错误：
+
+```scala
+case 1.0 => ??? // ERROR: this line won’t compile
+```
+
+### 联合类型的替代方案
+
+如图所示，联合类型可用于替代几种不同的类型，而不要求这些类型是定制类层次结构的一部分，也不需要显式包装。
+
+#### 预先规划类层次结构
+
+其他语言需要预先规划类层次结构，如下例所示：
+
+{% tabs pre-planning %}
+{% tab 'Scala 2 and 3' %}
+```scala
+trait UsernameOrPassword
+case class Username(name: String) extends UsernameOrPassword
+case class Password(hash: Hash) extends UsernameOrPassword
+def help(id: UsernameOrPassword) = ...
+```
+{% endtab %}
+{% endtabs %}
+
+预先计划不能很好地扩展，例如，API 用户的需求可能无法预见。
+此外，使用诸如 `UsernameOrPassword` 之类的标记 trait 使类型层次结构混乱也会使代码更难阅读。
+
+#### 标记联合
+
+另一种选择是定义一个单独的枚举类型，如：
+
+```scala
+enum UsernameOrPassword:
+ case IsUsername(u: Username)
+ case IsPassword(p: Password)
+```
+
+枚举 `UsernameOrPassword` 表示 `Username` 和 `Password` 的 _标记_联合。
+但是，这种联合建模方式需要_显式包装和展开_，例如，`Username` **不是** `UsernameOrPassword` 的子类型。
+
+### 联合类型推断
+
+_仅当_明确给出这种类型时，编译器才会将联合类型分配给表达式。
+例如，给定这些值：
+
+```scala
+val name = Username("Eve") // name: Username = Username(Eve)
+val password = Password(123) // password: Password = Password(123)
+```
+
+这个 REPL 示例展示了在将变量绑定到 `if`/`else` 表达式的结果时如何使用联合类型：
+
+````
+scala> val a = if (true) name else password
+val a: Object = Username(Eve)
+
+scala> val b: Password | Username = if (true) name else password
+val b: Password | Username = Username(Eve)
+````
+
+`a` 的类型是 `Object`，它是 `Username` 和 `Password` 的超类型，但不是二者*最小*的超类型 `Password | Username`。
+如果你想要最小的超类型，你必须明确地给出它，就像对 `b` 所做的那样。
+
+> 联合类型是交集类型的对偶。
+> 和具有交集类型的 `&` 一样，`|` 也是可交换的：`A | B` 与 `B | A` 是同一类型。
+
diff --git a/_zh-cn/overviews/scala3-book/types-variance.md b/_zh-cn/overviews/scala3-book/types-variance.md
new file mode 100644
index 0000000000..3c774c1d52
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/types-variance.md
@@ -0,0 +1,250 @@
+---
+title: 型变
+type: section
+description: This section introduces and demonstrates variance in Scala 3.
+language: zh-cn
+num: 54
+previous-page: types-adts-gadts
+next-page: types-opaque-types
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+类型参数_型变_控制参数化类型（如类或 traits）的子类型。
+
+为了解释型变，让我们假设以下类型定义：
+
+{% tabs types-variance-1 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+trait Item { def productNumber: String }
+trait Buyable extends Item { def price: Int }
+trait Book extends Buyable { def isbn: String }
+```
+{% endtab %}
+{% endtabs %}
+
+我们还假设以下参数化类型：
+
+{% tabs types-variance-2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=types-variance-2 %}
+```scala
+// an example of an invariant type
+trait Pipeline[T] {
+ def process(t: T): T
+}
+
+// an example of a covariant type
+trait Producer[+T] {
+ def make: T
+}
+
+// an example of a contravariant type
+trait Consumer[-T] {
+ def take(t: T): Unit
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=types-variance-2 %}
+```scala
+// an example of an invariant type
+trait Pipeline[T]:
+ def process(t: T): T
+
+// an example of a covariant type
+trait Producer[+T]:
+ def make: T
+
+// an example of a contravariant type
+trait Consumer[-T]:
+ def take(t: T): Unit
+```
+{% endtab %}
+{% endtabs %}
+
+一般来说，型变有三种模式：
+
+- **不变的**---默认值，写成 `Pipeline[T]`
+- **协变**---用`+`注释，例如 `Producer[+T]`
+- **逆变**---用`-`注释，如 `Consumer[-T]`
+
+我们现在将详细介绍此注释的含义以及我们使用它的原因。
+
+### 不变类型
+
+默认情况下，像 `Pipeline` 这样的类型在它们的类型参数中是不变的（本例中是 `T`）。
+这意味着像 `Pipeline[Item]`、`Pipeline[Buyable]` 和 `Pipeline[Book]` 这样的类型彼此之间_没有子类型关系_。
+
+理所当然地！假设以下方法使用两个类型为`Pipeline[Buyable]` 的值，并根据价格将其参数 `b` 传递给其中一个：
+
+{% tabs types-variance-3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=types-variance-3 %}
+```scala
+def oneOf(
+ p1: Pipeline[Buyable],
+ p2: Pipeline[Buyable],
+ b: Buyable
+): Buyable = {
+ val b1 = p1.process(b)
+ val b2 = p2.process(b)
+ if (b1.price < b2.price)
+ b1
+ else
+ b2
+ }
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=types-variance-3 %}
+```scala
+def oneOf(
+ p1: Pipeline[Buyable],
+ p2: Pipeline[Buyable],
+ b: Buyable
+): Buyable =
+ val b1 = p1.process(b)
+ val b2 = p2.process(b)
+ if b1.price < b2.price then b1 else b2
+```
+{% endtab %}
+{% endtabs %}
+
+现在，回想一下，我们的类型之间存在以下_子类型关系_：
+
+{% tabs types-variance-4 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+Book <: Buyable <: Item
+```
+{% endtab %}
+{% endtabs %}
+
+我们不能将 `Pipeline[Book]` 传递给 `oneOf` 方法，因为在其实现中，我们调用的 `p1` 和 `p2` 是 `Buyable` 类型的值。
+`Pipeline[Book]` 需要的是 `Book`，这可能会导致运行时错误。
+
+我们不能传递一个 `Pipeline[Item]` 因为在它上面调用 `process` 只会保证返回一个 `Item`；但是，我们应该返回一个 `Buyable` 。
+
+#### 为什么是不变的？
+
+事实上，`Pipeline` 类型需要是不变的，因为它使用它的类型参数 `T` _既_作为参数类型，_又_作为返回类型。
+出于同样的原因，Scala 集合库中的某些类型——例如 `Array` 或 `Set` —— 也是_不变的_。
+
+### 协变类型
+
+与不变的 `Pipeline` 相比，`Producer` 类型通过在类型参数前面加上 `+` 前缀被标记为 **协变**。
+这是有效的，因为类型参数仅用于_返回的位置_。
+
+将其标记为协变意味着当需要 `Producer[Buyable]` 时，我们可以传递（或返回）一个 `Producer[Book]`。
+事实上，这是合理的。 `Producer[Buyable].make` 的类型只承诺_返回_ `Buyable`。
+作为 `make` 的调用者，我们乐意接受作为 `Buyable` 的子类型的 `Book` 类型，---也就是说，它_至少_是一个 `Buyable`。
+
+以下示例说明了这一点，其中函数 `makeTwo` 需要一个 `Producer[Buyable]`：
+
+{% tabs types-variance-5 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def makeTwo(p: Producer[Buyable]): Int =
+ p.make.price + p.make.price
+```
+{% endtab %}
+{% endtabs %}
+
+通过书籍制作人是完全可以的：
+
+{% tabs types-variance-6 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val bookProducer: Producer[Book] = ???
+makeTwo(bookProducer)
+```
+{% endtab %}
+{% endtabs %}
+
+在 `makeTwo` 中调用 `price` 对书籍仍然有效。
+
+#### 不可变容器的协变类型
+
+在处理不可变容器时，您会经常遇到协变类型，例如可以在标准库中找到的那些（例如 `List`、`Seq`、`Vector` 等）。
+
+例如，`List` 和 `Vector` 大致定义为：
+
+{% tabs types-variance-7 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+class List[+A] ...
+class Vector[+A] ...
+```
+{% endtab %}
+{% endtabs %}
+
+这样，您可以在需要 `List[Buyable]` 的地方使用 `List[Book]`。
+这在直觉上也是有道理的：如果您期望收藏可以购买的东西，那么给您收藏书籍应该没问题。
+在我们的示例中，它们有一个额外的 ISBN 方法，但您可以随意忽略这些额外的功能。
+
+### 逆变类型
+
+与标记为协变的类型 `Producer` 相比，类型 `Consumer` 通过在类型参数前加上 `-` 来标记为**逆变**。
+这是有效的，因为类型参数仅用于_参数位置_。
+
+将其标记为逆变意味着如果我们想要 `Consumer[Buyable]` 时，可以传递（或返回） `Consumer[Item]`。
+也就是说，我们有子类型关系`Consumer[Item] <: Consumer[Buyable]`。
+请记住，对于类型 `Producer`，情况正好相反，我们有 `Producer[Buyable] <: Producer[Item]`。
+
+事实上，这是合理的。 `Consumer[Item].take` 方法接受一个 `Item`。
+作为 `take` 的调用者，我们还可以提供 `Buyable`，它会被 `Consumer[Item]` 愉快地接受，因为 `Buyable` 是 `Item` 的一个子类型——也就是说，它_至少_是 `Item` 。
+
+#### 消费者的逆变类型
+
+逆变类型比协变类型少得多。
+在我们的示例中，您可以将它们视为“消费者”。你可能来的最重要的类型标记为逆变的 cross 是函数之一：
+
+{% tabs types-variance-8 class=tabs-scala-version %}
+{% tab 'Scala 2' for=types-variance-8 %}
+```scala
+trait Function[-A, +B] {
+ def apply(a: A): B
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=types-variance-8 %}
+```scala
+trait Function[-A, +B]:
+ def apply(a: A): B
+```
+{% endtab %}
+{% endtabs %}
+
+它的参数类型 `A` 被标记为逆变的 `A` ——它消费 `A` 类型的值。
+相反，它的结果类型 `B` 被标记为协变——它产生 `B` 类型的值。
+
+以下是一些示例，这些示例说明了由函数上可变注释引起的子类型关系：
+
+{% tabs types-variance-9 %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val f: Function[Buyable, Buyable] = b => b
+
+// OK to return a Buyable where a Item is expected
+val g: Function[Buyable, Item] = f
+
+// OK to provide a Book where a Buyable is expected
+val h: Function[Book, Buyable] = f
+```
+{% endtab %}
+{% endtabs %}
+
+## 概括
+
+在本节中，我们遇到了三种不同的方差：
+
+- **生产者**通常是协变的，并用 `+` 标记它们的类型参数。
+ 这也适用于不可变集合。
+- **消费者**通常是逆变的，并用 `-` 标记他们的类型参数。
+- **既是**生产者**又**是消费者的类型必须是不变的，并且不需要在其类型参数上进行任何标记。
+ 像 `Array` 这样的可变集合就属于这一类。
diff --git a/_zh-cn/overviews/scala3-book/where-next.md b/_zh-cn/overviews/scala3-book/where-next.md
new file mode 100644
index 0000000000..66c3afe639
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/where-next.md
@@ -0,0 +1,20 @@
+---
+title: 下一步去哪
+type: chapter
+description: Where to go next after reading the Scala Book
+language: zh-cn
+num: 76
+previous-page: scala-for-python-devs
+next-page:
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+我们希望你能喜欢 Scala 编程语言的介绍，我们也希望你能分享一些这门语言的美丽之处。
+
+如果你继续用 Scala 工作，你可以在我们[引导和概览部分][overviews]发现更多细节。
+
+[overviews]: {% link _overviews/index.md %}
diff --git a/_zh-cn/overviews/scala3-book/why-scala-3.md b/_zh-cn/overviews/scala3-book/why-scala-3.md
new file mode 100644
index 0000000000..b07b567fe7
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/why-scala-3.md
@@ -0,0 +1,504 @@
+---
+title: 为什么是 Scala 3 ？
+type: chapter
+description: This page describes the benefits of the Scala 3 programming language.
+language: zh-cn
+num: 3
+previous-page: scala-features
+next-page: taste-intro
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+{% comment %}
+TODO: Is “Scala 3 Benefits” a better title?
+NOTE: Could mention “grammar” as a way of showing that Scala isn’t a large language; see this slide: https://www.slideshare.net/Odersky/preparing-for-scala-3#13
+{% endcomment %}
+
+使用 Scala 有很多好处，特别是 Scala 3。
+很难列出 Scala 的每一个好处，但“前十名”列表可能看起来像这样：
+
+1. Scala 融合了函数式编程（FP）和面向对象编程（OOP）
+2. Scala 是静态类型的语言，但通常感觉像一种动态类型语言。
+3. Scala 的语法简洁，但仍然可读;它通常被称为 _易于表达_
+4. Scala 2 中的 _Implicits_ 是一个定义特性，它们在 Scala 3 中得到了改进和简化。
+5. Scala 与 Java 无缝集成，因此您可以创建混合了 Scala 和 Java 代码的项目，Scala 代码可以轻松使用成千上万个现有的 Java 库
+6. Scala 可以在服务器上使用，通过 [Scala.js](https://www.scala-js.org)， Scala 也可以在浏览器中使用
+7. Scala 标准库具有数十种预构建的函数式方法，可节省您的时间，并大大减少编写自定义 `for` 循环和算法的需要
+8. Scala 内置了“最佳实践”，它支持不可变性，匿名函数，高阶函数，模式匹配，默认情况下无法扩展的类等
+9. Scala 生态系统提供世界上最现代化的 FP 库
+10. 强类型式系统
+
+## 1) FP/OOP 融合
+
+Scala 比任何其他语言都更支持 FP 和 OOP 范式的融合。
+正如 Martin Odersky 所说，Scala 的本质是在类型化环境中融合了函数式和面向对象编程，具有：
+
+- 函数用于编写逻辑 （局部）
+- 对象用于构建模块化 （整体）
+
+模块化的一些最佳示例可能是标准库中的类。
+例如，`List` 被定义为一个类---从技术上讲，它是一个抽象类---并且像这样创建了一个新实例：
+
+{% tabs list %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val x = List(1, 2, 3)
+```
+{% endtab %}
+{% endtabs %}
+
+但是，在程序员看来是一个简单的 `List` 实际上是由几种特殊类型的组合构建的，包括名为`Iterable`, `Seq`, 和 `LinearSeq` 的 traits。
+这些类型同样由其他小型的模块化代码单元组成。
+
+除了从一系列模块化 traits 构建/cases像 `List` 这样的类型之外，`List` API还包含数十种其他方法，其中许多是高阶函数：
+
+{% tabs list-methods %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val xs = List(1, 2, 3, 4, 5)
+
+xs.map(_ + 1) // List(2, 3, 4, 5, 6)
+xs.filter(_ < 3) // List(1, 2)
+xs.find(_ > 3) // Some(4)
+xs.takeWhile(_ < 3) // List(1, 2)
+```
+{% endtab %}
+{% endtabs %}
+
+在这些示例中，无法修改列表中的值。
+`List` 类是不可变的，因此所有这些方法都返回新值，如每个注释中的数据所示。
+
+## 2) 动态的感觉
+
+Scala的 _类型推断_ 经常使语言感觉是动态类型的，即使它是静态类型的。
+对于变量声明，情况确实如此：
+
+{% tabs dynamic %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = 1
+val b = "Hello, world"
+val c = List(1,2,3,4,5)
+val stuff = ("fish", 42, 1_234.5)
+```
+{% endtab %}
+{% endtabs %}
+
+当把匿名函数传递给高阶函数时，情况也是如此：
+
+{% tabs dynamic-hof %}
+{% tab 'Scala 2 and 3' %}
+```scala
+list.filter(_ < 4)
+list.map(_ * 2)
+list.filter(_ < 4)
+ .map(_ * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+还有定义方法的时候：
+
+{% tabs list-method %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def add(a: Int, b: Int) = a + b
+```
+{% endtab %}
+{% endtabs %}
+
+这在Scala 3中比以往任何时候都更加真实，例如在使用[union types][union-types] 时：
+
+{% tabs union %}
+{% tab 'Scala 3 Only' %}
+```scala
+// union type parameter
+def help(id: Username | Password) =
+ val user = id match
+ case Username(name) => lookupName(name)
+ case Password(hash) => lookupPassword(hash)
+ // more code here ...
+
+// union type value
+val b: Password | Username = if (true) name else password
+```
+{% endtab %}
+{% endtabs %}
+
+## 3) 简洁的语法
+
+Scala是一种 low ceremony，“简洁但仍然可读”的语言。例如，变量声明是简洁的：
+
+{% tabs concise %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = 1
+val b = "Hello, world"
+val c = List(1,2,3)
+```
+{% endtab %}
+{% endtabs %}
+
+创建类型如traits, 类和枚举都很简洁：
+
+{% tabs enum %}
+{% tab 'Scala 3 Only' %}
+```scala
+trait Tail:
+ def wagTail(): Unit
+ def stopTail(): Unit
+
+enum Topping:
+ case Cheese, Pepperoni, Sausage, Mushrooms, Onions
+
+class Dog extends Animal, Tail, Legs, RubberyNose
+
+case class Person(
+ firstName: String,
+ lastName: String,
+ age: Int
+)
+```
+{% endtab %}
+{% endtabs %}
+
+简洁的高阶函数：
+
+{% tabs list-hof %}
+{% tab 'Scala 2 and 3' %}
+```scala
+list.filter(_ < 4)
+list.map(_ * 2)
+```
+{% endtab %}
+{% endtabs %}
+
+所有这些表达方式以及更多表达方式都很简洁，并且仍然非常易读：我们称之为 _富有表现力_。
+
+## 4) 隐式，简化
+
+Scala 2 中的隐式是一个主要明显的设计特征。
+它们代表了抽象上下文的基本方式，具有服务于各种用例的统一范式，其中包括：
+
+- 实现 [type classes]({% link _zh-cn/overviews/scala3-book/ca-type-classes.md %})
+- 建立背景
+- 依赖注入
+- 表达能力
+
+从那以后，其他语言也采用了类似的概念，所有这些都是 _术语推断_ 核心思想的变体：给定一个类型，编译器合成一个具有该类型的“规范”术语。
+
+虽然隐式是 Scala 2 中的一个定义特性，但它们的设计在 Scala 3 中得到了极大的改进：
+
+- 定义“given”值的方法只有一种
+- 只有一种方法可以引入隐式参数和参数
+- 有一种单独的方式来导入 givens，不允许它们隐藏在正常导入的海洋中
+- 只有一种定义隐式转换的方法，它被清楚地标记为这样，并且不需要特殊的语法
+
+这些变化的好处包括：
+
+- 新设计避免了特性交叉，使语言更加一致
+- 它使隐式更容易学习和不容易滥用
+- 它极大地提高了 95% 使用隐式的 Scala 程序的清晰度
+- 它有可能以一种易于理解和友好的原则方式进行术语推断
+
+这些功能在其他部分有详细描述，因此请参阅 [上下文抽象介绍][context] 和 [`given` 和 `using` 子句][given] 部分了解更多详细信息。
+
+## 5) 与 Java 无缝集成
+
+Scala/Java 交互在许多方面都是无缝的。
+例如：
+
+- 您可以使用 Scala 项目中可用的所有数千个 Java 库
+- Scala `String` 本质上是 Java `String`，添加了附加功能
+- Scala 无缝使用 Java 中 *java.time._* 包中的日期/时间类
+
+您还可以在 Scala 中使用 Java 集合类，并为它们提供更多功能，Scala 包含方法，因此您可以将它们转换为 Scala 集合。
+
+虽然几乎所有交互都是无缝的，但[“与 Java 交互”一章][java] 演示了如何更好地结合使用某些功能，包括如何使用：
+
+- Scala 中的 Java 集合
+- Scala 中的 Java `Optional`
+- Scala 中的 Java 接口
+- Java 中的 Scala 集合
+- Java 中的 Scala `Option`
+- Java 中的 Scala traits
+- 在 Java 代码中引发异常的 Scala 方法
+- Java 中的 Scala 可变参数
+
+有关这些功能的更多详细信息，请参见该章。
+
+## 6) 客户 &服务器
+
+Scala 可以通过非常棒的框架在服务器端使用：
+
+- [Play Framework](https://www.playframework.com) 可让您构建高度可扩展的服务器端应用程序和微服务
+- [Akka Actors](https://akka.io) 让你使用actor模型大大简化分布式和并发软件应用程序
+
+Scala 也可以通过 [Scala.js 项目](https://www.scala-js.org) 在浏览器中使用，它是 JavaScript 的类型安全替代品。
+Scala.js 生态系统 [有几十个库](https://www.scala-js.org/libraries) 让您可以在浏览器中使用 React、Angular、jQuery 和许多其他 JavaScript 和 Scala 库。
+
+除了这些工具之外，[Scala Native](https://github.com/scala-native/scala-native) 项目“是一个优化的提前编译器和专为 Scala 设计的轻量级托管运行时”。它允许您使用纯 Scala 代码构建“系统”风格的二进制可执行应用程序，还允许您使用较低级别的原语。
+
+## 7) 标准库方法
+
+您将很少需要再次编写自定义的 `for` 循环，因为 Scala 标准库中的数十种预构建函数方法既可以节省您的时间，又有助于使代码在不同应用程序之间更加一致。
+
+下面的例子展示了一些内置的集合方法，除此之外还有很多。
+虽然这些都使用 `List` 类，但相同的方法适用于其他集合类，例如 `Seq`、`Vector`、`LazyList`、`Set`、`Map`、`Array` 和 `ArrayBuffer`。
+
+这里有些例子：
+
+{% tabs list-more %}
+{% tab 'Scala 2 and 3' %}
+```scala
+List.range(1, 3) // List(1, 2)
+List.range(start = 1, end = 6, step = 2) // List(1, 3, 5)
+List.fill(3)("foo") // List(foo, foo, foo)
+List.tabulate(3)(n => n * n) // List(0, 1, 4)
+List.tabulate(4)(n => n * n) // List(0, 1, 4, 9)
+
+val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10)
+a.distinct // List(10, 20, 30, 40)
+a.drop(2) // List(30, 40, 10)
+a.dropRight(2) // List(10, 20, 30)
+a.dropWhile(_ < 25) // List(30, 40, 10)
+a.filter(_ < 25) // List(10, 20, 10)
+a.filter(_ > 100) // List()
+a.find(_ > 20) // Some(30)
+a.head // 10
+a.headOption // Some(10)
+a.init // List(10, 20, 30, 40)
+a.intersect(List(19,20,21)) // List(20)
+a.last // 10
+a.lastOption // Some(10)
+a.map(_ * 2) // List(20, 40, 60, 80, 20)
+a.slice(2, 4) // List(30, 40)
+a.tail // List(20, 30, 40, 10)
+a.take(3) // List(10, 20, 30)
+a.takeRight(2) // List(40, 10)
+a.takeWhile(_ < 30) // List(10, 20)
+a.filter(_ < 30).map(_ * 10) // List(100, 200, 100)
+
+val fruits = List("apple", "pear")
+fruits.map(_.toUpperCase) // List(APPLE, PEAR)
+fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R)
+
+val nums = List(10, 5, 8, 1, 7)
+nums.sorted // List(1, 5, 7, 8, 10)
+nums.sortWith(_ < _) // List(1, 5, 7, 8, 10)
+nums.sortWith(_ > _) // List(10, 8, 7, 5, 1)
+```
+{% endtab %}
+{% endtabs %}
+
+## 8) 内置最佳实践
+
+Scala 习语以多种方式鼓励最佳实践。
+对于不可变性，我们鼓励您创建不可变的 `val` 声明：
+
+{% tabs val %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = 1 // 不可变变量
+```
+{% endtab %}
+{% endtabs %}
+
+还鼓励您使用不可变集合类，例如 `List` 和 `Map`：
+
+{% tabs list-map %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val b = List(1,2,3) // List 是不可变的
+val c = Map(1 -> "one") // Map 是不可变的
+```
+{% endtab %}
+{% endtabs %}
+
+样例类主要用于 [领域建模]({% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %})，它们的参数是不可变的：
+
+{% tabs case-class %}
+{% tab 'Scala 2 and 3' %}
+```scala
+case class Person(name: String)
+val p = Person("Michael Scott")
+p.name // Michael Scott
+p.name = "Joe" // 编译器错误（重新分配给 val 名称）
+```
+{% endtab %}
+{% endtabs %}
+
+如上一节所示，Scala 集合类支持高阶函数，您可以将方法（未显示）和匿名函数传递给它们：
+
+{% tabs higher-order %}
+{% tab 'Scala 2 and 3' %}
+```scala
+a.dropWhile(_ < 25)
+a.filter(_ < 25)
+a.takeWhile(_ < 30)
+a.filter(_ < 30).map(_ * 10)
+nums.sortWith(_ < _)
+nums.sortWith(_ > _)
+```
+{% endtab %}
+{% endtabs %}
+
+`match` 表达式让您可以使用模式匹配，它们确实是返回值的 _表达式_：
+
+{% tabs match class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val numAsString = i match {
+ case 1 | 3 | 5 | 7 | 9 => "odd"
+ case 2 | 4 | 6 | 8 | 10 => "even"
+ case _ => "too big"
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val numAsString = i match
+ case 1 | 3 | 5 | 7 | 9 => "odd"
+ case 2 | 4 | 6 | 8 | 10 => "even"
+ case _ => "too big"
+```
+{% endtab %}
+{% endtabs %}
+
+因为它们可以返回值，所以它们经常被用作方法的主体：
+
+{% tabs match-body class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def isTruthy(a: Matchable) = a match {
+ case 0 | "" => false
+ case _ => true
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def isTruthy(a: Matchable) = a match
+ case 0 | "" => false
+ case _ => true
+```
+{% endtab %}
+{% endtabs %}
+
+## 9) 生态系统库
+
+用于函数式编程的 Scala 库，如 [Cats](https://typelevel.org/cats) 和 [Zio](https://zio.dev) 是 FP 社区中的前沿库。
+所有流行语，如高性能、类型安全、并发、异步、资源安全、可测试、函数式、模块化、二进制兼容、高效、副作用/有副作用等，都可以用于这些库。
+
+我们可以在这里列出数百个库，但幸运的是它们都列在另一个位置：有关这些详细信息，请参阅 [“Awesome Scala” 列表](https://github.com/lauris/awesome-scala)。
+
+## 10) 强类型系统
+
+Scala 有一个强大的类型系统，它在 Scala 3 中得到了更多的改进。
+Scala 3 的目标很早就定义了，与类型系统相关的目标包括：
+
+- 简化
+- 消除不一致
+- 安全
+- 人体工程学
+- 性能
+
+_简化_ 来自数十个更改和删除的特性。
+例如，从 Scala 2 中重载的 `implicit` 关键字到 Scala 3 中的术语 `given` 和 `using` 的变化使语言更加清晰，尤其是对于初学者来说。
+
+_消除不一致_ 与Scala 3中的几十个[删除的特性][dropped]、[改变的特性][changed]和[增加的特性][add]有关。
+此类别中一些最重要的功能是：
+
+- 交集类型
+- 并集类型
+- 隐式函数类型
+- 依赖函数类型
+- trait 参数
+- 通用元组
+
+{% comment %}
+A list of types from the Dotty documentation:
+
+- Inferred types
+- Generics
+- Intersection types
+- Union types
+- Structural types
+- Dependent function types
+- Type classes
+- Opaque types
+- Variance
+- Algebraic Data Types
+- Wildcard arguments in types: ? replacing _
+- Type lambdas
+- Match types
+- Existential types
+- Higher-kinded types
+- Singleton types
+- Refinement types
+- Kind polymorphism
+- Abstract type members and path-dependent types
+- Dependent function types
+- Bounds
+{% endcomment %}
+
+_安全_ 与几个新的和改变的特性有关：
+
+- Multiversal equality
+- Restricting implicit conversions
+- Null safety
+- Safe initialization
+
+_人体工程学_ 的好例子是枚举和扩展方法，它们以非常易读的方式添加到 Scala 3 中：
+
+{% tabs extension %}
+{% tab 'Scala 3 Only' %}
+```scala
+// 枚举
+enum Color:
+ case Red, Green, Blue
+
+// 扩展方法
+extension (c: Circle)
+ def circumference: Double = c.radius * math.Pi * 2
+ def diameter: Double = c.radius * 2
+ def area: Double = math.Pi * c.radius * c.radius
+```
+{% endtab %}
+{% endtabs %}
+
+_性能_ 涉及几个方面。
+其中之一是 [不透明类型][opaque-types]。
+在 Scala 2 中，有几次尝试创建解决方案以与域驱动设计 (DDD) 实践相一致，即赋予值更有意义的类型。
+这些尝试包括：
+
+- 类型别名
+- 值类
+- 样例类
+
+不幸的是，所有这些方法都有弱点，如 [_Opaque Types_ SIP](https://docs.scala-lang.org/sips/opaque-types.html) 中所述。
+相反，如 SIP 中所述，不透明类型的目标是“对这些包装器类型的操作不得在运行时产生任何额外开销，同时在编译时仍提供类型安全使用。”
+
+有关更多类型系统的详细信息，请参阅 [参考文档][reference]。
+
+## 其他很棒的功能
+
+Scala 有许多很棒的特性，选择十大列表可能是主观的。
+多项调查表明，不同的开发人员群体喜欢不同的特性。
+
+[java]: {% link _zh-cn/overviews/scala3-book/interacting-with-java.md %}
+[given]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %}
+[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %}
+[reference]: {{ site.scala3ref }}
+[dropped]: {{ site.scala3ref }}/dropped-features
+[changed]: {{ site.scala3ref }}/changed-features
+[added]:{{ site.scala3ref }}/other-new-features
+
+[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %}
+[opaque-types]: {% link _zh-cn/overviews/scala3-book/types-opaque-types.md %}
diff --git a/_zh-cn/overviews/thanks.md b/_zh-cn/overviews/thanks.md
index e1429b74f0..e2fac4be7a 100644
--- a/_zh-cn/overviews/thanks.md
+++ b/_zh-cn/overviews/thanks.md
@@ -1,7 +1,8 @@
---
-layout: inner-page-no-masthead
+layout: singlepage-overview
language: zh-cn
title: 致谢名单
+orphanTranslation: true
---
2013年10月份起，CSDN CODE开始组织志愿者翻译Scala官方文档。计划翻译的文档主要为Scala官网上overview部分的内容，包含以下部分：
diff --git a/_zh-cn/scala3/guides/tasty-overview.md b/_zh-cn/scala3/guides/tasty-overview.md
new file mode 100644
index 0000000000..9ab7cc3124
--- /dev/null
+++ b/_zh-cn/scala3/guides/tasty-overview.md
@@ -0,0 +1,146 @@
+---
+layout: singlepage-overview
+title: TASTy 概览
+---
+假定你创建了一个 Scala 3 源代码文件叫 _Hello.scala_:
+
+```scala
+@main def hello = println("Hello, world")
+```
+
+然后用 `scalac` 编译了该文件：
+
+```bash
+$ scalac Hello.scala
+```
+
+你会发现在 `scalac` 生成的其它文件结果中，有些文件是以 _.tasty_ 为扩展名：
+
+```bash
+$ ls -1
+Hello$package$.class
+Hello$package.class
+Hello$package.tasty
+Hello.scala
+hello.class
+hello.tasty
+```
+
+这自然地会引出一个问题，“什么是 tasty？”
+
+## 什么是 TASTy?
+
+TASTy 是从 _Typed Abstract Syntax Trees_ 这个术语的首字母缩写来的。它是 Scala 3 的高级交换格式，在本文档中，我们将它称为 _Tasty_ 。
+
+首先要知道的是，Tasty 文件是由 `scalac` 编译器生成的，并且包含 _所有_ 有关源代码的信息，这些信息包括程序的语法结构，以及有关类型，位置甚至文档的 _所有_ 信息。Tasty 文件包含的信息比 _.class_ 文件多得多，后者是为在 JVM 上运行而生成的。（后面有详细介绍）。
+
+在 Scala 3 中，编译流程像这样：
+
+```text
+ +-------------+ +-------------+ +-------------+
+$ scalac | Hello.scala | -> | Hello.tasty | -> | Hello.class |
+ +-------------+ +-------------+ +-------------+
+ ^ ^ ^
+ | | |
+ 你的代码 TASTy 文件 Class 文件
+ 用于 scalac 用于 JVM
+ （包括完整信息） （不完整信息）
+```
+
+您可以通过使用 `-print-tasty` 标志在 _.tasty_ 文件上运行编译器，以人类可读的形式查看 _.tasty_ 文件的内容。
+您还可以使用 `-decompile` 标志以类似于 Scala 源代码的形式查看反编译的内容。
+
+```bash
+$ scalac -print-tasty hello.tasty
+$ scalac -decompile hello.tasty
+```
+
+### The issue with _.class_ files
+
+由于象 [类型擦除][erasure] 等问题，_.class_ 文件实际上是代码的不完整表示形式。
+演示这一点的一种简单方法是使用 `List` 示例。
+
+_类型擦除_ 意味着当你编写这样的Scala代码，并假定它是在JVM上运行时：
+
+```scala
+val xs: List[Int] = List(1, 2, 3)
+```
+
+该代码被编译为需要与 JVM 兼容的 _.class_ 文件。由于该兼容性要求，该类文件中的代码 --- 您可以使用 `javap` 命令看到它，--- 最终看起来像这样：
+
+```java
+public scala.collection.immutable.List xs();
+```
+
+该 `javap` 命令输出显示了类文件中包含的内容，该内容是 Java 的表示形式。请注意，在此输出中，`xs` _不是_ 定义为 `List[Int]` ；它真正表示的是 `List[java.lang.Object]` 。为了使您的 Scala 代码与 JVM 配合使用，`Int` 类型已被擦除。
+
+稍后，当您在 Scala 代码中访问 `List[Int]` 的元素时，像这样：
+
+```scala
+val x = xs(0)
+```
+
+生成的类文件对此行代码进行强制转换操作，您可以将其想象成：
+
+```
+int x = (Int) xs.get(0) // Java-ish
+val x = xs.get(0).asInstanceOf[Int] // more Scala-like
+```
+
+同样，这样做是为了兼容性，因此您的 Scala 代码可以在 JVM 上运行。但是，我们已经有的整数列表的信息在类文件中丢失了。
+当尝试使用已编译的库来编译 Scala 程序时，会带来问题。为此，我们需要的信息比类文件中通常可用的信息更多。
+
+此讨论仅涵盖类型擦除的主题。对于 JVM 没有意识到的所有其他 Scala 结构，也存在类似的问题，包括 unions, intersections, 带有参数的 traits 以及更多 Scala 3 特性。
+
+### TASTy to the Rescue
+
+因此，TASTy 格式不是像 _.class_ 文件那样没有原始类型的信息，或者只有公共 API（如Scala 2.13 “Pickle” 格式），而是在类型检查后存储完整的抽象语法树（AST）。存储整个 AST 有很多优点：它支持单独编译，针对不同的 JVM 版本重新编译，程序的静态分析等等。
+
+### 重点
+
+因此，这是本节的第一个要点：您在 Scala 代码中指定的类型在 _.class_ 文件中没有完全准确地表示。
+
+第二个关键点是要了解 _编译时_ 和 _运行时_ 提供的信息之间存在差异：
+
+- 在**编译时**，当 `scalac` 读取和分析你的代码时，它知道 `xs` 是一个 `List[Int]`
+- 当编译器将你的代码写入类文件时，它会写 `xs` 是 `List[Object]` ，并在访问 `xs` 的任何地方添加转换信息
+- 然后在**运行时** --- 你的代码在 JVM 中运行，--- JVM 不知道你的列表是一个 `List[Int]`
+
+对于 Scala 3 和 Tasty，这里有一个关于编译时的重要说明：
+
+- 当您编写使用其他 Scala 3 库的 Scala 3 代码时，`scalac` 不必再读取其 _.class_ 文件;它可以读取其 _.tasty_ 文件，如前所述，这些文件是代码的 _准确_ 表示形式。这对于在 Scala 2.13 和 Scala 3 之间实现单独编译和兼容性非常重要。
+
+## Tasty 的好处
+
+可以想象，拥有代码的完整表示形式具有[许多好处][benefits]：
+
+- 编译器使用它来支持单独的编译。
+- Scala 基于 _Language Server Protocol_ 的语言服务器使用它来支持超链接、命令补全、文档以及全局操作，如查找引用和重命名。
+- Tasty 为新一代[基于反射的宏][macros]奠定了良好的基础。
+- 优化器和分析器可以使用它进行深度代码分析和高级代码生成。
+
+在相关的说明中，Scala 2.13.6 有一个 TASTy 读取器，Scala 3 编译器也可以读取2.13“Pickle”格式。Scala 3 迁移指南中的 [类路径兼容性页面][compatibility-ref] 解释了此交叉编译功能的好处。
+
+## 更多信息
+
+总之，Tasty 是 Scala 3 的高级交换格式，_.tasty_ 文件包含源代码的完整表示形式，从而带来了上一节中概述的好处。
+
+有关更多详细信息，请参阅以下资源：
+
+- 在 [此视频](https://www.youtube.com/watch?v=YQmVrUdx8TU) 中，Scala 中心的Jamie Thompson 对 Tasty 的工作原理及其优势进行了详尽的讨论
+- [库作者的二进制兼容性][binary] 讨论二进制兼容性、源代码兼容性和 JVM 执行模型
+- [Scala 3 Transition 的前向兼容性](https://www.scala-lang.org/blog/2020/11/19/scala-3-forward-compat.html) 演示了在同一项目中使用 Scala 2.13 和 Scala 3 的技术
+
+这些文章提供了有关 Scala 3 宏的更多信息：
+
+- [Scala 宏库](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html)
+- [宏：Scala 3 的计划](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html)
+- [Quotes Reflect 的参考文档][quotes-reflect]
+- [宏的参考文档][macros]
+
+[benefits]: https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html
+[erasure]: https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure
+[binary]: {% link _overviews/tutorials/binary-compatibility-for-library-authors.md %}
+[compatibility-ref]: {% link _overviews/scala3-migration/compatibility-classpath.md %}
+[quotes-reflect]: {{ site.scala3ref }}/metaprogramming/reflection.html
+[macros]: {{ site.scala3ref }}/metaprogramming/macros.html
diff --git a/_zh-cn/scala3/new-in-scala3.md b/_zh-cn/scala3/new-in-scala3.md
new file mode 100644
index 0000000000..5f82276635
--- /dev/null
+++ b/_zh-cn/scala3/new-in-scala3.md
@@ -0,0 +1,122 @@
+---
+layout: singlepage-overview
+title: Scala 3 里的新东西
+scala3: true
+---
+令人振奋的新版 Scala 3 带来了许多改进和新功能。在这里，我们为你提供最重要的变更的快速概述。如果你想深入挖掘，还有一些参考资料供你使用：
+
+- [Scala 3 Book]({% link _overviews/scala3-book/introduction.md %}) 面向刚接触 Scala 语言的开发人员。
+- [Syntax Summary][syntax-summary] 为您提供了新语法的正式描述。
+- [Language Reference][reference] 对 Scala 2 到 Scala 3 的变化做了详细说明。
+- [Migration Guide][migration] 为你提供了从 Scala 2 迁移到 Scala 3 的所有必要信息。
+- [Scala 3 Contributing Guide][contribution] Scala 3 贡献指南，更深入地探讨了编译器，包括修复问题的指南。
+
+## Scala 3 里有什么新东西
+Scala 3 是对 Scala 语言的一次彻底改造。在其核心部分，类型系统的许多方面都被改变了，变得更有原则性。虽然这也带来了令人兴奋的新功能（比如联合类型），但首先意味着类型系统变得（甚至）不那么碍事了，例如[类型推断][type-inference]和 overload resolution 都得到了很大的改善。
+
+### 新的和闪亮的：语法
+除了许多（小的）清理工作，Scala 3 的语法还提供了以下改进：
+
+- 用于控制结构的新“quiet”语法，如 `if`、`while` 和 `for` 。 ([new control syntax][syntax-control])
+- `new` 关键字是可选的 (_aka_ [creator applications][creator])
+- [Optional braces][syntax-indentation]：可选的大括号，支持不受干扰、缩进敏感的编程风格
+- [类型级通配符][syntax-wildcard] 从 `_` 更改为 `?`。
+- implicit（和它们的语法）已被[大量修订][implicits]。
+
+### Opinionated: 上下文抽象
+Scala的一个基本核心概念是（在某种程度上仍然是）为用户提供一小部分强大的功能，这些功能可以被组合成巨大的（有时甚至是不可预见的）表达能力。例如，_implicit_ 的特性被用来模拟上下文抽象、表达类型级计算、模拟类型类、执行隐式强制、编码扩展方法等等。从这些用例中学习，Scala 3 采取了一种略微不同的方法，专注于 **意图** 而非 **机制**。Scala 3 没有提供一个非常强大的功能，而是提供了多个定制的语言功能，让程序员直接表达他们的意图。
+
+- **Abtracting over contextual information**. [Using clauses][contextual-using] 允许程序员对调用上下文中的信息进行抽象，这些信息应该以隐式方式传递。作为对 Scala 2 implicits 的改进，可以按类型指定 using 子句，从而将函数签名从从未显式引用的术语变量名中解放出来。
+
+- **Providing Type-class instances**. [Given instances][contextual-givens] 允许程序员定义某个类型的 _规范值_ 。这使得使用类型类的编程更加简单，而不会泄露实现细节。
+
+- **Retroactively extending classes**. 在 Scala 2 中，扩展方法必须使用隐式转换或隐式类进行编码。相比之下，在 Scala 3 中，[extension methods][contextual-extension]现在直接内置于语言中，从而产生更好的错误消息和改进的类型推断。
+
+- **Viewing one type as another**. [隐式转换][contextual-conversions]已经被重新设计为类型类`Conversion`的实例。
+
+- **Higher-order contextual abstractions**. [context functions][contextual-functions]的 _全新_ 功能使上下文抽象成为第一等公民。它们是库开发人员的一个重要工具，允许表达简洁的特定领域语言。
+
+- **Actionable feedback from the compiler**. 如果一个隐式参数不能被编译器解决，它现在提供了可能解决这个问题的[import suggestions](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html)。
+
+### 表达真正的意思: 类型系统改进
+除了极大地改进了类型推断，Scala 3 类型系统还提供了许多新的功能，还为你提供了强大的工具来静态地表达类型中的不变量：
+
+- **Enumerations**. [枚举][enums]已经被重新设计，以便与样例类很好地融合，并形成表达[代数数据类型][enums-adts]的新标准。
+
+- **Opaque Types**. 将实现细节隐藏在[opaque type aliases][types-opaque]的别名后面，而不需要在性能上付出代价! Opaque types 取代了值类，并允许你建立一个抽象的屏障，而不会造成额外的装箱开销。
+
+- **Intersection and union types**. 将类型系统建立在新的基础上，引入了新的类型系统特性：[intersection types][types-intersection]的实例，如`A & B`，既是`A`的实例，也是`B`的实例；[union types][types-union]的实例，如`A | B`，是`A`或`B`的实例。这两种结构都允许程序员在继承层次结构之外灵活地表达类型约束。
+
+- **Dependent function types**. Scala 2 已经允许返回类型依赖于（值）参数。在 Scala 3 中，现在可以对这种模式进行抽象，表达[dependent function types][types-dependent]。在类型`F = (e: Entry) => e.Key`中，结果类型取决于参数。
+
+- **Polymorphic function types**. 与 dependent function types 一样，Scala 2 支持拥有类型参数的方法，但不允许程序员对这些方法进行抽象。在 Scala 3 中，像`[A] => List[A] => List[A]`这样的[polymorphic function types][types-polymorphic]可以抽象出除值参数外还接受 _类型参数_ 的函数。
+
+- **Type lambdas**. 在 Scala 2 中需要用[编译器插件](https://github.com/typelevel/kind-projector)来表达的东西，现在在 Scala 3 中是原生支持的功能：类型lambdas是类型级别的函数，可以作为（高等类型的）类型参数传递，而不需要辅助类型定义。
+
+- **Match types**. Scala 3 提供了对[matching on types][types-match]的直接支持，而不是使用隐式解析对类型级别的计算进行编码。将类型级计算整合到类型检查器中，可以改进错误信息，并消除对复杂编码的需求。
+
+### Re-envisioned：面向对象的编程
+Scala 一直处于函数式编程和面向对象编程的前沿 -- 而 Scala 3 在这两个方向上都推动了边界的发展! 上述类型系统的变化和上下文抽象的重新设计使得 _函数式编程_ 比以前更容易。同时，以下的新特性使结构良好的 _面向对象设计_ 成为可能，并支持最佳实践。
+
+- **Pass it on**. Trait 更接近于 class，现在也可以接受[参数][oo-trait-parameters]，使其作为模块化软件分解的工具更加强大。
+
+- **Plan for extension**. 在面向对象的设计中，扩展那些不打算扩展的类是一个长期存在的问题。为了解决这个问题，[open classes][oo-open]要求库设计者 _明确地_ 将类标记为 open（开放的）。
+
+- **Hide implementation details**. 实现功能的工具性的traits有时不应该是推断类型的一部分。在 Scala 3 中，这些traits可以被标记为[transparent][oo-transparent]，（在推断类型中）向用户隐藏继承信息。
+
+- **Composition over inheritance**. 这句话经常被引用，但实现起来却很繁琐。Scala 3 的[export clauses][oo-export]则不然：与imports对应，export clauses 允许用户为对象的选定成员定义别名。
+
+- **No more NPEs**. Scala 3 比以往任何时候都更安全：[explicit null][oo-explicit-null]将`null`移出了类型层次结构，帮助你静态地捕捉错误；[safe initialization][oo-safe-init]的额外检查可以检测对未初始化对象的访问。
+
+### Batteries Included: 元编程
+Scala 2 中的宏只是一个实验性的功能，而 Scala 3 则为元编程提供了强大的工具库。[宏教程]({% link _overviews/scala3-macros/tutorial/index.md %})中包含了关于不同设施的详细信息。特别是，Scala 3 为元编程提供了以下功能：
+
+- **Inline**. [inline feature][meta-inline]允许在编译时化简值和方法。这个简单的功能已经涵盖了许多使用情况，同时也为更高级的功能提供了入口。
+- **Compile-time operations**. 包[`scala.compiletime`][meta-compiletime]中包含了额外的功能，可以用来实现内联方法。
+- **Quoted code blocks**. Scala 3为代码增加了[quasi-quotation][meta-quotes]的新功能，这为构建和分析代码提供了方便的高级接口。构建加一加一的代码就像`'{ 1 + 1 }`一样简单。
+- **Reflection API**. 对于更高级的用例，[quotes.reflect][meta-reflection]提供了更详细的控制来检查和生成程序树。
+
+如果你想进一步了解 Scala 3 中的元编程，我们邀请你参阅我们的[教程][meta-tutorial]。
+
+[enums]: {{ site.scala3ref }}/enums/enums.html
+[enums-adts]: {{ site.scala3ref }}/enums/adts.html
+
+[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html
+[types-union]: {{ site.scala3ref }}/new-types/union-types.html
+[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html
+[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html
+[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html
+[types-match]: {{ site.scala3ref }}/new-types/match-types.html
+[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html
+
+[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html
+[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html
+[reference]: {{ site.scala3ref }}/overview.html
+[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html
+[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %}
+[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %}
+
+[implicits]: {{ site.scala3ref }}/contextual
+[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html
+[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html
+[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html
+[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html
+[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html
+
+[syntax-summary]: {{ site.scala3ref }}/syntax.html
+[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html
+[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html
+[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html
+
+[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %}
+[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %}
+[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %}
+[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %}
+[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %}
+
+[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html
+[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html
+[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html
+[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html
+[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html
+[oo-export]: {{ site.scala3ref }}/other-new-features/export.html
diff --git a/_zh-cn/scala3/reference/README.md b/_zh-cn/scala3/reference/README.md
new file mode 100644
index 0000000000..960554be5f
--- /dev/null
+++ b/_zh-cn/scala3/reference/README.md
@@ -0,0 +1,5 @@
+https://docs.scala-lang.org/scala3/reference 的页面内容是从 [Scala 3 编译器库](https://github.com/scala/scala3) 生成的。
+
+请到这里为 Scala 3 参考文档做贡献：
+
+https://github.com/scala/scala3/tree/main/docs/_docs
diff --git a/_zh-cn/thanks.md b/_zh-cn/thanks.md
index e1429b74f0..e2fac4be7a 100644
--- a/_zh-cn/thanks.md
+++ b/_zh-cn/thanks.md
@@ -1,7 +1,8 @@
---
-layout: inner-page-no-masthead
+layout: singlepage-overview
language: zh-cn
title: 致谢名单
+orphanTranslation: true
---
2013年10月份起，CSDN CODE开始组织志愿者翻译Scala官方文档。计划翻译的文档主要为Scala官网上overview部分的内容，包含以下部分：
diff --git a/_zh-cn/tour/automatic-closures.md b/_zh-cn/tour/automatic-closures.md
deleted file mode 100644
index b51652c94e..0000000000
--- a/_zh-cn/tour/automatic-closures.md
+++ /dev/null
@@ -1,7 +0,0 @@
----
-layout: tour
-title: Automatic Closures
-partof: scala-tour
-
-language: zh-cn
----
diff --git a/_zh-cn/tour/basics.md b/_zh-cn/tour/basics.md
index 55bbc97a4f..a7f9c3bf0a 100644
--- a/_zh-cn/tour/basics.md
+++ b/_zh-cn/tour/basics.md
@@ -14,16 +14,14 @@ previous-page: tour-of-scala
## 在浏览器上尝试Scala
-你可以在浏览器上使用ScalaFiddle运行Scala。
+你可以在浏览器上使用Scastie运行Scala。
-1. 打开[https://scalafiddle.io](https://scalafiddle.io)；
+1. 打开[Scastie](https://scastie.scala-lang.org/)；
2. 在左侧窗格中粘贴`println("Hello, world!")`；
3. 点击"Run"按钮，输出将展现在右侧窗格中。
这是一种简单的、零设置的方法来实践Scala的代码片段。
-这篇文档中的大部分代码示例与 ScalaFiddle 进行了集成，可以通过点击 “Run” 按钮即来直接运行 Scala 代码。
-
## 表达式
表达式是可计算的语句。
@@ -32,14 +30,12 @@ previous-page: tour-of-scala
```
你可以使用`println`来输出表达式的结果。
-{% scalafiddle %}
```scala mdoc
println(1) // 1
println(1 + 1) // 2
println("Hello!") // Hello!
println("Hello," + " world!") // Hello, world!
```
-{% endscalafiddle %}
### 常量（`Values`）
@@ -58,7 +54,7 @@ println(x) // 2
x = 3 // This does not compile.
```
-常量（`values`）的类型可以被推断，或者你也可以显示地声明类型，例如：
+常量（`values`）的类型可以被推断，或者你也可以显式地声明类型，例如：
```scala mdoc:nest
val x: Int = 1 + 1
@@ -76,7 +72,7 @@ x = 3 // This compiles because "x" is declared with the "var" keyword.
println(x * x) // 9
```
-和常量一样，你可以显示地声明类型：
+和常量一样，你可以显式地声明类型：
```scala mdoc:nest
var x: Int = 1 + 1
@@ -110,21 +106,17 @@ println({
你也可以给函数命名。
-{% scalafiddle %}
```scala mdoc
val addOne = (x: Int) => x + 1
println(addOne(1)) // 2
```
-{% endscalafiddle %}
函数可带有多个参数。
-{% scalafiddle %}
```scala mdoc
val add = (x: Int, y: Int) => x + y
println(add(1, 2)) // 3
```
-{% endscalafiddle %}
或者不带参数。
@@ -139,23 +131,19 @@ println(getTheAnswer()) // 42
方法由`def`关键字定义。`def`后面跟着一个名字、参数列表、返回类型和方法体。
-{% scalafiddle %}
```scala mdoc:nest
def add(x: Int, y: Int): Int = x + y
println(add(1, 2)) // 3
```
-{% endscalafiddle %}
注意返回类型是怎么在函数列表和一个冒号`: Int`之后声明的。
方法可以接受多个参数列表。
-{% scalafiddle %}
```scala mdoc
def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier
println(addThenMultiply(1, 2)(3)) // 9
```
-{% endscalafiddle %}
或者没有参数列表。
@@ -168,7 +156,6 @@ println("Hello, " + name + "!")
方法也可以有多行的表达式。
-{% scalafiddle %}
```scala mdoc
def getSquareString(input: Double): String = {
val square = input * input
@@ -176,7 +163,6 @@ def getSquareString(input: Double): String = {
}
println(getSquareString(2.5)) // 6.25
```
-{% endscalafiddle %}
方法体的最后一个表达式就是方法的返回值。（Scala中也有一个`return`关键字，但是很少使用）
@@ -221,15 +207,15 @@ val yetAnotherPoint = Point(2, 2)
```scala mdoc
if (point == anotherPoint) {
- println(point + " and " + anotherPoint + " are the same.")
+ println(s"$point and $anotherPoint are the same.")
} else {
- println(point + " and " + anotherPoint + " are different.")
+ println(s"$point and $anotherPoint are different.")
} // Point(1,2) and Point(1,2) are the same.
if (point == yetAnotherPoint) {
- println(point + " and " + yetAnotherPoint + " are the same.")
+ println(s"$point and $yetAnotherPoint are the same.")
} else {
- println(point + " and " + yetAnotherPoint + " are different.")
+ println(s"$point and $yetAnotherPoint are different.")
} // Point(1,2) and Point(2,2) are different.
```
@@ -276,7 +262,6 @@ trait Greeter {
特质也可以有默认的实现。
-{% scalafiddle %}
```scala mdoc:reset
trait Greeter {
def greet(name: String): Unit =
@@ -301,7 +286,6 @@ greeter.greet("Scala developer") // Hello, Scala developer!
val customGreeter = new CustomizableGreeter("How are you, ", "?")
customGreeter.greet("Scala developer") // How are you, Scala developer?
```
-{% endscalafiddle %}
这里，`DefaultGreeter`仅仅继承了一个特质，它还可以继承多个特质。
diff --git a/_zh-cn/tour/case-classes.md b/_zh-cn/tour/case-classes.md
index cbff24d6e9..15a2dbf4cb 100644
--- a/_zh-cn/tour/case-classes.md
+++ b/_zh-cn/tour/case-classes.md
@@ -1,6 +1,6 @@
---
layout: tour
-title: 案例类（Case Classes）
+title: 样例类（Case Classes）
partof: scala-tour
num: 10
@@ -11,18 +11,18 @@ next-page: pattern-matching
previous-page: multiple-parameter-lists
---
-案例类（Case classes）和普通类差不多，只有几点关键差别，接下来的介绍将会涵盖这些差别。案例类非常适合用于不可变的数据。下一节将会介绍他们在[模式匹配](pattern-matching.html)中的应用。
+样例类（Case classes）和普通类差不多，只有几点关键差别，接下来的介绍将会涵盖这些差别。样例类非常适合用于不可变的数据。下一节将会介绍他们在[模式匹配](pattern-matching.html)中的应用。
-## 定义一个案例类
-一个最简单的案例类定义由关键字`case class`，类名，参数列表（可为空）组成：
+## 定义一个样例类
+一个最简单的样例类定义由关键字`case class`，类名，参数列表（可为空）组成：
```scala mdoc
case class Book(isbn: String)
val frankenstein = Book("978-0486282114")
```
-注意在实例化案例类`Book`时，并没有使用关键字`new`，这是因为案例类有一个默认的`apply`方法来负责对象的创建。
+注意在实例化样例类`Book`时，并没有使用关键字`new`，这是因为样例类有一个默认的`apply`方法来负责对象的创建。
-当你创建包含参数的案例类时，这些参数是公开（public）的`val`
+当你创建包含参数的样例类时，这些参数是公开（public）的`val`
```
case class Message(sender: String, recipient: String, body: String)
val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?")
@@ -30,10 +30,10 @@ val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?")
println(message1.sender) // prints guillaume@quebec.ca
message1.sender = "travis@washington.us" // this line does not compile
```
-你不能给`message1.sender`重新赋值，因为它是一个`val`（不可变）。在案例类中使用`var`也是可以的，但并不推荐这样。
+你不能给`message1.sender`重新赋值，因为它是一个`val`（不可变）。在样例类中使用`var`也是可以的，但并不推荐这样。
## 比较
-案例类在比较的时候是按值比较而非按引用比较：
+样例类在比较的时候是按值比较而非按引用比较：
```
case class Message(sender: String, recipient: String, body: String)
@@ -44,7 +44,7 @@ val messagesAreTheSame = message2 == message3 // true
尽管`message2`和`message3`引用不同的对象，但是他们的值是相等的，所以`message2 == message3`为`true`。
## 拷贝
-你可以通过`copy`方法创建一个案例类实例的浅拷贝，同时可以指定构造参数来做一些改变。
+你可以通过`copy`方法创建一个样例类实例的浅拷贝，同时可以指定构造参数来做一些改变。
```
case class Message(sender: String, recipient: String, body: String)
val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg")
diff --git a/_zh-cn/tour/extractor-objects.md b/_zh-cn/tour/extractor-objects.md
index d6d75aaad8..c74d946482 100644
--- a/_zh-cn/tour/extractor-objects.md
+++ b/_zh-cn/tour/extractor-objects.md
@@ -18,7 +18,7 @@ import scala.util.Random
object CustomerID {
- def apply(name: String) = s"$name--${Random.nextLong}"
+ def apply(name: String) = s"$name--${Random.nextLong()}"
def unapply(customerID: String): Option[String] = {
val stringArray: Array[String] = customerID.split("--")
diff --git a/_zh-cn/tour/implicit-conversions.md b/_zh-cn/tour/implicit-conversions.md
index 48049bc249..4c2d94cc0b 100644
--- a/_zh-cn/tour/implicit-conversions.md
+++ b/_zh-cn/tour/implicit-conversions.md
@@ -47,8 +47,8 @@ implicit def list2ordered[A](x: List[A])
```scala mdoc
import scala.language.implicitConversions
-implicit def int2Integer(x: Int) =
- java.lang.Integer.valueOf(x)
+implicit def int2Integer(x: Int): Integer =
+ Integer.valueOf(x)
```
因为如果不加选择地使用隐式转换可能会导致陷阱，编译器会在编译隐式转换定义时发出警告。
diff --git a/_zh-cn/tour/implicit-parameters.md b/_zh-cn/tour/implicit-parameters.md
index aa264c086d..e8e89451e6 100644
--- a/_zh-cn/tour/implicit-parameters.md
+++ b/_zh-cn/tour/implicit-parameters.md
@@ -18,7 +18,7 @@ Scala 将查找这些参数的位置分为两类：
* Scala 在调用包含有隐式参数块的方法时，将首先查找可以直接访问的隐式定义和隐式参数 (无前缀)。
* 然后，它在所有伴生对象中查找与隐式候选类型相关的有隐式标记的成员。
-更加详细的关于 Scala 到哪里查找隐式参数的指南请参考 [常见问题](//docs.scala-lang.org/tutorials/FAQ/finding-implicits.html)
+更加详细的关于 Scala 到哪里查找隐式参数的指南请参考 [常见问题](/tutorials/FAQ/finding-implicits.html)
在下面的例子中，我们定义了一个方法 `sum`，它使用 Monoid 类的 `add` 和 `unit` 方法计算一个列表中元素的总和。 请注意，隐式值不能是顶级值。
diff --git a/_zh-cn/tour/inner-classes.md b/_zh-cn/tour/inner-classes.md
index d8fede0742..a390c0b340 100644
--- a/_zh-cn/tour/inner-classes.md
+++ b/_zh-cn/tour/inner-classes.md
@@ -19,7 +19,7 @@ previous-page: lower-type-bounds
class Graph {
class Node {
var connectedNodes: List[Node] = Nil
- def connectTo(node: Node) {
+ def connectTo(node: Node): Unit = {
if (!connectedNodes.exists(node.equals)) {
connectedNodes = node :: connectedNodes
}
@@ -63,7 +63,7 @@ node1.connectTo(node3) // illegal!
class Graph {
class Node {
var connectedNodes: List[Graph#Node] = Nil
- def connectTo(node: Graph#Node) {
+ def connectTo(node: Graph#Node): Unit = {
if (!connectedNodes.exists(node.equals)) {
connectedNodes = node :: connectedNodes
}
@@ -77,4 +77,3 @@ class Graph {
}
}
```
-
diff --git a/_zh-cn/tour/operators.md b/_zh-cn/tour/operators.md
index 5c415752fa..9bca79a928 100644
--- a/_zh-cn/tour/operators.md
+++ b/_zh-cn/tour/operators.md
@@ -65,7 +65,7 @@ def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y)
&
^
|
-(all letters)
+(all letters, $, _)
```
这也适用于你自定义的方法。 例如，以下表达式：
```
diff --git a/_zh-cn/tour/pattern-matching.md b/_zh-cn/tour/pattern-matching.md
index c340c48546..36ad508a7c 100644
--- a/_zh-cn/tour/pattern-matching.md
+++ b/_zh-cn/tour/pattern-matching.md
@@ -42,9 +42,9 @@ matchTest(1) // one
```
这个`match`表达式是String类型的，因为所有的情况（case）均返回String，所以`matchTest`函数的返回值是String类型。
-## 案例类（case classes）的匹配
+## 样例类（case classes）的匹配
-案例类非常适合用于模式匹配。
+样例类非常适合用于模式匹配。
```scala mdoc
abstract class Notification
@@ -58,7 +58,7 @@ case class VoiceRecording(contactName: String, link: String) extends Notificatio
```
-`Notification` 是一个虚基类，它有三个具体的子类`Email`, `SMS`和`VoiceRecording`，我们可以在这些案例类(Case Class)上像这样使用模式匹配：
+`Notification` 是一个虚基类，它有三个具体的子类`Email`, `SMS`和`VoiceRecording`，我们可以在这些样例类(Case Class)上像这样使用模式匹配：
```
def showNotification(notification: Notification): String = {
@@ -80,7 +80,7 @@ println(showNotification(someVoiceRecording)) // you received a Voice Recording
```
`showNotification`函数接受一个抽象类`Notification`对象作为输入参数，然后匹配其具体类型。（也就是判断它是一个`Email`，`SMS`，还是`VoiceRecording`）。在`case Email(sender, title, _)`中，对象的`sender`和`title`属性在返回值中被使用，而`body`属性则被忽略，故使用`_`代替。
-## 模式守卫（Pattern gaurds）
+## 模式守卫（Pattern guards）
为了让匹配更加具体，可以使用模式守卫，也就是在模式后面加上`if `。
```
@@ -147,5 +147,5 @@ def findPlaceToSit(piece: Furniture): String = piece match {
## 备注
-Scala的模式匹配语句对于使用[案例类（case classes）](case-classes.html)表示的类型非常有用，同时也可以利用[提取器对象（extractor objects）](extractor-objects.html)中的`unapply`方法来定义非案例类对象的匹配。
+Scala的模式匹配语句对于使用[样例类（case classes）](case-classes.html)表示的类型非常有用，同时也可以利用[提取器对象（extractor objects）](extractor-objects.html)中的`unapply`方法来定义非样例类对象的匹配。
diff --git a/_zh-cn/tour/tour-of-scala.md b/_zh-cn/tour/tour-of-scala.md
index df7288f109..78b70dd115 100644
--- a/_zh-cn/tour/tour-of-scala.md
+++ b/_zh-cn/tour/tour-of-scala.md
@@ -13,7 +13,7 @@ next-page: basics
## 欢迎来到Scala之旅
本次 Scala 之旅教程包含了对于大多数 Scala 特性的简单介绍。主要针对 Scala 这门语言的初学者。
-这是个简化的教程，如果希望得到完整的话，可以考虑购买[书籍](/books.html)或者参考[其他资源](/learn.html)。
+这是个简化的教程，如果希望得到完整的话，可以考虑购买[书籍](/books.html)或者参考[其他资源](/online-courses.html)。
## Scala是什么？
Scala是一门现代的多范式语言，志在以简洁、优雅及类型安全的方式来表达常用的编程模型。它平滑地集成了面向对象和函数式语言的特性。
diff --git a/_zh-cn/tour/unified-types.md b/_zh-cn/tour/unified-types.md
index b3d9055168..904684e4dc 100644
--- a/_zh-cn/tour/unified-types.md
+++ b/_zh-cn/tour/unified-types.md
@@ -59,7 +59,7 @@ true
```scala mdoc
val x: Long = 987654321
-val y: Float = x // 9.8765434E8 (note that some precision is lost in this case)
+val y: Float = x.toFloat // 9.8765434E8 (note that some precision is lost in this case)
val face: Char = '☺'
val number: Int = face // 9786
@@ -69,7 +69,7 @@ val number: Int = face // 9786
```
val x: Long = 987654321
-val y: Float = x // 9.8765434E8
+val y: Float = x.toFloat // 9.8765434E8
val z: Long = y // Does not conform
```
diff --git a/_zh-cn/tutorials/scala-for-java-programmers.md b/_zh-cn/tutorials/scala-for-java-programmers.md
index 9ee8838b4d..a3327a1963 100644
--- a/_zh-cn/tutorials/scala-for-java-programmers.md
+++ b/_zh-cn/tutorials/scala-for-java-programmers.md
@@ -18,7 +18,7 @@ Lightsing 译
这里用标准的 *Hello world* 程序作为第一个例子。虽然它很无趣，但让我们可以用少量语言特质来演示 Scala 工具。程序如下：
object HelloWorld {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
println("Hello, world!")
}
}
@@ -60,7 +60,7 @@ Java 的标准函数库定义了一些有用的工具类，如 `Date` 跟 `DateF
import java.text.DateFormat._
object FrenchDate {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val now = new Date
val df = getDateInstance(LONG, Locale.FRANCE)
println(df format now)
@@ -114,7 +114,7 @@ Scala 中的函数也是对象，所以将函数当做对象传递、把它们
def timeFlies() {
println("time flies like an arrow...")
}
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
oncePerSecond(timeFlies)
}
}
@@ -129,7 +129,7 @@ Scala 中的函数也是对象，所以将函数当做对象传递、把它们
def oncePerSecond(callback: () => Unit) {
while (true) { callback(); Thread sleep 1000 }
}
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
oncePerSecond(() =>
println("time flies like an arrow..."))
}
@@ -157,7 +157,7 @@ Scala 中的函数也是对象，所以将函数当做对象传递、把它们
函数 `re`、`im` 有个小问题，为了调用函数，我们必须在函数名称后面加上一对空括号，如这个例子：
object ComplexNumbers {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val c = new Complex(1.2, 3.4)
println("imaginary part: " + c.im())
}
@@ -261,7 +261,7 @@ Java 中我们会将这个树用一个抽象父类表示，然后每种节点跟
我们还没有探讨完模式匹配的全部功能，不过为了让这份文件保持简短，先就此打住。我们还是希望能看到这两个函数在真正的示例如何作用。因此让我们写一个简单的 `main` 函数，对表达式 `(x+x)+(7+y)` 做一些操作：先在环境 `{ x -> 5, y -> 7 }` 下计算结果，然后在对 `x` 接着对 `y` 取导数。
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y")))
val env: Environment = { case "x" => 5 case "y" => 7 }
println("Expression: " + exp)
@@ -308,7 +308,7 @@ Java 中我们会将这个树用一个抽象父类表示，然后每种节点跟
def year = y
def month = m
def day = d
- override def toString(): String = year + "-" + month + "-" + day
+ override def toString(): String = s"$year-$month-$day"
这边要注意的是声明在类名称跟参数之后的 `extends Ord`。这个语法声明了 `Date` 继承 `Ord` 特质。
@@ -361,7 +361,7 @@ Scala 借由可定义泛型类 (跟函数) 来解决这问题。让我们借由
为了使用 `Reference` 类型，我们必须指定 `T`，也就是这容器所包容的元素类型。举例来说，创造并使用该容器来容纳整数，我们可以这样写：
object IntegerReference {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val cell = new Reference[Int]
cell.set(13)
println("Reference contains the half of " + (cell.get * 2))
diff --git a/_zh-tw/tutorials/scala-for-java-programmers.md b/_zh-tw/tutorials/scala-for-java-programmers.md
index 290ee22ac3..333744ecea 100755
--- a/_zh-tw/tutorials/scala-for-java-programmers.md
+++ b/_zh-tw/tutorials/scala-for-java-programmers.md
@@ -18,7 +18,7 @@ Chikei Lee 譯
這邊用標準的 *Hello world* 程式作為第一個例子。雖然它很無趣，可是這讓我們在僅用少量語言特性下演示 Scala 工具。程式如下：
object HelloWorld {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
println("Hello, world!")
}
}
@@ -60,7 +60,7 @@ Java 的標準函式庫定義了一些有用的工具類別，如 `Date` 跟 `Da
import java.text.DateFormat._
object FrenchDate {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val now = new Date
val df = getDateInstance(LONG, Locale.FRANCE)
println(df format now)
@@ -114,7 +114,7 @@ Scala 是一個純粹的物件導向語言，這句話的意思是說，*所有
def timeFlies() {
println("time flies like an arrow...")
}
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
oncePerSecond(timeFlies)
}
}
@@ -129,7 +129,7 @@ Scala 是一個純粹的物件導向語言，這句話的意思是說，*所有
def oncePerSecond(callback: () => Unit) {
while (true) { callback(); Thread sleep 1000 }
}
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
oncePerSecond(() =>
println("time flies like an arrow..."))
}
@@ -157,7 +157,7 @@ Scala 是一個純粹的物件導向語言，這句話的意思是說，*所有
函式 `re`、`im` 有個小問題，為了呼叫函式，我們必須在函式名稱後面加上一對空括號，如這個例子：
object ComplexNumbers {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val c = new Complex(1.2, 3.4)
println("imaginary part: " + c.im())
}
@@ -261,7 +261,7 @@ Java 中我們會將這個樹用一個抽象母類別表示，然後每種節點
我們還沒有探討完模式匹配的全部功能，不過為了讓這份文件保持簡短，先就此打住。我們還是希望能看到這兩個函式在真正的範例如何作用。因此讓我們寫一個簡單的 `main` 函數，對表示式 `(x+x)+(7+y)` 做一些操作：先在環境 `{ x -> 5, y -> 7 }` 下計算結果，然後在對 `x` 接著對 `y` 取導數。
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val exp: Tree = Sum(Sum(Var("x"),Var("x")),Sum(Const(7),Var("y")))
val env: Environment = { case "x" => 5 case "y" => 7 }
println("Expression: " + exp)
@@ -308,7 +308,7 @@ Java 中我們會將這個樹用一個抽象母類別表示，然後每種節點
def year = y
def month = m
def day = d
- override def toString(): String = year + "-" + month + "-" + day
+ override def toString(): String = s"$year-$month-$day"
這邊要注意的是宣告在類別名稱跟參數之後的 `extends Ord`。這個語法宣告了 `Date` 繼承 `Ord` 特質。
@@ -361,7 +361,7 @@ Scala 藉由可定義泛型類別 (跟函式) 來解決這問題。讓我們藉
為了使用 `Reference` 類型，我們必須指定 `T`，也就是這容器所包容的元素型別。舉例來說，創造並使用該容器來容納整數，我們可以這樣寫：
object IntegerReference {
- def main(args: Array[String]) {
+ def main(args: Array[String]): Unit = {
val cell = new Reference[Int]
cell.set(13)
println("Reference contains the half of " + (cell.get * 2))
diff --git a/api/all.md b/api/all.md
index bed90bad2e..6f049664b7 100644
--- a/api/all.md
+++ b/api/all.md
@@ -2,22 +2,28 @@
layout: singlepage-overview
title: Scala API Docs
includeTOC: true
+redirect_from:
+ - /reference.html
---
## Latest releases
-* Scala 2.13.5
- * [Library API](https://www.scala-lang.org/api/2.13.5/)
- * [Compiler API](https://www.scala-lang.org/api/2.13.5/scala-compiler/scala/)
- * [Reflection API](https://www.scala-lang.org/api/2.13.5/scala-reflect/scala/reflect/)
-* Scala 2.12.13
- * [Library API](https://www.scala-lang.org/api/2.12.13/)
- * [Compiler API](https://www.scala-lang.org/api/2.12.13/scala-compiler/scala/)
- * [Reflection API](https://www.scala-lang.org/api/2.12.13/scala-reflect/scala/reflect/)
+* Scala {{site.scala-3-version}}
+ * [Library API](https://www.scala-lang.org/api/{{site.scala-3-version}}/)
+* Scala 3.3.6 LTS
+ * [Library API](https://www.scala-lang.org/api/3.3.6/)
+* Scala 2.13.16
+ * [Library API](https://www.scala-lang.org/api/2.13.16/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.16/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.16/scala-reflect/scala/reflect/)
+* Scala 2.12.20
+ * [Library API](https://www.scala-lang.org/api/2.12.20/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.20/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.20/scala-reflect/scala/reflect/)
* Scala Modules
- * [XML API](https://www.scala-lang.org/api/2.12.13/scala-xml/scala/xml/)
- * [Parser Combinators API](https://www.scala-lang.org/api/2.12.13/scala-parser-combinators/scala/util/parsing/)
- * [Swing API](https://www.scala-lang.org/api/2.12.13/scala-swing/scala/swing/)
+ * [XML API](https://www.scala-lang.org/api/2.12.20/scala-xml/scala/xml/)
+ * [Parser Combinators API](https://www.scala-lang.org/api/2.12.20/scala-parser-combinators/scala/util/parsing/)
+ * [Swing API](https://www.scala-lang.org/api/2.12.20/scala-swing/scala/swing/)
* Scala 2.11.12
* [Library API](https://www.scala-lang.org/api/2.11.12/)
* [Compiler API](https://www.scala-lang.org/api/2.11.12/scala-compiler/)
@@ -58,6 +64,102 @@ https://scala-ci.typesafe.com/artifactory/scala-integration/org/scala-lang/
## Previous releases
+* Scala 3.7.0
+ * [Library API](https://www.scala-lang.org/api/3.7.0/)
+* Scala 3.6.4
+ * [Library API](https://www.scala-lang.org/api/3.6.4/)
+* Scala 3.6.3
+ * [Library API](https://www.scala-lang.org/api/3.6.3/)
+* Scala 3.6.2
+ * [Library API](https://www.scala-lang.org/api/3.6.2/)
+* Scala 3.5.2
+ * [Library API](https://www.scala-lang.org/api/3.5.2/)
+* Scala 3.5.1
+ * [Library API](https://www.scala-lang.org/api/3.5.1/)
+* Scala 3.5.0
+ * [Library API](https://www.scala-lang.org/api/3.5.0/)
+* Scala 3.4.3
+ * [Library API](https://www.scala-lang.org/api/3.4.3/)
+* Scala 3.4.2
+ * [Library API](https://www.scala-lang.org/api/3.4.2/)
+* Scala 3.4.1
+ * [Library API](https://www.scala-lang.org/api/3.4.1/)
+* Scala 3.4.0
+ * [Library API](https://www.scala-lang.org/api/3.4.0/)
+* Scala 3.3.5 LTS
+ * [Library API](https://www.scala-lang.org/api/3.3.5/)
+* Scala 3.3.4 LTS
+ * [Library API](https://www.scala-lang.org/api/3.3.4/)
+* Scala 3.3.3 LTS
+ * [Library API](https://www.scala-lang.org/api/3.3.3/)
+* Scala 3.3.1 LTS
+ * [Library API](https://www.scala-lang.org/api/3.3.1/)
+* Scala 3.3.0 LTS
+ * [Library API](https://www.scala-lang.org/api/3.3.0/)
+* Scala 3.2.2
+ * [Library API](https://www.scala-lang.org/api/3.2.2/)
+* Scala 3.2.1
+ * [Library API](https://www.scala-lang.org/api/3.2.1/)
+* Scala 3.2.0
+ * [Library API](https://www.scala-lang.org/api/3.2.0/)
+* Scala 3.1.3
+ * [Library API](https://www.scala-lang.org/api/3.1.3/)
+* Scala 3.1.2
+ * [Library API](https://www.scala-lang.org/api/3.1.2/)
+* Scala 3.1.1
+ * [Library API](https://www.scala-lang.org/api/3.1.1/)
+* Scala 3.1.0
+ * [Library API](https://www.scala-lang.org/api/3.1.0/)
+* Scala 3.0.2
+ * [Library API](https://www.scala-lang.org/api/3.0.2/)
+* Scala 3.0.1
+ * [Library API](https://www.scala-lang.org/api/3.0.1/)
+* Scala 3.0.0
+ * [Library API](https://www.scala-lang.org/api/3.0.0/)
+* Scala 2.13.15
+ * [Library API](https://www.scala-lang.org/api/2.13.15/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.15/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.15/scala-reflect/scala/reflect/)
+* Scala 2.13.14
+ * [Library API](https://www.scala-lang.org/api/2.13.14/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.14/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.14/scala-reflect/scala/reflect/)
+* Scala 2.13.13
+ * [Library API](https://www.scala-lang.org/api/2.13.13/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.13/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.13/scala-reflect/scala/reflect/)
+* Scala 2.13.12
+ * [Library API](https://www.scala-lang.org/api/2.13.12/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.12/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.12/scala-reflect/scala/reflect/)
+* Scala 2.13.11
+ * [Library API](https://www.scala-lang.org/api/2.13.11/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.11/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.11/scala-reflect/scala/reflect/)
+* Scala 2.13.10
+ * [Library API](https://www.scala-lang.org/api/2.13.10/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.10/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.10/scala-reflect/scala/reflect/)
+* Scala 2.13.9
+ * [Library API](https://www.scala-lang.org/api/2.13.9/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.9/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.9/scala-reflect/scala/reflect/)
+* Scala 2.13.8
+ * [Library API](https://www.scala-lang.org/api/2.13.8/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.8/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.8/scala-reflect/scala/reflect/)
+* Scala 2.13.7
+ * [Library API](https://www.scala-lang.org/api/2.13.7/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.7/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.7/scala-reflect/scala/reflect/)
+* Scala 2.13.6
+ * [Library API](https://www.scala-lang.org/api/2.13.6/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.6/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.6/scala-reflect/scala/reflect/)
+* Scala 2.13.5
+ * [Library API](https://www.scala-lang.org/api/2.13.5/)
+ * [Compiler API](https://www.scala-lang.org/api/2.13.5/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.13.5/scala-reflect/scala/reflect/)
* Scala 2.13.4
* [Library API](https://www.scala-lang.org/api/2.13.4/)
* [Compiler API](https://www.scala-lang.org/api/2.13.4/scala-compiler/scala/)
@@ -78,6 +180,58 @@ https://scala-ci.typesafe.com/artifactory/scala-integration/org/scala-lang/
* [Library API](https://www.scala-lang.org/api/2.13.0/)
* [Compiler API](https://www.scala-lang.org/api/2.13.0/scala-compiler/scala/)
* [Reflection API](https://www.scala-lang.org/api/2.13.0/scala-reflect/scala/reflect/)
+* Scala 2.12.19
+ * [Library API](https://www.scala-lang.org/api/2.12.19/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.19/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.19/scala-reflect/scala/reflect/)
+ * Scala Modules
+ * [XML API](https://www.scala-lang.org/api/2.12.19/scala-xml/scala/xml/)
+ * [Parser Combinators API](https://www.scala-lang.org/api/2.12.19/scala-parser-combinators/scala/util/parsing/)
+ * [Swing API](https://www.scala-lang.org/api/2.12.19/scala-swing/scala/swing/)
+* Scala 2.12.18
+ * [Library API](https://www.scala-lang.org/api/2.12.18/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.18/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.18/scala-reflect/scala/reflect/)
+ * Scala Modules
+ * [XML API](https://www.scala-lang.org/api/2.12.18/scala-xml/scala/xml/)
+ * [Parser Combinators API](https://www.scala-lang.org/api/2.12.18/scala-parser-combinators/scala/util/parsing/)
+ * [Swing API](https://www.scala-lang.org/api/2.12.18/scala-swing/scala/swing/)
+* Scala 2.12.17
+ * [Library API](https://www.scala-lang.org/api/2.12.17/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.17/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.17/scala-reflect/scala/reflect/)
+ * Scala Modules
+ * [XML API](https://www.scala-lang.org/api/2.12.17/scala-xml/scala/xml/)
+ * [Parser Combinators API](https://www.scala-lang.org/api/2.12.17/scala-parser-combinators/scala/util/parsing/)
+ * [Swing API](https://www.scala-lang.org/api/2.12.17/scala-swing/scala/swing/)
+* Scala 2.12.16
+ * [Library API](https://www.scala-lang.org/api/2.12.16/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.16/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.16/scala-reflect/scala/reflect/)
+ * Scala Modules
+ * [XML API](https://www.scala-lang.org/api/2.12.16/scala-xml/scala/xml/)
+ * [Parser Combinators API](https://www.scala-lang.org/api/2.12.16/scala-parser-combinators/scala/util/parsing/)
+ * [Swing API](https://www.scala-lang.org/api/2.12.16/scala-swing/scala/swing/)
+* Scala 2.12.15
+ * [Library API](https://www.scala-lang.org/api/2.12.15/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.15/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.15/scala-reflect/scala/reflect/)
+ * Scala Modules
+ * [XML API](https://www.scala-lang.org/api/2.12.15/scala-xml/scala/xml/)
+ * [Parser Combinators API](https://www.scala-lang.org/api/2.12.15/scala-parser-combinators/scala/util/parsing/)
+ * [Swing API](https://www.scala-lang.org/api/2.12.15/scala-swing/scala/swing/)
+* Scala 2.12.14
+ * [Library API](https://www.scala-lang.org/api/2.12.14/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.14/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.14/scala-reflect/scala/reflect/)
+ * Scala Modules
+ * [XML API](https://www.scala-lang.org/api/2.12.14/scala-xml/scala/xml/)
+ * [Parser Combinators API](https://www.scala-lang.org/api/2.12.14/scala-parser-combinators/scala/util/parsing/)
+ * [Swing API](https://www.scala-lang.org/api/2.12.14/scala-swing/scala/swing/)
+* Scala 2.12.13
+ * [Library API](https://www.scala-lang.org/api/2.12.13/)
+ * [Compiler API](https://www.scala-lang.org/api/2.12.13/scala-compiler/scala/)
+ * [Reflection API](https://www.scala-lang.org/api/2.12.13/scala-reflect/scala/reflect/)
* Scala 2.12.12
* [Library API](https://www.scala-lang.org/api/2.12.12/)
* [Compiler API](https://www.scala-lang.org/api/2.12.12/scala-compiler/scala/)
diff --git a/books.md b/books.md
index 0bdfff3358..3e33b863d5 100644
--- a/books.md
+++ b/books.md
@@ -1,12 +1,12 @@
---
title: Books
-layout: inner-page
+layout: basic-index
redirect_from:
- /documentation/books.html
---
-More and more books being published about Scala every year. Here, you can find
-just a small selection of the many available titles.
+More books about Scala are published every year. This is
+only a selection of the available titles.
diff --git a/contribute.md b/contribute.md index 471ab85a3c..3ac938c17b 100644 --- a/contribute.md +++ b/contribute.md @@ -1,9 +1,9 @@ --- -layout: contribute -title: Contribute +layout: singlepage-overview +title: Why Contribute to docs.scala-lang.org? --- -###### Heather Miller +###### A note from Heather Miller ## A Place to Build Documentation Together @@ -21,175 +21,6 @@ If we want Scala to be accessible to more programmers, clear, easy-to-find docum If you're interested in contributing to the Scala project in general, I argue that one of the most meaningful ways that you can, is to help us improve this transfer of information- let's make it easier and faster for people to _get_ core concepts, and to answer their own questions so they can progress to _Scala-proficient_ quickly. Each line that you contribute has the potential to affect the entire Scala community as a whole-- current, and future. -## About docs.scala-lang.org +## How Can I Contribute? -### Content - -Currently, the _types_ of documentation supported in this repository are: - -- **Guides/Overviews**: Definitive guides/overviews of specific language features. Often long, detailed documents, often produced by members of the Scala team. An example is the excellent [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview. -- **Tutorials**: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly. -- **Cheatsheets**: Quick reference of Scala syntax and behaviors. - -### Implementation - -This documentation repository is open-source, it lives in [github repository](https://github.com/scala/docs.scala-lang), and is always contribution-ready. - -It's statically generated from [Markdown](https://en.wikipedia.org/wiki/Markdown) source using [Jekyll](https://github.com/mojombo/jekyll), and hosted on [GitHub Pages](https://pages.github.com/). This workflow was chosen so as to make it as easy as possible for core committers and the community alike to produce HTML documentation, and as easy as possible to publish it in a central location. - -The markdown syntax being used supports [Maruku](https://github.com/bhollis/maruku) extensions, and has automatic syntax highlighting, without the need for any tags. - -Additionally [mdoc](https://github.com/scalameta/mdoc) is used during pull requests to validate Scala code blocks. To use this feature you must use the backtick notation as documented by mdoc. Note that only validation is done. The output files from mdoc are not used in the building of the tutorial. Use `mdoc` or `mdoc:fail` for your code blocks. - -## Submitting Docs - -For one to contribute a document, one must simply -[fork](https://help.github.com/articles/fork-a-repo/) the -[repo](https://github.com/scala/docs.scala-lang), write their article in -[Markdown](https://daringfireball.net/projects/markdown/syntax) (example below), and submit a pull request. That's it. Likely after some edits and discussion, your document will be made live on [docs.scala-lang.org](https://docs.scala-lang.org). - - --- - layout: overview - title: My Awesome Title - --- - - ## An h2 Header in Markdown - - And a paragraph, with a [link](https://www.scala-lang.org). - - One can contribute code by indenting it 4 spaces, or in-line by putting backticks around it like so, `def foo` - -Everything else is automatically generated for you; tables of contents, and most index pages. And of course, the styling is already taken care of for you. - -### Criteria for Docs to be Accepted - -The goal of this documentation repository is to be tighter and more organized than other community-driven documentation platforms, like wikis. As such, any document pulled in for inclusion on [https://docs.scala-lang.org](https://docs.scala-lang.org) must: - -- **"fit in"** to the repository ( _i.e.,_ it should not be a complete duplicate of another article), -- **be polished** it must be thorough, complete, correct, organized, and "article-like" (personal programming notes don't quite fit.) -- **be maintained** if the document might require revisions from time to time, it should come with an owner - -If you have something you're thinking about contributing, or that you're thinking about writing in order to contribute-- we'd love to consider it! Please don't hesitate to use GitHub issues and pull requests and the [scala/contributors room](https://gitter.im/scala/contributors) on Gitter for any questions, concerns, clarifications, etc. - -## Document Templates - - - -### Guides/Overviews - -A guide or an overview that can be logically placed on **one** page must be placed in the directory `overviews/RELEVANT-CATEGORY/_posts` with the file name in the format `YYYY-MM-dd-title-separated-by-dashes.md`, and header: - - --- - layout: overview - title: YOUR TITLE - --- - -The rest of the document should, of course, be written in [Markdown](https://en.wikipedia.org/wiki/Markdown). - -At the moment, `RELEVANT-CATEGORY` corresponds to only a single category, "core," because we are currently focusing on building up documentation of core libraries. However, expect more categories here in the future. - -If your document consists of **multiple** pages, like the [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview, an ordering must be specified, by numbering documents in their logical order with `num`, and a name must be assigned to the collection of pages using `partof`. For example, the following header might be used for a document in the collections overview: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 10 - --- - -A **single** document in the collection must contain a tag in the header, `outof`, that indicates the total number of documents in the large overview. Putting it on the last page in the overview is often best: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 15 - outof: 15 - --- - -Index pages, such as [https://docs.scala-lang.org/overviews/index.html](https://docs.scala-lang.org/overviews/index.html) are automatically generated, assuming documents are properly placed under the correct `RELEVANT-CATEGORY`. So, simply drop your document into the correct folder, and you're done. - -### Tutorials - -At the moment, a tutorial that can be logically placed on **one** page must be placed in the directory `tutorials/` with the file name in the format `title-separated-by-dashes.md`. For the moment, single-page tutorials use the same layout as single-page overviews: - - --- - layout: overview - title: YOUR TITLE - --- - -If you have a **multiple-page** tutorial, like in the case of multiple-page overviews, you must both specify an ordering for your document, and a name must be assigned to the collection of tutorial pages. For example, the following header is used for the [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html) series of tutorial articles: - - --- - layout: inner-page-no-masthead - title: YOUR TITLE - - tutorial: scala-tour - num: 4 - --- - -At the moment, only indexes for multiple-page tutorials are automatically generated. - -### Cheatsheets - -For now, cheatsheets are assumed to be in the form of tables. To contribute a cheatsheet, one must simply produce their cheatsheet as a Markdown table, with the following header: - - --- - layout: cheatsheet - title: YOUR TITLE - by: YOUR NAME - about: SOME TEXT ABOUT THE CHEAT SHEET. - --- - -### Code blocks - -The site build process uses [mdoc](https://scalameta.org/mdoc/) to typecheck -code snippets in markdown. This is a great way to ensure the code snippets that -you're including typecheck and are valid. Here are a few quick types to get -started. - -To get started, you can simply add `mdoc` behind `scala` when you are creating a -code block. The `mdoc` modifier here will make sure that `mdoc` runs the code -snippet and ensures that it's valid. - - ```scala mdoc - val a = 1 - ``` -If you have a snippet that you expect to fail, you can also account for this by -using `mdoc:fail` for a compile error `mdoc:crash` for a runtime-error. - - ```scala mdoc:fail - val b: String = 3 // won't compile - ``` -Keep in mind that a single file is all compiled as a single unit, so you can't -redefine a variable that was defined above in another code snippet. _However_ -there are a couple ways to get around this. Firstly, you can use the `mdoc:nest` -modifier with will wrap the snippet in a `scala.Predef.locally{...}`. This will -essentially "hide" the snippet from the others. Another way around this is to -use the `mdoc:reset` modifier, which _resets_ and forgets about everything up -above. Here is an example using the various modifiers. - - ```scala mdoc - import java.time.Instant - - def now() = Instant.now() - object Foo {} - ``` - - ```scala mdoc:nest - case class Foo(a: Int) // conflicts with Foo above, but it's nested so it's fine - ``` - - ```scala mdoc - val a = s"The time is ${now()}" // still have access to the now method from above - ``` - ```scala mdoc:reset - case class Foo(a: String) // forget the previous Foo's and start fresh - ``` - ```scala mdoc - val myFoo = Foo("hi") // now we only have access to the last Foo - ``` +Please read: [Add New Guides/Tutorials](https://docs.scala-lang.org/contribute/add-guides.html) diff --git a/docker-compose.yml b/docker-compose.yml index 26f6d5b398..75b1876399 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,9 +1,9 @@ -version: '2' - services: jekyll: - image: bretfisher/jekyll-serve - volumes: - - .:/site + user: "${UID}:${GID}" + build: . + command: sh -c "chown $UID / && bundle exec jekyll serve --incremental --host=0.0.0.0 " ports: - - '8080:4000' + - '4000:4000' + volumes: + - .:/srv/jekyll diff --git a/docker-compose_build-only.yml b/docker-compose_build-only.yml new file mode 100644 index 0000000000..615d0425a7 --- /dev/null +++ b/docker-compose_build-only.yml @@ -0,0 +1,9 @@ +version: '2' + +services: + jekyll: + user: "${UID}:${GID}" + build: . + command: sh -c "chown $UID / && bundle exec jekyll build" + volumes: + - .:/srv/jekyll diff --git a/guides.md b/guides.md deleted file mode 100644 index 98700b64b3..0000000000 --- a/guides.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-no-masthead -title: Guides and Overviews -languages: [ja, zh-cn, es, ru] - ---- diff --git a/index.md b/index.md index d244e435e7..22cbc790cc 100644 --- a/index.md +++ b/index.md @@ -1,74 +1,55 @@ --- -layout: documentation -languages: [ja, zh-cn, ru] -title: Documentation +layout: landing-page +languages: [ja, zh-cn, ru, uk] + +title: Learn Scala namespace: root discourse: true partof: documentation more-resources-label: More Resources +redirect_from: + - /scala3/ + - /scala3/index.html -scala3-sections: - - title: "First steps" - links: - - title: "New in Scala 3" - description: "An overview of the exciting new features in Scala 3." - icon: "fa fa-star" - link: /scala3/new-in-scala3.html - - title: "Getting Started" - description: "Install Scala 3 on your computer and start writing some Scala code!" - icon: "fa fa-rocket" - link: /scala3/getting-started.html - - title: "Scala 3 Book" - description: "An online book introducing the main language features." - icon: "fa fa-book" - link: /scala3/book/introduction.html - - title: "More detailed information" - links: - - title: "Migration Guide" - description: "A guide to help you migrate from Scala 2 to Scala 3." - icon: "fa fa-suitcase" - link: https://scalacenter.github.io/scala-3-migration-guide/ - - title: "Guides" - description: "Detailed guides about particular aspects of the language." - icon: "fa fa-map" - link: /scala3/guides.html - - title: "API" - description: "API documentation for every version of Scala 3." - icon: "fa fa-file-text" - link: https://dotty.epfl.ch/api/index.html - - title: "Language Reference" - description: "The Scala 3 language reference." - icon: "fa fa-book" - link: https://dotty.epfl.ch/docs/reference/overview.html - -scala2-sections: +sections: - title: "First Steps..." links: - title: "Getting Started" description: "Install Scala on your computer and start writing some Scala code!" icon: "fa fa-rocket" - link: /getting-started.html + link: /getting-started/install-scala.html - title: "Tour of Scala" description: "Bite-sized introductions to core language features." icon: "fa fa-flag" link: /tour/tour-of-scala.html - - title: "Scala Book" - description: "An online book introducing the main language features." - icon: "fa fa-book" - link: /overviews/scala-book/introduction.html - more-resources: - - title: Online Courses, Exercises, & Blogs - url: /learn.html + - title: "Scala 3 Book" + description: "Learn Scala by reading a series of short lessons." + icon: "fa fa-book-open" + link: /scala3/book/introduction.html + - title: "Scala Toolkit" + description: "Sending HTTP requests, writing files, running processes, parsing JSON..." + icon: "fa fa-toolbox" + link: /toolkit/introduction.html + - title: Online Courses + description: "MOOCs to learn Scala, for beginners and experienced programmers." + icon: "fa fa-cloud" + link: /online-courses.html - title: Books - url: /books.html + description: "Printed and digital books about Scala." + icon: "fa fa-book" + link: /books.html + - title: Tutorials + description: "Take you by the hand through a series of steps to create Scala applications." + icon: "fa fa-tasks" + link: /tutorials.html - title: "Returning Users" links: - title: "API" description: "API documentation for every version of Scala." - icon: "fa fa-file-text" + icon: "fa fa-file-alt" link: /api/all.html - - title: "Overviews" + - title: "Guides & Overviews" description: "In-depth documentation covering many of Scala's features." icon: "fa fa-database" link: /overviews/index.html @@ -84,19 +65,46 @@ scala2-sections: description: "Answers to frequently-asked questions about Scala." icon: "fa fa-question-circle" link: /tutorials/FAQ/index.html - - title: "Language Spec" - description: "Scala's formal language specification." + - title: "Language Spec v2.x" + description: "Scala 2's formal language specification." icon: "fa fa-book" link: https://scala-lang.org/files/archive/spec/2.13/ + - title: "Language Spec v3.x" + description: "Scala 3's formal language specification." + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/3.4/ + - title: "Scala 3 Language Reference" + description: "The Scala 3 language reference." + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference + + - title: "Explore Scala 3" + links: + - title: "Migration Guide" + description: "A guide to help you move from Scala 2 to Scala 3." + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "New in Scala 3" + description: "An overview of the exciting new features in Scala 3." + icon: "fa fa-star" + link: /scala3/new-in-scala3.html + - title: "All new Scaladoc for Scala 3" + description: "Highlights of new features for Scaladoc" + icon: "fa fa-star" + link: /scala3/scaladoc.html + - title: "Talks" + description: "Talks about Scala 3 that can be watched online" + icon: "fa fa-play-circle" + link: /scala3/talks.html - title: "Scala Evolution" links: - - title: "SIPs" - description: "The Scala Improvement Process. Language & compiler evolution." + - title: "Scala Improvement Process" + description: "Description of the process for evolving the language, and list of all the Scala Improvement Proposals (SIPs)." icon: "fa fa-cogs" link: /sips/index.html - - title: "SPP" - description: "The Scala Platform Process. Community-driven library evolution." - icon: "fa fa-users" - link: https://platform.scala-lang.org + - title: "Become a Scala OSS Contributor" + description: "From start to finish: discover how you can help Scala's open-source ecosystem" + icon: "fa fa-code-branch" + link: /contribute/ --- diff --git a/learn.md b/learn.md deleted file mode 100644 index 62ff6b5fbb..0000000000 --- a/learn.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Online Resources -layout: inner-page-no-masthead -redirect_from: - - /documentation/books.html ---- - -## Try Scala in your browser! - -There are a handful of websites where you can interactively run Scala code in your browser! Have a look at [ScalaFiddle](https://scalafiddle.io/) and [Scastie](https://scastie.org/). - -## Online courses from the Scala Center - -The following courses are available for free. They teach you the main features of the Scala language and introduce you -to functional programming. They are published either on [Coursera](https://www.coursera.org) or [edX](https://www.edx.org). - - * [Functional Programming in Scala Specialization](https://www.coursera.org/specializations/scala). - The Specialization provides a hands-on introduction to functional programming using Scala. You can access the courses - material and exercises by either signing up for the specialization or auditing the courses individually. The - specialization has the following courses. - * [Functional Programming Principles in Scala](https://www.coursera.org/learn/progfun1), - * [Functional Program Design in Scala](https://www.coursera.org/learn/progfun2), - * [Parallel programming](https://www.coursera.org/learn/parprog1), - * [Big Data Analysis with Scala and Spark](https://www.coursera.org/learn/scala-spark-big-data), - * [Functional Programming in Scala Capstone](https://www.coursera.org/learn/scala-capstone), - * [Programming Reactive Systems](https://www.coursera.org/learn/scala-reactive) (also available on [edX](https://www.edx.org/course/programming-reactive-systems)). - -Note : On Coursera and edX, there is a paid version available. The only difference with the free version is that -the paid version delivers a certificate of completion. Learn more about -[Coursera certificates](https://learner.coursera.help/hc/en-us/articles/209819053-Get-a-Course-Certificate) or -[edX certificates](https://support.edx.org/hc/en-us/categories/115002269627-Certificates). - -## Scala Exercises - -[Scala Exercises](https://www.scala-exercises.org/) is a series of lessons and exercises created by [47 Degrees](https://www.47deg.com/). It's a great way to get a brief introduction to Scala while testing your knowledge along the way. - -[Tour of Scala](https://tourofscala.com) gives you an introduction to Scala, step by step, from begineer to expert. - -## Dr. Mark C Lewis's lectures from Trinity University - -[Dr. Mark C Lewis](https://www.cs.trinity.edu/~mlewis/) from Trinity University, San Antonio, TX, teaches programming courses using the Scala language. Course videos are available in YouTube for free. Some of the courses below. - - * [Introduction to Programming and Problem Solving Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt9MIJ9DV4ps-_trOzWtphYO) - * [Object-Orientation, Abstraction, and Data Structures Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt8JLumqKj-3BlHmEXPIfR42) - -You can visit his [YouTube channel](https://www.youtube.com/user/DrMarkCLewis/featured) for more videos. - -## Scala Learning Community -[Scala Learning Community on Discord](http://sca.la/learning-community), a growing online community connecting learners with online resources to learn Scala together. - -## allaboutscala -[allaboutscala](https://allaboutscala.com/) provides detailed tutorials for beginners. - -## ScalaCourses -[Independent Courseware](https://getscala.com), online self-study or instructor-led Scala and Play courses for a fee. - -## DevInsideYou -[DevInsideYou](https://youtube.com/devinsideyou) is a YouTube channel with hundreds of hours of free Scala content. - -## Visual Scala Reference -[Visual Scala Reference](https://superruzafa.github.com/visual-scala-reference/), a guide to visually learn about Scala concepts and functions. diff --git a/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md b/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md index 38a941ac28..c4722a5bb3 100644 --- a/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md +++ b/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md @@ -1,5 +1,5 @@ --- -layout: inner-page-no-masthead +layout: singlepage-overview title: "Functional Programming Principles in Scala: Impressions and Statistics" --- ###### By Heather Miller and Martin Odersky @@ -33,7 +33,7 @@ Those of you reading this who were enrolled in the course might recall that, sev For example, as mentioned above, a success rate of 20% is quite high for an online course. One might suspect that it was because the course was very easy, but in our previous experience that's not the case. In fact, the online course is a direct adaptation of a 2nd year course that was given at EPFL for a number of years and that has a reputation of being rather tough. If anything, the material in the online course was a bit more compressed than in the previous on-campus class. -In particular, 57% of all respondents to the survey rated the overall course as being 3, "Just Right", on a scale from 1 to 5, with 1 being "Too Easy" and 5 being "Too Difficult. With regard to programming assignments specifically, 40% rated the assignments as being 3, "Just Right", while 46% rated assignments as being 4 "Challenging". +In particular, 57% of all respondents to the survey rated the overall course as being 3, "Just Right", on a scale from 1 to 5, with 1 being "Too Easy" and 5 being "Too Difficult". With regard to programming assignments specifically, 40% rated the assignments as being 3, "Just Right", while 46% rated assignments as being 4 "Challenging". Another point which might be particularly interesting is the fact that the difficulty rating appears to be independent of whether people have a background in Computer Science/Software Engineering or not. One might guess that this could mean that learning Scala is not much more difficult without a formal educational background in Computer Science. @@ -43,7 +43,7 @@ While a majority of the students in the course have degrees in Computer Science/
-However, we were still interested to see how the formal education of participants influenced their assessment of the perceived difficulty. It turns out that, of those who have or have pursued university degrees— Bachelors or Masters degrees, there was almost no difference in perceived difficulty. The only marked differences appeared to the far left and the far right of the spectrum.
+However, we were still interested to see how the formal education of participants influenced their assessment of the perceived difficulty. It turns out that, of those who have or have pursued university degrees— Bachelors or Master's degrees, there was almost no difference in perceived difficulty. The only marked differences appeared to the far left and the far right of the spectrum.
Scale: 1 - Too Easy, 2 - Easy, 3 - Just Right, 4 - Challenging, 5 - Too Difficult
@@ -79,7 +79,7 @@ We also collected numbers about the used programming tools. First, we were inter
-The collected numbers are markedly different. In no small part this is due to the fact that the [Scala IDE for Eclipse](https://scala-ide.org) introduced a new [worksheet](https://github.com/scala-ide/scala-worksheet/wiki/Getting-Started) component used throughout the lectures.
+The collected numbers are markedly different. In no small part this is due to the fact that the Scala IDE for Eclipse introduced a new [worksheet](https://github.com/scala-ide/scala-worksheet/wiki/Getting-Started) component used throughout the lectures.
We'd like to close with some fun, and partially surprising, information on the demographics of those who took the course and completed our survey. Here is a world map showing the number of participants per country— darker colors indicate a larger number of students per-country:
@@ -93,7 +93,7 @@ Here's that graph again, relating that population of students who enrolled in th
## Get the data and explore it with Scala!
-For those of you who want to have a little bit of fun with the numbers, we've made all of the data publicly available, and we've made a small Scala project out of it. In particular, we put the code that we used to produce the above plots on [github (progfun-stats)](https://www.github.com/heathermiller/progfun-stats).
+For those of you who want to have a little bit of fun with the numbers, we've made all the data publicly available, and we've made a small Scala project out of it. In particular, we put the code that we used to produce the above plots on [github (progfun-stats)](https://www.github.com/heathermiller/progfun-stats).
For those of you who have taken the course and are itching for some fun additional exercises in functional programming, one of our suggestions is to tinker with and extend this project! You'll find the code examples for generating most of these plots available in this post, in the above repository.
diff --git a/online-courses.md b/online-courses.md
new file mode 100644
index 0000000000..6b65a5115f
--- /dev/null
+++ b/online-courses.md
@@ -0,0 +1,43 @@
+---
+title: Online Courses
+layout: online-courses
+redirect_from:
+ - /documentation/books.html
+ - /learn
+---
+
+## Other Online Resources
+
+### Tour of Scala
+
+[Tour of Scala](https://tourofscala.com) is an interactive website that introduces the basics of Scala programming through a series of hands-on lessons.
+Each lesson provides code examples and exercises that compiles and runs directly in the browser, making it a quick and accessible way to get started with Scala.
+
+In the [Scala Learning Discord](http://sca.la/learning-community), you can connect with fellow Scala learners and engage with the Tour of Scala community.
+
+### Scala Exercises
+
+[Scala Exercises](https://www.scala-exercises.org/) is a series of lessons and exercises created by [47 Degrees](https://www.47deg.com/).
+It's a great way to get a brief introduction to Scala while testing your knowledge along the way.
+It also covers some libraries of the ecosystem such as cats, doobie, scalacheck etc.
+
+### DevInsideYou
+
+[DevInsideYou](https://youtube.com/devinsideyou) is a YouTube channel with hundreds of hours of free Scala content.
+
+### Visual Scala Reference
+
+[Visual Scala Reference](https://superruzafa.github.io/visual-scala-reference/) is a visual guide to the most common methods of the Scala collections.
+
+### allaboutscala
+
+[allaboutscala](https://allaboutscala.com/) provides detailed tutorials for beginners.
+
+### Dr. Mark C Lewis's lectures from Trinity University
+
+[Dr. Mark C Lewis](https://www.cs.trinity.edu/~mlewis/) from Trinity University, San Antonio, TX, teaches programming courses using the Scala language. Course videos are available in YouTube for free. Some courses below.
+
+- [Introduction to Programming and Problem Solving Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt9MIJ9DV4ps-_trOzWtphYO)
+- [Object-Orientation, Abstraction, and Data Structures Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt8JLumqKj-3BlHmEXPIfR42)
+
+You can visit his [YouTube channel](https://www.youtube.com/user/DrMarkCLewis/featured) for more videos.
diff --git a/reference.md b/reference.md
deleted file mode 100644
index e7a837825e..0000000000
--- a/reference.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-layout: inner-page-no-masthead
-sitemap: false
-permalink: /reference.html
-redirect_to: /api/all.html
----
diff --git a/resources/css/style.scss b/resources/css/style.scss
index 57b121deba..5f30379a90 100755
--- a/resources/css/style.scss
+++ b/resources/css/style.scss
@@ -55,13 +55,16 @@
@import 'layout/training-events';
@import 'layout/blog';
@import 'layout/download';
+@import 'layout/online-courses';
@import 'layout/content-contributors'; // COMPONENTS
+@import 'layout/details-summary';
//------------------------------------------------
//------------------------------------------------
@import 'components/buttons';
@import 'components/call-to-action';
@import 'components/slider';
@import 'components/heading-line';
+@import 'components/alt-details';
@import 'components/card';
@import 'components/calendar';
@import 'components/tooltip';
@@ -72,3 +75,4 @@
@import 'components/search';
@import 'components/dropdown';
@import 'components/wip-notice';
+@import 'components/heading-anchor.scss';
diff --git a/resources/images/getting-started/IntelliJScala.png b/resources/images/getting-started/IntelliJScala.png
new file mode 100644
index 0000000000..c567da38df
Binary files /dev/null and b/resources/images/getting-started/IntelliJScala.png differ
diff --git a/resources/images/getting-started/VSCodeMetals.png b/resources/images/getting-started/VSCodeMetals.png
new file mode 100644
index 0000000000..bdc5090726
Binary files /dev/null and b/resources/images/getting-started/VSCodeMetals.png differ
diff --git a/resources/images/learning-path.png b/resources/images/learning-path.png
new file mode 100644
index 0000000000..43e9d09631
Binary files /dev/null and b/resources/images/learning-path.png differ
diff --git a/resources/images/online-courses/coursera.png b/resources/images/online-courses/coursera.png
new file mode 100644
index 0000000000..a329139aa0
Binary files /dev/null and b/resources/images/online-courses/coursera.png differ
diff --git a/resources/images/online-courses/extension-school.png b/resources/images/online-courses/extension-school.png
new file mode 100644
index 0000000000..94da532d8c
Binary files /dev/null and b/resources/images/online-courses/extension-school.png differ
diff --git a/resources/images/online-courses/rock-the-jvm.png b/resources/images/online-courses/rock-the-jvm.png
new file mode 100644
index 0000000000..86b6512c0b
Binary files /dev/null and b/resources/images/online-courses/rock-the-jvm.png differ
diff --git a/resources/images/scala3-book/intellij-worksheet.png b/resources/images/scala3-book/intellij-worksheet.png
new file mode 100644
index 0000000000..e33fd3566e
Binary files /dev/null and b/resources/images/scala3-book/intellij-worksheet.png differ
diff --git a/resources/images/scala3-book/metals-worksheet.png b/resources/images/scala3-book/metals-worksheet.png
new file mode 100644
index 0000000000..da950e19d6
Binary files /dev/null and b/resources/images/scala3-book/metals-worksheet.png differ
diff --git a/resources/images/scala3-migration/compatibility-213-to-3.svg b/resources/images/scala3-migration/compatibility-213-to-3.svg
new file mode 100644
index 0000000000..32d5687bce
--- /dev/null
+++ b/resources/images/scala3-migration/compatibility-213-to-3.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/resources/images/scala3-migration/compatibility-3-to-213.svg b/resources/images/scala3-migration/compatibility-3-to-213.svg
new file mode 100644
index 0000000000..88fdc8606e
--- /dev/null
+++ b/resources/images/scala3-migration/compatibility-3-to-213.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/resources/images/scala3-migration/compatibility-sandwich.svg b/resources/images/scala3-migration/compatibility-sandwich.svg
new file mode 100644
index 0000000000..32942b7d03
--- /dev/null
+++ b/resources/images/scala3-migration/compatibility-sandwich.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/resources/images/scala3-migration/tutorial-macro-cross-building.svg b/resources/images/scala3-migration/tutorial-macro-cross-building.svg
new file mode 100644
index 0000000000..03b75bd497
--- /dev/null
+++ b/resources/images/scala3-migration/tutorial-macro-cross-building.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/resources/images/scala3-migration/tutorial-macro-mixing.svg b/resources/images/scala3-migration/tutorial-macro-mixing.svg
new file mode 100644
index 0000000000..18023dffb9
--- /dev/null
+++ b/resources/images/scala3-migration/tutorial-macro-mixing.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png b/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png
new file mode 100644
index 0000000000..65179260c2
Binary files /dev/null and b/resources/images/scala3/explicit-nulls/explicit-nulls-type-hierarchy.png differ
diff --git a/resources/images/scala3/scaladoc/assert-compilation-errors.gif b/resources/images/scala3/scaladoc/assert-compilation-errors.gif
new file mode 100644
index 0000000000..c13cf0ef49
Binary files /dev/null and b/resources/images/scala3/scaladoc/assert-compilation-errors.gif differ
diff --git a/resources/images/scala3/scaladoc/blog-post.png b/resources/images/scala3/scaladoc/blog-post.png
new file mode 100644
index 0000000000..f8db0483d2
Binary files /dev/null and b/resources/images/scala3/scaladoc/blog-post.png differ
diff --git a/resources/images/scala3/scaladoc/documentation-snippet.png b/resources/images/scala3/scaladoc/documentation-snippet.png
new file mode 100644
index 0000000000..31ce6087fc
Binary files /dev/null and b/resources/images/scala3/scaladoc/documentation-snippet.png differ
diff --git a/resources/images/scala3/scaladoc/documentation-snippet2.png b/resources/images/scala3/scaladoc/documentation-snippet2.png
new file mode 100644
index 0000000000..d60acb4634
Binary files /dev/null and b/resources/images/scala3/scaladoc/documentation-snippet2.png differ
diff --git a/resources/images/scala3/scaladoc/hiding-code.gif b/resources/images/scala3/scaladoc/hiding-code.gif
new file mode 100644
index 0000000000..f3e52712be
Binary files /dev/null and b/resources/images/scala3/scaladoc/hiding-code.gif differ
diff --git a/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif b/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif
new file mode 100644
index 0000000000..1cc25b5683
Binary files /dev/null and b/resources/images/scala3/scaladoc/inkuire-1.0.0-M2_js_flatMap.gif differ
diff --git a/resources/images/scala3/scaladoc/logo.svg b/resources/images/scala3/scaladoc/logo.svg
new file mode 100644
index 0000000000..1774519639
--- /dev/null
+++ b/resources/images/scala3/scaladoc/logo.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/resources/images/scala3/scaladoc/nightly.gif b/resources/images/scala3/scaladoc/nightly.gif
new file mode 100644
index 0000000000..d6e764a032
Binary files /dev/null and b/resources/images/scala3/scaladoc/nightly.gif differ
diff --git a/resources/images/scala3/scaladoc/snippet-compiler1.gif b/resources/images/scala3/scaladoc/snippet-compiler1.gif
new file mode 100644
index 0000000000..d3573e395f
Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler1.gif differ
diff --git a/resources/images/scala3/scaladoc/snippet-compiler2.gif b/resources/images/scala3/scaladoc/snippet-compiler2.gif
new file mode 100644
index 0000000000..2074c74ebb
Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler2.gif differ
diff --git a/resources/images/scala3/scaladoc/snippet-compiler3.png b/resources/images/scala3/scaladoc/snippet-compiler3.png
new file mode 100644
index 0000000000..3982bc782f
Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler3.png differ
diff --git a/resources/images/scala3/scaladoc/snippet-compiler4.png b/resources/images/scala3/scaladoc/snippet-compiler4.png
new file mode 100644
index 0000000000..5bb2afaa15
Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-compiler4.png differ
diff --git a/resources/images/scala3/scaladoc/snippet-includes.png b/resources/images/scala3/scaladoc/snippet-includes.png
new file mode 100644
index 0000000000..cd9db043d6
Binary files /dev/null and b/resources/images/scala3/scaladoc/snippet-includes.png differ
diff --git a/resources/images/scala3/scaladoc/social-links.png b/resources/images/scala3/scaladoc/social-links.png
new file mode 100644
index 0000000000..4c20568c7c
Binary files /dev/null and b/resources/images/scala3/scaladoc/social-links.png differ
diff --git a/resources/images/scala3/scaladoc/static-site.png b/resources/images/scala3/scaladoc/static-site.png
new file mode 100644
index 0000000000..9f27f058b2
Binary files /dev/null and b/resources/images/scala3/scaladoc/static-site.png differ
diff --git a/resources/images/scalacenter-courses/testimonial000.jpg b/resources/images/scalacenter-courses/testimonial000.jpg
new file mode 100644
index 0000000000..50c03ecf3a
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial000.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial001.jpg b/resources/images/scalacenter-courses/testimonial001.jpg
new file mode 100644
index 0000000000..b3e1cc7584
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial001.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial002.jpg b/resources/images/scalacenter-courses/testimonial002.jpg
new file mode 100644
index 0000000000..62174d4319
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial002.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial003.jpg b/resources/images/scalacenter-courses/testimonial003.jpg
new file mode 100644
index 0000000000..3a594aabdd
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial003.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial004.jpg b/resources/images/scalacenter-courses/testimonial004.jpg
new file mode 100644
index 0000000000..2750557f9c
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial004.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial005.jpg b/resources/images/scalacenter-courses/testimonial005.jpg
new file mode 100644
index 0000000000..d6104cd9dd
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial005.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial006.jpg b/resources/images/scalacenter-courses/testimonial006.jpg
new file mode 100644
index 0000000000..acdcdc7b34
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial006.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial007.jpg b/resources/images/scalacenter-courses/testimonial007.jpg
new file mode 100644
index 0000000000..46a1e90193
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial007.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial008.jpg b/resources/images/scalacenter-courses/testimonial008.jpg
new file mode 100644
index 0000000000..bde859d696
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial008.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial009.jpg b/resources/images/scalacenter-courses/testimonial009.jpg
new file mode 100644
index 0000000000..e036db8133
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial009.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial010.jpg b/resources/images/scalacenter-courses/testimonial010.jpg
new file mode 100644
index 0000000000..b329771b8f
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial010.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial011.jpg b/resources/images/scalacenter-courses/testimonial011.jpg
new file mode 100644
index 0000000000..ec49e73333
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial011.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial012.jpg b/resources/images/scalacenter-courses/testimonial012.jpg
new file mode 100644
index 0000000000..639c5a0617
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial012.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial013.jpg b/resources/images/scalacenter-courses/testimonial013.jpg
new file mode 100644
index 0000000000..4dd0e747f7
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial013.jpg differ
diff --git a/resources/images/scalacenter-courses/testimonial014.jpg b/resources/images/scalacenter-courses/testimonial014.jpg
new file mode 100644
index 0000000000..4fe1763fe4
Binary files /dev/null and b/resources/images/scalacenter-courses/testimonial014.jpg differ
diff --git a/resources/images/sip/process-chart.png b/resources/images/sip/process-chart.png
new file mode 100644
index 0000000000..c647901efd
Binary files /dev/null and b/resources/images/sip/process-chart.png differ
diff --git a/resources/images/sip/sip-stages.png b/resources/images/sip/sip-stages.png
new file mode 100644
index 0000000000..981f8b8937
Binary files /dev/null and b/resources/images/sip/sip-stages.png differ
diff --git a/resources/img/books/FPiS_93x116.jpg b/resources/img/books/FPiS_93x116.jpg
new file mode 100644
index 0000000000..dac8f9d915
Binary files /dev/null and b/resources/img/books/FPiS_93x116.jpg differ
diff --git a/resources/img/books/FPiS_93x116.png b/resources/img/books/FPiS_93x116.png
deleted file mode 100644
index c942bd6bab..0000000000
Binary files a/resources/img/books/FPiS_93x116.png and /dev/null differ
diff --git a/resources/img/books/ProgrammingInScala.gif b/resources/img/books/ProgrammingInScala.gif
deleted file mode 100644
index 06452435db..0000000000
Binary files a/resources/img/books/ProgrammingInScala.gif and /dev/null differ
diff --git a/resources/img/books/ProgrammingInScala.png b/resources/img/books/ProgrammingInScala.png
new file mode 100644
index 0000000000..bfc20e4d56
Binary files /dev/null and b/resources/img/books/ProgrammingInScala.png differ
diff --git a/resources/img/books/ProgrammingScala-final-border.gif b/resources/img/books/ProgrammingScala-final-border.gif
index 69f7cb8cad..a8646acbdd 100644
Binary files a/resources/img/books/ProgrammingScala-final-border.gif and b/resources/img/books/ProgrammingScala-final-border.gif differ
diff --git a/resources/img/books/ProgrammingScala.jpg b/resources/img/books/ProgrammingScala.jpg
index 07db7ec46a..232d0abff8 100644
Binary files a/resources/img/books/ProgrammingScala.jpg and b/resources/img/books/ProgrammingScala.jpg differ
diff --git a/resources/img/books/get-programming-book.png b/resources/img/books/get-programming-book.png
new file mode 100644
index 0000000000..93dd8c60e5
Binary files /dev/null and b/resources/img/books/get-programming-book.png differ
diff --git a/resources/img/books/scala_for_the_impatient.jpg b/resources/img/books/scala_for_the_impatient.jpg
new file mode 100644
index 0000000000..c1dab91058
Binary files /dev/null and b/resources/img/books/scala_for_the_impatient.jpg differ
diff --git a/resources/img/books/scala_for_the_impatient.png b/resources/img/books/scala_for_the_impatient.png
deleted file mode 100644
index 012367038d..0000000000
Binary files a/resources/img/books/scala_for_the_impatient.png and /dev/null differ
diff --git a/resources/img/foundreq.jpg b/resources/img/foundreq.jpg
new file mode 100644
index 0000000000..47c56099da
Binary files /dev/null and b/resources/img/foundreq.jpg differ
diff --git a/resources/img/foundreq_record.jpg b/resources/img/foundreq_record.jpg
new file mode 100644
index 0000000000..c54f105ecc
Binary files /dev/null and b/resources/img/foundreq_record.jpg differ
diff --git a/resources/img/frontpage/discord-logo.png b/resources/img/frontpage/discord-logo.png
new file mode 100644
index 0000000000..c055c19c6c
Binary files /dev/null and b/resources/img/frontpage/discord-logo.png differ
diff --git a/resources/img/frontpage/gitter-logo.png b/resources/img/frontpage/gitter-logo.png
deleted file mode 100644
index ff91a264d4..0000000000
Binary files a/resources/img/frontpage/gitter-logo.png and /dev/null differ
diff --git a/resources/img/implicits-circe.jpg b/resources/img/implicits-circe.jpg
new file mode 100644
index 0000000000..840898eb81
Binary files /dev/null and b/resources/img/implicits-circe.jpg differ
diff --git a/resources/img/implicits-compact.jpg b/resources/img/implicits-compact.jpg
new file mode 100644
index 0000000000..900820c8ca
Binary files /dev/null and b/resources/img/implicits-compact.jpg differ
diff --git a/resources/js/functions.js b/resources/js/functions.js
index e52eddd5cf..686a38f47b 100644
--- a/resources/js/functions.js
+++ b/resources/js/functions.js
@@ -65,14 +65,11 @@ $(document).ready(function() {
// Highlight
$(document).ready(function() {
hljs.configure({
- languages: ["scala", "bash"]
+ languages: ["scala", "bash"],
+ noHighlightRe: /^hljs-skip$/i
})
- hljs.initHighlighting();
-});
-
-// Show Blog
-$(".hide").click(function() {
- $(".new-on-the-blog").hide();
+ hljs.registerLanguage("scala", highlightDotty);
+ hljs.highlightAll();
});
// Documentation menu dropdown toggle
@@ -147,7 +144,7 @@ $(document).ready(function() {
old.empty();
// if there are no translations, hide language dropdown box
- if (items.length <= 1) {
+ if (items.length === 0) {
$("#dd").hide();
}
});
@@ -280,6 +277,11 @@ $(document).ready(function() {
autoId: true,
numerate: false
});
+ const target = $('#sidebar-toc .active');
+ if (target.length) {
+ const marginTop = $('#sidebar-toc .type-chapter').length ? 15 : 10;
+ $('#sidebar-toc').animate({scrollTop: target.position().top - marginTop}, 200);
+ };
}
});
@@ -382,25 +384,151 @@ $(document).ready(function() {
}
});
+// Browser Storage Support (https://stackoverflow.com/a/41462752/2538602)
+function storageAvailable(type) {
+ try {
+ var storage = window[type],
+ x = '__storage_test__';
+ storage.setItem(x, x);
+ storage.removeItem(x);
+ return true;
+ }
+ catch (e) {
+ return false;
+ }
+}
+
+// Store preference for Scala 2 vs 3
+$(document).ready(function() {
+
+ const Storage = (namespace) => {
+ return ({
+ getPreference(key, defaultValue) {
+ const res = localStorage.getItem(`${namespace}.${key}`);
+ return res === null ? defaultValue : res;
+ },
+ setPreference(key, value, onChange) {
+ const old = this.getPreference(key, null);
+ if (old !== value) { // activate effect only if value changed.
+ localStorage.setItem(`${namespace}.${key}`, value);
+ onChange(old);
+ }
+ }
+ });
+ };
+
+ function activateTab(tabs, value) {
+ // check the code tab corresponding to the preferred value
+ tabs.find('input[data-target=' + value + ']').prop("checked", true);
+ }
+
+ /** Links all tabs created in Liquid templates with class ".tabs-$namespace"
+ * on the page together, such that
+ * changing a tab to some value will activate all other tab sections to
+ * also change to that value.
+ * Also records a preference for the tab in localStorage, so
+ * that when the page is refreshed, the same tab will be selected.
+ * On page load, selects the tab corresponding to stored value.
+ */
+ function setupTabs(tabs, namespace, defaultValue, storage) {
+ const preferredValue = storage.getPreference(namespace, defaultValue);
+
+ activateTab(tabs, preferredValue)
+
+ // setup listeners to record new preferred Scala version.
+ tabs.find('input').on('change', function() {
+ // if checked then set the preferred version, and activate the other tabs on page.
+ if ($(this).is(':checked')) {
+ const parent = $(this).parent();
+ const newValue = $(this).data('target');
+
+ storage.setPreference(namespace, newValue, _ => {
+ // when we set a new scalaVersion, find scalaVersionTabs except current one
+ // and activate those tabs.
+ activateTab(tabs.not(parent), newValue);
+ });
+
+ }
+
+ });
+ }
+
+ function setupAlertCancel(alert, storage) {
+ const messageId = alert.data('message_id');
+ let onHide = () => {};
+ if (messageId) {
+ const key = `alert.${messageId}`;
+ const isHidden = storage.getPreference(key, 'show') === 'hidden';
+ if (isHidden) {
+ alert.hide();
+ }
+ onHide = () => storage.setPreference(key, 'hidden', _ => {});
+ }
+
+
+ alert.find('.hide').click(function() {
+ alert.hide(), onHide();
+ });
+ }
+
+ function setupAllTabs(storage) {
+ var scalaVersionTabs = $(".tabsection.tabs-scala-version");
+ if (scalaVersionTabs.length) {
+ setupTabs(scalaVersionTabs, "scalaVersion", "scala-3", storage);
+ }
+ var buildToolTabs = $(".tabsection.tabs-build-tool");
+ if (buildToolTabs.length) {
+ setupTabs(buildToolTabs, "buildTool", "scala-cli", storage);
+ }
+ }
+
+ function setupAllAlertCancels(storage) {
+ var alertBanners = $(".new-on-the-blog.alert-warning");
+ if (alertBanners.length) {
+ setupAlertCancel(alertBanners, storage);
+ }
+ }
+
+ if (storageAvailable('localStorage')) {
+ const PreferenceStorage = Storage('org.scala-lang.docs.preferences');
+ setupAllTabs(PreferenceStorage);
+ setupAllAlertCancels(PreferenceStorage);
+ }
+
+});
+
// OS detection
function getOS() {
var osname = "linux";
if (navigator.appVersion.indexOf("Win") != -1) osname = "windows";
- if (navigator.appVersion.indexOf("Mac") != -1) osname = "osx";
+ if (navigator.appVersion.indexOf("Mac") != -1) osname = "macos";
if (navigator.appVersion.indexOf("Linux") != -1) osname = "linux";
if (navigator.appVersion.indexOf("X11") != -1) osname = "unix";
return osname;
}
-$(document).ready(function() {
- if ($(".main-download").length) {
+$(document).ready(function () {
+ // for each code snippet area, find the copy button,
+ // and add a click listener that will copy text from
+ // the code area to the clipboard
+ $(".code-snippet-area").each(function () {
+ var area = this;
+ $(area).children(".code-snippet-buttons").children("button.copy-button").click(function () {
+ var code = $(area).children(".code-snippet-display").children("code").text();
+ window.navigator.clipboard.writeText(code);
+ });
+ });
+});
+
+$(document).ready(function () {
+ // click the get-started tab corresponding to the users OS.
+ var platformOSOptions = $(".tabsection.platform-os-options");
+ if (platformOSOptions.length) {
var os = getOS();
- var intelliJlink = $("#intellij-" + os).text();
- var sbtLink = $("#sbt-" + os).text();
- var stepOneContent = $("#stepOne-" + os).html()
- $("#download-intellij-link").attr("href", intelliJlink);
- $("#download-sbt-link").attr("href", sbtLink);
- $("#download-step-one").html(stepOneContent);
+ if (os === 'unix') {
+ os = 'linux';
+ }
+ platformOSOptions.find('input[data-target=' + os + ']').prop("checked", true);
}
});
@@ -444,7 +572,7 @@ $('#filter-glossary-terms').focus();
// Loop through the comment list
$(".glossary .toc-context > ul li").each(function(){
// If the name of the glossary term does not contain the text phrase fade it out
- if (jQuery(this).find("h4").text().search(new RegExp(filter, "i")) < 0) {
+ if (jQuery(this).find("h3").text().search(new RegExp(filter, "i")) < 0) {
$(this).fadeOut();
// Show the list item if the phrase matches and increase the count by 1
@@ -467,18 +595,18 @@ $('#filter-glossary-terms').focus();
//Footer scroll to top button
-$(document).ready(function(){
- $(window).scroll(function(){
- if ($(this).scrollTop() > 100) {
- $('#scroll-to-top-btn').fadeIn();
- } else {
- $('#scroll-to-top-btn').fadeOut();
- }
- });
- $('#scroll-to-top-btn').click(function(){
- $("html, body").animate({ scrollTop: 0 }, 600);
- return false;
- });
+$(document).ready(function(){
+ $(window).scroll(function(){
+ if ($(this).scrollTop() > 100) {
+ $('#scroll-to-top-btn').fadeIn();
+ } else {
+ $('#scroll-to-top-btn').fadeOut();
+ }
+ });
+ $('#scroll-to-top-btn').click(function(){
+ $("html, body").animate({ scrollTop: 0 }, 600);
+ return false;
+ });
});
//Contributors widget
@@ -490,7 +618,7 @@ $(document).ready(function () {
* - some files aren't prefixed with underscore, see rootFiles
* - some files are placed in _overviews but rendered to its folder, see overviewsFolders
*/
-
+
let rootFiles = ['getting-started', 'learn', 'glossary'];
let overviewsFolders = ['FAQ', 'cheatsheets', 'collections', 'compiler-options',
'core', 'jdk-compatibility', 'macros', 'parallel-collections',
@@ -565,3 +693,15 @@ $(document).ready(function () {
$('#contributors').html(contributorsHtml);
});
});
+
+$(document).ready(function() {
+ const icon = ''
+ const anchor = ''
+
+ $('.content-primary.documentation').find('h1, h2, h3, h4, h5, h6').each(function() {
+ const id = $(this).attr('id');
+ if (id) {
+ $(this).append($(anchor).attr('href', '#' + id).html(icon));
+ }
+ });
+});
diff --git a/resources/js/hljs-scala3.js b/resources/js/hljs-scala3.js
new file mode 100644
index 0000000000..e0be3758b8
--- /dev/null
+++ b/resources/js/hljs-scala3.js
@@ -0,0 +1,504 @@
+function highlightDotty(hljs) {
+
+ // identifiers
+ const capitalizedId = /\b[A-Z][$\w]*\b/
+ const alphaId = /[a-zA-Z$_][$\w]*/
+ const op1 = /[^\s\w\d,;"'()[\]{}=:]/
+ const op2 = /[^\s\w\d,;"'()[\]{}]/
+ const compound = `[a-zA-Z$][a-zA-Z0-9$]*_${op2.source}` // e.g. value_=
+ const id = new RegExp(`(${compound}|${alphaId.source}|${op2.source}{2,}|${op1.source}+|\`.+?\`)`)
+
+ // numbers
+ const hexDigit = '[a-fA-F0-9]'
+ const hexNumber = `0[xX](${hexDigit})+(_(${hexDigit})+)*[lL]?`
+ const wholePart = `(\\d+)(_\\d+)*`
+ const decPoint = `\\.\\d+`
+ const floatingSuffix = `([eE][-+]?\\d+)?[fFdD]?`
+ const intOrFloat = `${decPoint}${floatingSuffix}|\\b${wholePart}([lLfFdD]|(${decPoint})?${floatingSuffix})`
+ const number = new RegExp(`(-?)((\\b(${hexNumber})|${intOrFloat}))`)
+
+ // Regular Keywords
+ // The "soft" keywords (e.g. 'using') are added later where necessary
+ const alwaysKeywords = {
+ $pattern: /(\w+|\?=>|\?{1,3}|=>>|=>|<:|>:|_|#|<-|\.nn)/,
+ keyword:
+ 'abstract case catch class def do else enum export extends final finally for given ' +
+ 'if implicit import lazy match new object package private protected override return ' +
+ 'sealed then throw trait true try type val var while with yield =>> => ?=> <: >: _ ? <- #',
+ literal: 'true false null this super',
+ built_in: '??? asInstanceOf isInstanceOf assert implicitly locally summon valueOf .nn'
+ }
+ const modifiers = 'abstract|final|implicit|override|private|protected|sealed'
+
+ // End of class, enum, etc. header
+ const templateDeclEnd = /(\/[/*]|{|:(?= *\n)|\n(?! *(extends|with|derives)))/
+
+ // all the keywords + soft keywords, separated by spaces
+ function withSoftKeywords(kwd) {
+ return {
+ $pattern: alwaysKeywords.$pattern,
+ keyword: kwd + ' ' + alwaysKeywords.keyword,
+ literal: alwaysKeywords.literal,
+ built_in: alwaysKeywords.built_in
+ }
+ }
+
+ // title inside of a complex token made of several parts, but colored as a type (e.g. class)
+ const TP_TITLE = {
+ className: 'type',
+ begin: id,
+ returnEnd: true,
+ keywords: alwaysKeywords.keyword,
+ literal: alwaysKeywords.literal,
+ built_in: alwaysKeywords.built_in
+ }
+
+ // title inside of a complex token made of several parts (e.g. class)
+ const TITLE = {
+ className: 'title',
+ begin: id,
+ returnEnd: true,
+ keywords: alwaysKeywords.keyword,
+ literal: alwaysKeywords.literal,
+ built_in: alwaysKeywords.built_in
+ }
+
+ // title that goes to the end of a simple token (e.g. val)
+ const TITLE2 = {
+ className: 'title',
+ begin: id,
+ excludeEnd: true,
+ endsWithParent: true
+ }
+
+ const TYPED = {
+ begin: /: (?=[a-zA-Z()?])/,
+ end: /\/\/|\/\*|\n/,
+ endsWithParent: true,
+ returnEnd: true,
+ contains: [
+ {
+ // works better than the usual way of defining keyword,
+ // in this specific situation
+ className: 'keyword',
+ begin: /\?\=>|=>>|[=:][><]|\?/,
+ },
+ {
+ className: 'type',
+ begin: alphaId
+ }
+ ]
+ }
+
+ const PROBABLY_TYPE = {
+ className: 'type',
+ begin: capitalizedId,
+ relevance: 0
+ }
+
+ const NUMBER = {
+ className: 'number',
+ begin: number,
+ relevance: 0,
+ }
+
+ const CHAR = {
+ className: 'string',
+ begin: /\'([^'\\]|\\[\s\S])\'/,
+ relevance: 0,
+ }
+
+ // type parameters within [square brackets]
+ const TPARAMS = {
+ begin: /\[/, end: /\]/,
+ keywords: {
+ $pattern: /<:|>:|[+-?_:]/,
+ keyword: '<: >: : + - ? _'
+ },
+ contains: [
+ hljs.C_BLOCK_COMMENT_MODE,
+ {
+ className: 'type',
+ begin: alphaId
+ },
+ ],
+ relevance: 3
+ }
+
+ // Class or method parameters declaration
+ const PARAMS = {
+ className: 'params',
+ begin: /\(/, end: /\)/,
+ excludeBegin: true,
+ excludeEnd: true,
+ keywords: withSoftKeywords('inline using'),
+ contains: [
+ hljs.C_BLOCK_COMMENT_MODE,
+ hljs.QUOTE_STRING_MODE,
+ PROBABLY_TYPE
+ ]
+ }
+
+ // (using T1, T2, T3)
+ const CTX_PARAMS = {
+ className: 'params',
+ begin: /\(using (?!\w+:)/, end: /\)/,
+ excludeBegin: false,
+ excludeEnd: true,
+ relevance: 5,
+ keywords: withSoftKeywords('using'),
+ contains: [
+ PROBABLY_TYPE
+ ]
+ }
+
+ // String interpolation
+ const SUBST = {
+ className: 'subst',
+ variants: [
+ { begin: /\$[a-zA-Z_]\w*/ },
+ {
+ begin: /\${/, end: /}/,
+ contains: [
+ NUMBER,
+ hljs.QUOTE_STRING_MODE
+ ]
+ }
+ ]
+ }
+
+ // "string" or """string""", with or without interpolation
+ const STRING = {
+ className: 'string',
+ variants: [
+ hljs.QUOTE_STRING_MODE,
+ {
+ begin: '"""', end: '"""',
+ contains: [hljs.BACKSLASH_ESCAPE],
+ relevance: 10
+ },
+ {
+ begin: alphaId.source + '"', end: '"',
+ contains: [hljs.BACKSLASH_ESCAPE, SUBST],
+ illegal: /\n/,
+ relevance: 5
+ },
+ {
+ begin: alphaId.source + '"""', end: '"""',
+ contains: [hljs.BACKSLASH_ESCAPE, SUBST],
+ relevance: 10
+ }
+ ]
+ }
+
+ // Class or method apply
+ const APPLY = {
+ begin: /\(/, end: /\)/,
+ excludeBegin: true, excludeEnd: true,
+ keywords: {
+ $pattern: alwaysKeywords.$pattern,
+ keyword: 'using ' + alwaysKeywords.keyword,
+ literal: alwaysKeywords.literal,
+ built_in: alwaysKeywords.built_in
+ },
+ contains: [
+ STRING,
+ NUMBER,
+ CHAR,
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ PROBABLY_TYPE,
+ ]
+ }
+
+ // @annot(...) or @my.package.annot(...)
+ const ANNOTATION = {
+ className: 'meta',
+ begin: `@${id.source}(\\.${id.source})*`,
+ contains: [
+ APPLY,
+ hljs.C_BLOCK_COMMENT_MODE
+ ]
+ }
+
+ // glob all non-whitespace characters as a "string"
+ const DIRECTIVE_VALUE = {
+ className: 'string',
+ begin: /\S+/,
+ }
+
+ // glob all non-whitespace characters as a "type", so that we can highlight differently to values
+ const DIRECTIVE_KEY = {
+ className: 'type',
+ begin: /\S+/,
+ }
+
+ // directives
+ const USING_DIRECTIVE = hljs.COMMENT('//>', '\n', {
+ contains: [
+ {
+ begin: /using /,
+ end: /\s/,
+ keywords: 'using',
+ contains: [
+ DIRECTIVE_KEY
+ ]
+ },
+ DIRECTIVE_VALUE,
+ ]
+ })
+
+ // Documentation
+ const SCALADOC = hljs.COMMENT('/\\*\\*', '\\*/', {
+ contains: [
+ {
+ className: 'doctag',
+ begin: /@[a-zA-Z]+/
+ },
+ // markdown syntax elements:
+ {
+ className: 'code',
+ variants: [
+ { begin: /```.*\n/, end: /```/ },
+ { begin: /`/, end: /`/ }
+ ],
+ },
+ {
+ className: 'bold',
+ variants: [
+ { begin: /\*\*/, end: /\*\*/ },
+ { begin: /__/, end: /__/ }
+ ],
+ },
+ {
+ className: 'emphasis',
+ variants: [
+ { begin: /\*(?!([\*\s/])|([^\*]*\*[\*/]))/, end: /\*/ },
+ { begin: /_/, end: /_/ }
+ ],
+ },
+ {
+ className: 'bullet', // list item
+ begin: /- (?=\S)/, end: /\s/,
+ },
+ {
+ begin: /\[.*?\]\(/, end: /\)/,
+ contains: [
+ {
+ // mark as "link" only the URL
+ className: 'link',
+ begin: /.*?/,
+ endsWithParent: true
+ }
+ ]
+ }
+ ]
+ })
+
+ // Methods
+ const METHOD = {
+ className: 'function',
+ begin: `((${modifiers}|transparent|inline|infix) +)*def `, end: / =\s|\n/,
+ excludeEnd: true,
+ relevance: 5,
+ keywords: withSoftKeywords('inline infix transparent'),
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ TPARAMS,
+ CTX_PARAMS,
+ PARAMS,
+ TYPED, // prevents the ":" (declared type) to become a title
+ PROBABLY_TYPE,
+ TITLE
+ ]
+ }
+
+ // Variables & Constants
+ const VAL = {
+ beginKeywords: 'val var', end: /[=:;\n/]/,
+ excludeEnd: true,
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ TITLE2
+ ]
+ }
+
+ // Type declarations
+ const TYPEDEF = {
+ className: 'typedef',
+ begin: `((${modifiers}|opaque) +)*type `, end: /[=;\n]| ?[<>]:/,
+ excludeEnd: true,
+ keywords: withSoftKeywords('opaque'),
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ PROBABLY_TYPE,
+ TITLE,
+ ]
+ }
+
+ // Given instances
+ const GIVEN = {
+ begin: `((${modifiers}|transparent|inline) +)*given `, end: / =|[=;\n]/,
+ excludeEnd: true,
+ keywords: withSoftKeywords('inline transparent given using with'),
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ PARAMS,
+ CTX_PARAMS,
+ PROBABLY_TYPE,
+ TITLE
+ ]
+ }
+
+ // Extension methods
+ const EXTENSION = {
+ begin: /extension/, end: /(\n|def)/,
+ returnEnd: true,
+ keywords: 'extension implicit using',
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ CTX_PARAMS,
+ PARAMS,
+ PROBABLY_TYPE
+ ]
+ }
+
+ // 'end' soft keyword
+ const END = {
+ begin: `end(?= (if|while|for|match|try|given|extension|this|val|${id.source})\\n)`, end: /\s/,
+ keywords: 'end'
+ }
+
+ // Classes, traits, enums, etc.
+ const EXTENDS_PARENT = {
+ begin: ' extends ', end: /( with | derives |\/[/*])/,
+ endsWithParent: true,
+ returnEnd: true,
+ keywords: 'extends',
+ contains: [APPLY, PROBABLY_TYPE]
+ }
+ const WITH_MIXIN = {
+ begin: ' with ', end: / derives |\/[/*]/,
+ endsWithParent: true,
+ returnEnd: true,
+ keywords: 'with',
+ contains: [APPLY, PROBABLY_TYPE],
+ relevance: 10
+ }
+ const DERIVES_TYPECLASS = {
+ begin: ' derives ', end: /\n|\/[/*]/,
+ endsWithParent: true,
+ returnEnd: true,
+ keywords: 'derives',
+ contains: [PROBABLY_TYPE],
+ relevance: 10
+ }
+
+ const CLASS = {
+ className: 'class',
+ begin: `((${modifiers}|open|case|transparent) +)*(class|trait|enum|object|package object)`, end: templateDeclEnd,
+ keywords: withSoftKeywords('open transparent'),
+ excludeEnd: true,
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ TPARAMS,
+ CTX_PARAMS,
+ PARAMS,
+ EXTENDS_PARENT,
+ WITH_MIXIN,
+ DERIVES_TYPECLASS,
+ TITLE,
+ PROBABLY_TYPE
+ ]
+ }
+
+ // package declaration with a content
+ const PACKAGE = {
+ className: 'package',
+ begin: /package (?=\w+ *[:{\n])/, end: /[:{\n]/,
+ excludeEnd: true,
+ keywords: alwaysKeywords,
+ contains: [
+ TITLE
+ ]
+ }
+
+ // Case in enum
+ const ENUM_CASE = {
+ begin: /case (?!.*=>)/, end: /\n/,
+ keywords: 'case',
+ excludeEnd: true,
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ PARAMS,
+ EXTENDS_PARENT,
+ WITH_MIXIN,
+ DERIVES_TYPECLASS,
+ TP_TITLE,
+ PROBABLY_TYPE
+ ]
+ }
+
+ // Case in pattern matching
+ const MATCH_CASE = {
+ begin: /case/, end: /=>|\n/,
+ keywords: 'case',
+ excludeEnd: true,
+ contains: [
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ {
+ begin: /[@_]/,
+ keywords: {
+ $pattern: /[@_]/,
+ keyword: '@ _'
+ }
+ },
+ NUMBER,
+ STRING,
+ PROBABLY_TYPE
+ ]
+ }
+
+ // inline someVar[andMaybeTypeParams] match
+ const INLINE_MATCH = {
+ begin: /inline [^\n:]+ match/,
+ keywords: 'inline match'
+ }
+
+ return {
+ name: 'Scala3',
+ aliases: ['scala', 'dotty'],
+ keywords: alwaysKeywords,
+ contains: [
+ NUMBER,
+ CHAR,
+ STRING,
+ USING_DIRECTIVE,
+ SCALADOC,
+ hljs.C_LINE_COMMENT_MODE,
+ hljs.C_BLOCK_COMMENT_MODE,
+ METHOD,
+ VAL,
+ TYPEDEF,
+ PACKAGE,
+ CLASS,
+ GIVEN,
+ EXTENSION,
+ ANNOTATION,
+ ENUM_CASE,
+ MATCH_CASE,
+ INLINE_MATCH,
+ END,
+ APPLY,
+ PROBABLY_TYPE
+ ]
+ }
+}
diff --git a/resources/js/tweetMachine-update.js b/resources/js/tweetMachine-update.js
index a7604d2ba7..0addd1b951 100755
--- a/resources/js/tweetMachine-update.js
+++ b/resources/js/tweetMachine-update.js
@@ -133,11 +133,11 @@
});
// Usernames
text = text.replace(/@[A-Za-z0-9_]+/g, function (u) {
- return '' + u + '';
+ return '' + u + '';
});
// Hashtags
text = text.replace(/#[A-Za-z0-9_\-]+/g, function (u) {
- return '' + u + '';
+ return '' + u + '';
});
return text;
},
@@ -160,7 +160,7 @@
// Set the user screen name
var usernameLink = ""
+ "@"
@@ -170,7 +170,7 @@
// Set the username:
var userLink = ""
+ actualTweet.user.name
@@ -178,7 +178,7 @@
tweetObj.find('.user').html("" + userLink);
// Set the timestamp
- var dateLink = ""
+ tweetMachine.relativeTime(actualTweet.created_at)
@@ -411,4 +411,4 @@
}
});
};
-})(jQuery);
\ No newline at end of file
+})(jQuery);
diff --git a/scala3/contribute-to-docs.md b/scala3/contribute-to-docs.md
index 110a6da806..3196600581 100644
--- a/scala3/contribute-to-docs.md
+++ b/scala3/contribute-to-docs.md
@@ -2,6 +2,7 @@
layout: singlepage-overview
overview-name: "Scala 3 Documentation"
title: Contributing to the Docs
+languages: ["ja", "ru"]
---
## Overview
There are several ongoing efforts to produce high quality documentation for
@@ -16,7 +17,7 @@ We welcome contributions from the community to every aspect of the documentation
### How can I contribute?
-In general, there is many different ways you could help us:
+In general, there are many ways you can help us:
- **Confused about something in any of the docs?** Open an issue.
- **Found something not up-to-date?** Open an issue or create a PR.
@@ -28,40 +29,35 @@ Typically, each of the different documentation projects contain links (and so do
## Scala 3 Book
The [Scala 3 Book][scala3-book] is being written by Alvin Alexander and provides an overview over all the important features of Scala 3. It targets readers, which are new to Scala.
-- [Sources](https://github.com/scala/docs.scala-lang/tree/master/_overviews/scala3-book)
+- [Sources](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-book)
- [Issues](https://github.com/scala/docs.scala-lang/issues)
## Macros Tutorial
The [Macros Tutorial](/scala3/guides/macros) is being written by Nicolas Stucki and contains detailed information about macros in Scala 3 and best-practices.
-- [Sources](https://github.com/scala/docs.scala-lang/tree/master/_overviews/scala3-macros)
+- [Sources](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-macros)
- [Issues](https://github.com/scala/docs.scala-lang/issues)
## Migration Guide
-The [Scala 3 Migration Guide](https://scalacenter.github.io/scala-3-migration-guide/)
-contains an comprehensive overview over compatibility between Scala 2 and Scala 3,
+The [Scala 3 Migration Guide](/scala3/guides/migration/compatibility-intro.html)
+contains a comprehensive overview over compatibility between Scala 2 and Scala 3,
a tour presenting the migration tools, and detailed migration guides.
-- [Contribution Overview](https://scalacenter.github.io/scala-3-migration-guide/docs/contributing.html)
-- [Source](https://github.com/scalacenter/scala-3-migration-guide)
-- [Issues](https://github.com/scalacenter/scala-3-migration-guide/issues)
+- [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-migration)
+- [Issues](https://github.com/scala/docs.scala-lang/issues)
+
+## Scala 3 Contributing Guide
+The [Scala 3 Contributing Guide](/scala3/guides/contribution/contribution-intro.html)
+contains a comprehensive overview over contribution to and internals of the Scala 3 compiler and libraries
+- [Source](https://github.com/scala/docs.scala-lang/tree/main/_overviews/scala3-contribution)
+- [Issues](https://github.com/scala/docs.scala-lang/issues)
## Scala 3 Language Reference
-The [Dotty reference](https://dotty.epfl.ch/docs/reference/overview.html) will evolve into the Scala 3 language, containing a formal presentation and detailed technical information about the various features of the language.
+The [Scala 3 reference]({{ site.scala3ref }}) contains a formal presentation and detailed technical information about the various features of the language.
-- [Sources](https://github.com/lampepfl/dotty/tree/master/docs/docs/reference)
-- [Issues](https://github.com/lampepfl/dotty/issues)
+- [Sources](https://github.com/scala/scala3/tree/main/docs/_docs)
+- [Issues](https://github.com/scala/scala3/issues)
[scala3-book]: {% link _overviews/scala3-book/introduction.md %}
-
-[best-practices]: {% link _overviews/scala3-macros/best-practices.md %}
-[compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %}
-[cross-compilation]: https://scalacenter.github.io/scala-3-migration-guide/docs/macros/migration-tutorial.html#cross-building
-[inline]: {% link _overviews/scala3-macros/tutorial/inline.md %}
-[macros]: {% link _overviews/scala3-macros/tutorial/macros.md %}
-[migration-status]: https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html#macro-libraries
-[quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %}
-[tasty]: {% link _overviews/scala3-macros/tutorial/reflection.md %}
-[reflection-api]: https://dotty.epfl.ch/api/scala/quoted.html
diff --git a/scala3/getting-started.md b/scala3/getting-started.md
deleted file mode 100644
index dfe6c4853a..0000000000
--- a/scala3/getting-started.md
+++ /dev/null
@@ -1,192 +0,0 @@
----
-layout: singlepage-overview
-title: Getting Started with Scala 3
-languages: ["ja"]
----
-
-
-
-## Try Scala without installing anything
-
-To start experimenting with Scala 3 right away, use “Scastie” in your browser.
-_Scastie_ is an online “playground” where you can experiment with Scala examples to see how things work, with access to all Scala compilers and published libraries.
-
-
-
-## Install Scala on your computer
-
-Installing Scala means installing various command-line tools and build tools.
-We recommend using the Scala installer tool "Coursier" that automatically installs all the requirements, but you can still manually install each tool.
-
-
-### Using the Scala Installer (recommended way)
-
-The Scala installer is a tool named [Coursier](https://get-coursier.io/docs/cli-overview), whose main command is named `cs`.
-It ensures that a JVM and standard Scala tools are installed on your system.
-Install it on your system with the following instructions.
-
-
-
diff --git a/scala3/guides/tasty-overview.md b/scala3/guides/tasty-overview.md
index bd3cb9291b..245c822ee5 100644
--- a/scala3/guides/tasty-overview.md
+++ b/scala3/guides/tasty-overview.md
@@ -1,6 +1,10 @@
---
layout: singlepage-overview
title: An Overview of TASTy
+partof: tasty-overview
+languages: ["uk"]
+scala3: true
+versionSpecific: true
---
If you create a Scala 3 source code file named _Hello.scala_:
@@ -35,7 +39,7 @@ This leads to the natural question, “What is tasty?”
TASTy is an acronym that comes from the term, _Typed Abstract Syntax Trees_.
It’s a high-level interchange format for Scala 3, and in this document we’ll refer to it as _Tasty_.
-A first important thing to know is that Tasty files are generated by the `scalac` compiler, and contain _all_ of the information about your source code, including the syntactic structure of your program, and _complete_ information about types, positions, and even documentation. Tasty files contain much more information than _.class_ files, which are generated to run on the JVM. (More on this shortly.)
+A first important thing to know is that Tasty files are generated by the `scalac` compiler, and contain _all_ the information about your source code, including the syntactic structure of your program, and _complete_ information about types, positions, and even documentation. Tasty files contain much more information than _.class_ files, which are generated to run on the JVM. (More on this shortly.)
In Scala 3, the compilation process looks like this:
@@ -52,6 +56,13 @@ $ scalac | Hello.scala | -> | Hello.tasty | -> | Hello.class |
information)
```
+You can view the contents of a _.tasty_ file in a human-readable form by running the compiler on it with the `-print-tasty` flag.
+You can also view the contents decompiled in a form similar to Scala source code using the `-decompile` flag.
+```bash
+$ scalac -print-tasty hello.tasty
+$ scalac -decompile hello.tasty
+```
+
### The issue with _.class_ files
Because of issues such as [type erasure][erasure], _.class_ files are actually an incomplete representation of your code.
@@ -69,7 +80,7 @@ that code is compiled to a _.class_ file that needs to be compatible with the JV
public scala.collection.immutable.List xs();
```
-That `javap` command output shows a Java representation of what’s contained in the class file. Notice in this output that `xs` _is not_ defined as a `List[Int]` any more; it’s essentially represented as a `List[java.lang.Object]`. For your Scala code to work with the JVM, the `Int` type has been erased.
+That `javap` command output shows a Java representation of what’s contained in the class file. Notice in this output that `xs` _is not_ defined as a `List[Int]` anymore; it’s essentially represented as a `List[java.lang.Object]`. For your Scala code to work with the JVM, the `Int` type has been erased.
Later, when you access an element of your `List[Int]` in your Scala code, like this:
@@ -104,7 +115,7 @@ A second key point is to understand that there are differences between the infor
With Scala 3 and Tasty, here’s another important note about compile time:
-- When you write Scala 3 code that uses other Scala 3 libraries, `scalac` doesn’t have to read their _.class_ files any more; it can read their _.tasty_ files, which, as mentioned, are an _exact_ representation of your code. This is important to enable separate compilation and compatiblity between Scala 2.13 and Scala 3.
+- When you write Scala 3 code that uses other Scala 3 libraries, `scalac` doesn’t have to read their _.class_ files anymore; it can read their _.tasty_ files, which, as mentioned, are an _exact_ representation of your code. This is important to enable separate compilation and compatibility between Scala 2.13 and Scala 3.
@@ -117,10 +128,7 @@ As you can imagine, having a complete representation of your code has [many bene
- Tasty makes an excellent foundation for a new generation of [reflection-based macros][macros].
- Optimizers and analyzers can use it for deep code analysis and advanced code generation.
-In a related note, Scala 2.13.5 has a TASTy reader, and the Scala 3 compiler can also read the 2.13 “Pickle” format. The [Compatibility Reference](https://scalacenter.github.io/scala-3-migration-guide/docs/compatibility/classpath.html) in the Scala 3 Migration Guide summarizes the benefits of this cross-compiling capability:
-
-> “You can have a Scala `2.13` module that depends on a Scala `3.0.0-RC1` module, and the latter can even depend on another Scala `2.13` module. >Cross-compatibility will not restrain you from using the exciting new features of Scala 3.0.
-> In short, we have backward and forward compatibility and so migration can happen gradually and in any order.”
+In a related note, Scala 2.13.6 has a TASTy reader, and the Scala 3 compiler can also read the 2.13 “Pickle” format. The [Classpath Compatibility Page][compatibility-ref] in the Scala 3 Migration Guide explains the benefits of this cross-compiling capability.
@@ -130,7 +138,7 @@ In summary, Tasty is a high-level interchange format for Scala 3, and _.tasty_ f
For more details, see these resources:
-- In this [this video](https://www.youtube.com/watch?v=YQmVrUdx8TU), Jamie Thompson of the Scala Center provides a thorough discussion of how Tasty works, and its benefits
+- In [this video](https://www.youtube.com/watch?v=YQmVrUdx8TU), Jamie Thompson of the Scala Center provides a thorough discussion of how Tasty works, and its benefits
- [Binary Compatibility for library authors][binary] discusses binary compatibility, source compatibility, and the JVM execution model
- [Forward Compatibility for the Scala 3 Transition](https://www.scala-lang.org/blog/2020/11/19/scala-3-forward-compat.html) demonstrates techniques for using Scala 2.13 and Scala 3 in the same project
@@ -138,11 +146,17 @@ These articles provide more information about Scala 3 macros:
- [Scala Macro Libraries](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html)
- [Macros: The Plan for Scala 3](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html)
-- [The reference documentation on TASTy Reflect][tasty-reflect]
+- [The reference documentation on Quotes Reflect][quotes-reflect]
- [The reference documentation on macros](macros)
+
+TASTyViz is a tool to inspect TASTy files visually.
+At the time of writing, it is still in the early stages of developement, therefore you can expect missing functionality and less-than-ideal user experience, but it could still prove useful when debugging.
+You can check it out [here](https://github.com/shardulc/tastyviz).
+
[benefits]: https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html
[erasure]: https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure
[binary]: {% link _overviews/tutorials/binary-compatibility-for-library-authors.md %}
-[tasty-reflect]: {{ site.scala3ref }}/metaprogramming/reflection.html
+[compatibility-ref]: {% link _overviews/scala3-migration/compatibility-classpath.md %}
+[quotes-reflect]: {{ site.scala3ref }}/metaprogramming/reflection.html
[macros]: {{ site.scala3ref }}/metaprogramming/macros.html
diff --git a/scala3/index.md b/scala3/index.md
deleted file mode 100644
index c6e7eafbdb..0000000000
--- a/scala3/index.md
+++ /dev/null
@@ -1,44 +0,0 @@
----
-layout: inner-page-documentation
-title: Documentation for Scala 3
-namespace: root
-partof: scala3
-discourse: true
-# Content masthead links
-more-resources-label: More Resources
-sections:
-
- - title: "First Steps"
- links:
- - title: "New in Scala 3"
- description: "An overview of the exciting new features in Scala 3."
- icon: "fa fa-star"
- link: /scala3/new-in-scala3.html
- - title: "Getting Started"
- description: "Install Scala 3 on your computer and start writing some Scala code!"
- icon: "fa fa-rocket"
- link: /scala3/getting-started.html
- - title: "Scala 3 Book"
- description: "An online book introducing the main language features."
- icon: "fa fa-book"
- link: /scala3/book/introduction.html
- - title: "More Detailed Information"
- links:
- - title: "Migration Guide"
- description: "A guide to help you migrate from Scala 2 to Scala 3."
- icon: "fa fa-suitcase"
- link: https://scalacenter.github.io/scala-3-migration-guide/
- - title: "Guides"
- description: "Detailed guides about particular aspects of the language."
- icon: "fa fa-map"
- link: /scala3/guides.html
- - title: "API"
- description: "API documentation for every version of Scala 3."
- icon: "fa fa-file-text"
- link: https://dotty.epfl.ch/api/index.html
- - title: "Language Reference"
- description: "The Scala 3 language reference."
- icon: "fa fa-book"
- link: https://dotty.epfl.ch/docs/reference/overview.html
-
----
diff --git a/scala3/new-in-scala3.md b/scala3/new-in-scala3.md
index 85ae083537..cc3c0add30 100644
--- a/scala3/new-in-scala3.md
+++ b/scala3/new-in-scala3.md
@@ -1,16 +1,17 @@
---
layout: singlepage-overview
title: New in Scala 3
-languages: ["ja"]
+languages: ["ja","zh-cn","uk","ru"]
---
-The upcoming, exciting new version of Scala 3 brings many improvements and
+The exciting new version of Scala 3 brings many improvements and
new features. Here we provide you with a quick overview of the most important
changes. If you want to dig deeper, there are a few references at your disposal:
- The [Scala 3 Book]({% link _overviews/scala3-book/introduction.md %}) targets developers new to the Scala language.
- The [Syntax Summary][syntax-summary] provides you with a formal description of the new syntax.
- The [Language Reference][reference] gives a detailed description of the changes from Scala 2 to Scala 3.
-- The [Migration Guide][migration] provides you with all of the information necessary to move from Scala 2 to Scala 3.
+- The [Migration Guide][migration] provides you with all the information necessary to move from Scala 2 to Scala 3.
+- The [Scala 3 Contributing Guide][contribution] dives deeper into the compiler, including a guide to fix issues.
## What's new in Scala 3
Scala 3 is a complete overhaul of the Scala language. At its core, many aspects
@@ -40,7 +41,7 @@ and focuses on **intent** rather than **mechanism**.
Instead of offering one very powerful feature, Scala 3 offers multiple
tailored language features, allowing programmers to directly express their intent:
-- **Abtracting over contextual information**. [Using clauses][contextual-using] allow programmers to abstract over information that is available in the calling context and should be passed implicitly. As an improvement over Scala 2 implicits, using clauses can be specified by type, freeing function signatures from term variable names that are never explicitly referred to.
+- **Abstracting over contextual information**. [Using clauses][contextual-using] allow programmers to abstract over information that is available in the calling context and should be passed implicitly. As an improvement over Scala 2 implicits, using clauses can be specified by type, freeing function signatures from term variable names that are never explicitly referred to.
- **Providing Type-class instances**. [Given instances][contextual-givens] allow programmers to define the _canonical value_ of a certain type. This makes programming with type-classes more straightforward without leaking implementation details.
@@ -59,7 +60,7 @@ Besides greatly improved type inference, the Scala 3 type system also offers man
- **Opaque Types**. Hide implementation details behind [opaque type aliases][types-opaque] without paying for it in performance! Opaque types supersede value classes and allow you to set up an abstraction barrier without causing additional boxing overhead.
-- **Intersection and union types**. Basing the type system on new foundations led to the introduction of new type system features: instances of [intersection types][types-intersection], like `A & B`, are instances of _both_ `A` and of `B`. Instances of [union types][types-union], like `A | B`, are instances of _either_ `A` or `B`. Both constructs allow programmers to flexibly express type constraints outside of the inheritance hierarchy.
+- **Intersection and union types**. Basing the type system on new foundations led to the introduction of new type system features: instances of [intersection types][types-intersection], like `A & B`, are instances of _both_ `A` and of `B`. Instances of [union types][types-union], like `A | B`, are instances of _either_ `A` or `B`. Both constructs allow programmers to flexibly express type constraints outside the inheritance hierarchy.
- **Dependent function types**. Scala 2 already allowed return types to depend on (value) arguments. In Scala 3 it is now possible to abstract over this pattern and express [dependent function types][types-dependent]. In the type `type F = (e: Entry) => e.Key` the result type _depends_ on the argument!
@@ -79,17 +80,17 @@ At the same time, the following novel features enable well-structured _object-or
- **Plan for extension**. Extending classes that are not intended for extension is a long-standing problem in object-oriented design. To address this issue, [open classes][oo-open] require library designers to _explicitly_ mark classes as open.
- **Hide implementation details**. Utility traits that implement behavior sometimes should not be part of inferred types. In Scala 3, those traits can be marked as [transparent][oo-transparent] hiding the inheritance from the user (in inferred types).
- **Composition over inheritance**. This phrase is often cited, but tedious to implement. Not so with Scala 3's [export clauses][oo-export]: symmetric to imports, export clauses allow the user to define aliases for selected members of an object.
-- **No more NPEs**. Scala 3 is safer than ever: [explicit null][oo-explicit-null] moves `null` out of the type hierarchy, helping you to catch errors statically; additional checks for [safe initialization][oo-safe-init] detect access to uninitialized objects.
+- **No more NPEs (experimental)**. Scala 3 is safer than ever: [explicit null][oo-explicit-null] moves `null` out of the type hierarchy, helping you to catch errors statically; additional checks for [safe initialization][oo-safe-init] detect access to uninitialized objects.
### Batteries Included: Metaprogramming
While macros in Scala 2 were an experimental feature only, Scala 3 comes with a powerful arsenal of tools for metaprogramming.
-The [macro tutorial]({% link _overviews/scala3-macros/index.md %}) contains detailed information on the different facilities. In particular, Scala 3 offers the following features for metaprogramming:
+The [macro tutorial]({% link _overviews/scala3-macros/tutorial/index.md %}) contains detailed information on the different facilities. In particular, Scala 3 offers the following features for metaprogramming:
- **Inline**. As the basic starting point, the [inline feature][meta-inline] allows values and methods to be reduced at compile time. This simple feature already covers many use-cases and at the same time provides the entry point for more advanced features.
- **Compile-time operations**. The package [`scala.compiletime`][meta-compiletime] contains additional functionality that can be used to implement inline methods.
- **Quoted code blocks**. Scala 3 adds the new feature of [quasi-quotation][meta-quotes] for code, providing a convenient high-level interface to construct and analyse code. Constructing code for adding one and one is as easy as `'{ 1 + 1 }`.
-- **Reflection API**. For more advanced use cases [TASTy reflect][meta-reflection] provides more detailed control to inspect and generate program trees.
+- **Reflection API**. For more advanced use cases [quotes.reflect][meta-reflection] provides more detailed control to inspect and generate program trees.
If you want to learn more about metaprogramming in Scala 3, we invite you to take our [tutorial][meta-tutorial].
@@ -109,9 +110,10 @@ If you want to learn more about metaprogramming in Scala 3, we invite you to tak
[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html
[reference]: {{ site.scala3ref }}/overview.html
[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html
-[migration]: https://scalacenter.github.io/scala-3-migration-guide
+[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %}
+[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %}
-[implicits]: {{ site.scala3ref }}/contextual/motivation.html
+[implicits]: {{ site.scala3ref }}/contextual
[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html
[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html
[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html
@@ -123,13 +125,13 @@ If you want to learn more about metaprogramming in Scala 3, we invite you to tak
[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html
[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html
-[meta-tutorial]: {% link _overviews/scala3-macros/index.md %}
+[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %}
[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %}
[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %}
[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %}
[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %}
-[oo-explicit-null]: {{ site.scala3ref }}/other-new-features/explicit-nulls.html
+[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html
[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html
[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html
[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html
diff --git a/scala3/reference/README.md b/scala3/reference/README.md
new file mode 100644
index 0000000000..418bdbe3e1
--- /dev/null
+++ b/scala3/reference/README.md
@@ -0,0 +1,6 @@
+The content of the pages https://docs.scala-lang.org/scala3/reference is
+generated from the [Scala 3 compiler repository](https://github.com/scala/scala3).
+
+Please go here to contribute to the Scala 3 reference documentation:
+
+https://github.com/scala/scala3/tree/main/docs/_docs
diff --git a/scala3/scaladoc.md b/scala3/scaladoc.md
new file mode 100644
index 0000000000..5a735173e3
--- /dev/null
+++ b/scala3/scaladoc.md
@@ -0,0 +1,87 @@
+---
+layout: singlepage-overview
+title: New features for Scaladoc
+partof: scala3-scaladoc
+languages: ["uk","ru"]
+---
+
+The new Scala version 3 comes with a completely new implementation of the documentation generator _Scaladoc_, rewritten from scratch.
+In this article you can find highlights of new features that are or will be introduced to Scaladoc.
+For general reference, visit [Scaladoc manual]({% link _overviews/scala3-scaladoc/index.md %}).
+
+## New features
+
+### Markdown syntax
+
+The biggest change introduced in the new version of Scaladoc is the change of the default language for docstrings. So far Scaladoc only supported Wikidoc syntax.
+The new Scaladoc can still parse legacy `Wikidoc` syntax, however Markdown has been chosen as a primary language for formatting comments.
+To switch back to `Wikidoc` one can pass a global flag before running the `doc` task or one can define it for specific comments via the `@syntax wiki` directive.
+
+For more information on how to use the full power of docstings, check out [Scaladoc docstrings][scaladoc-docstrings]
+
+
+### Static site
+
+Scaladoc also provides an easy way for creating **static sites** for both documentation and blog posts in the similar way as Jekyll does.
+Thanks to this feature, you can store your documentation along-side with the generated Scaladoc API in a very convenient way.
+
+For more information on how to configure the generation of static sites check out [Static documentation][static-documentation] chapter
+
+
+
+### Blog posts
+
+Blog posts are a specific type of static sites. In the Scaladoc manual you can find additional information about how to work with [blog posts][built-in-blog].
+
+
+
+### Social links
+
+Furthermore, Scaladoc provides an easy way to configure your [social media links][social-links] e.g. Twitter or Discord.
+
+{: style="width: 180px"}
+
+## Experimental features
+
+The following features are currently (May 2021) not stable to be released with scaladoc, however we are happy to hear your feedback. Each feature has its own thread at scala-lang contributors site, where you can share your opinions.
+
+### Snippet compiling
+
+One of the experimental features of Scaladoc is a compiler for snippets. This tool will allow you to compile snippets that you attach to your docstring
+to check that they actually behave as intended, e.g., to properly compile. This feature is very similar to the `tut` or `mdoc` tools,
+but will be shipped with Scaladoc out of the box for easy setup and integration into your project. Making snippets interactive---e.g., letting users edit and compile them in the browser---is under consideration, though this feature is not in scope at this time.
+
+Showcase:
+* Hiding code 
+* Assert compilation errors 
+* Snippet includes 
+
+For more information see [Guides](/scala3/guides/scaladoc/snippet-compiler.html), or follow this [Scala Contributors thread](https://contributors.scala-lang.org/t/snippet-validation-in-scaladoc-for-scala-3/4976)
+
+### Type-based search
+
+Searching for functions by their symbolic names can be time-consuming.
+That is why the new scaladoc allows you to search for methods and fields by their types.
+
+
+So, for a declaration:
+```
+extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ...
+```
+Instead of searching for `span` we can also search for `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`.
+
+To use this feature simply type the signature of the function you are looking for in the scaladoc searchbar. This is how it works:
+
+
+
+This feature is provided by the [Inkuire](https://github.com/VirtusLab/Inkuire) search engine, which works for Scala 3 and Kotlin. To be up-to-date with the development of this feature, follow the [Inkuire repository](https://github.com/VirtusLab/Inkuire).
+
+For more information see [Guides](/scala3/guides/scaladoc/search-engine.html)
+
+Note that this feature is still in development, so it can be subject to considerable change.
+If you encounter a bug or have an idea for improvement, don't hesitate to create an issue on [Inkuire](https://github.com/VirtusLab/Inkuire/issues/new) or [scala3](https://github.com/scala/scala3/issues/new).
+
+[scaladoc-docstrings]: {% link _overviews/scala3-scaladoc/docstrings.md %}
+[static-documentation]: {% link _overviews/scala3-scaladoc/static-site.md %}
+[built-in-blog]: {% link _overviews/scala3-scaladoc/blog.md %}
+[social-links]: {% link _overviews/scala3-scaladoc/settings.md %}#-social-links
diff --git a/scala3/talks.md b/scala3/talks.md
new file mode 100644
index 0000000000..0cdba8b2d0
--- /dev/null
+++ b/scala3/talks.md
@@ -0,0 +1,72 @@
+---
+layout: singlepage-overview
+title: Talks
+scala3: true
+partof: scala3-talks
+languages: ["uk","ru"]
+versionSpecific: true
+---
+
+Let’s Talk About Scala 3 Series
+-------------------------------
+
+[Let’s Talk About Scala 3](https://www.youtube.com/playlist?list=PLTx-VKTe8yLxYQfX_eGHCxaTuWvvG28Ml) is a series
+of short (around 15 min) talks about Scala 3. It covers a variety of themes like how to get started, how to take
+advantage of the new language features, or how to migrate from Scala 2.
+
+Talks on Scala 3
+----------------
+- (ScalaDays 2019, Lausanne) [A Tour of Scala 3](https://www.youtube.com/watch?v=_Rnrx2lo9cw) by [Martin Odersky](http://x.com/odersky)
+
+- (ScalaDays 2016, Berlin) [Scala's Road Ahead](https://www.youtube.com/watch?v=GHzWqJKFCk4) by [Martin Odersky](http://x.com/odersky) [\[slides\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016)
+
+- (JVMLS 2015) [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc) by [Martin Odersky](http://x.com/odersky) [\[slides\]](http://www.slideshare.net/Odersky/compilers-are-databases)
+
+- (Scala World 2015) [Dotty: Exploring the future of Scala](https://www.youtube.com/watch?v=aftdOFuVU1o) by [Dmitry Petrashko](http://x.com/darkdimius) [\[slides\]](https://d-d.me/scalaworld2015/#/).
+ Dmitry covers many of the new features that Dotty brings on the table such as Intersection and Union types, improved lazy val initialization and more.
+ Dmitry also covers dotty internals and in particular the high-level of contextual abstractions of Dotty. You will get to
+ become familiar with many core concepts such as `Denotations`, their evolution through (compilation) time, their
+ transformations and more.
+
+Deep Dive with Scala 3
+----------------------
+- (ScalaDays 2019, Lausanne) [Metaprogramming in Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc) by [Nicolas Stucki](https://github.com/nicolasstucki).
+
+- (ScalaDays 2019, Lausanne) [Future-proofing Scala: the TASTY intermediate representation](https://www.youtube.com/watch?v=zQFjC3zLYwo) by [Guillaume Martres](http://guillaume.martres.me/).
+
+- (Mar 21, 2017) [Dotty Internals 1: Trees & Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8) by [Dmitry Petrashko](http://x.com/darkdimius) [\[meeting notes\]](https://dotty.epfl.ch/docs/internals/dotty-internals-1-notes.html).
+ This is a recorded meeting between EPFL and Waterloo, where we introduce first notions inside Dotty: Trees and Symbols.
+
+- (Mar 21, 2017) [Dotty Internals 2: Types](https://www.youtube.com/watch?v=3gmLIYlGbKc) by [Martin Odersky](http://x.com/odersky) and [Dmitry Petrashko](http://x.com/darkdimius).
+ This is a recorded meeting between EPFL and Waterloo, where we introduce how types are represented inside Dotty.
+
+- (Jun 15, 2017) [Dotty Internals 3: Denotations](https://youtu.be/9iPA7zMRGKY) by [Martin Odersky](http://x.com/odersky) and [Dmitry Petrashko](http://x.com/darkdimius).
+ This is a recorded meeting between EPFL and Waterloo, where we introduce denotations in Dotty.
+
+- (JVM Language Summit) [How do we make the Dotty compiler fast](https://www.youtube.com/watch?v=9xYoSwnSPz0) by [Dmitry Petrashko](http://x.com/darkdimius).
+ [Dmitry Petrashko](http://x.com/darkdimius) gives a high-level introduction on what was done to make Dotty .
+
+
+- (Typelevel Summit Oslo, May 2016) [Dotty and types: the story so far](https://www.youtube.com/watch?v=YIQjfCKDR5A) by
+ Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/).
+ Guillaume focused on some practical improvements to the type system that Dotty makes, like the new type parameter
+ inference algorithm that is able to reason about the type safety of more situations than scalac.
+
+- (flatMap(Oslo) 2016) [AutoSpecialization in Dotty](https://vimeo.com/165928176) by [Dmitry Petrashko](http://x.com/darkdimius) [\[slides\]](https://d-d.me/talks/flatmap2016/#/).
+ The Dotty Linker analyses your program and its dependencies to
+ apply a new specialization scheme. It builds on our experience from Specialization, Miniboxing and the Valhalla Project,
+ and drastically reduces the size of the emitted bytecode. And, best of all, it's always enabled, happens behind the
+ scenes without annotations, and results in speedups in excess of 20x. Additionally, it "just works" on Scala collections.
+
+- (ScalaSphere 2016) [Hacking on Dotty: A live demo](https://www.youtube.com/watch?v=0OOYGeZLHs4) by Guillaume Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-live-demo/).
+ Guillaume hacks on Dotty: a live demo during which he
+ creates a simple compiler phase to trace method calls at run-time.
+
+- (Scala By the Bay 2016) [Dotty: what is it and how it works](https://www.youtube.com/watch?v=wCFbYu7xEJA) by Guillaume
+ Martres [\[slides\]](http://guillaume.martres.me/talks/dotty-tutorial/#/). Guillaume provides a high-level view of the
+ compilation-pipeline of Dotty.
+
+- (ScalaDays 2015, Amsterdam) [Making your Scala applications smaller and faster with the Dotty linker](https://www.youtube.com/watch?v=xCeI1ArdXM4) by Dmitry Petrashko [\[slides\]](https://d-d.me/scaladays2015/#/).
+ Dmitry introduces the call-graph analysis algorithm
+ that Dotty implements and the performance benefits we can get in terms of number of methods, bytecode size, JVM code size
+ and the number of objects allocated in the end.
diff --git a/scalacenter-courses.md b/scalacenter-courses.md
new file mode 100644
index 0000000000..b242e6f5fe
--- /dev/null
+++ b/scalacenter-courses.md
@@ -0,0 +1,169 @@
+---
+title: Online Courses (MOOCs) from The Scala Center
+layout: singlepage-overview
+languages: [ru]
+testimonials:
+ - /resources/images/scalacenter-courses/testimonial000.jpg
+ - /resources/images/scalacenter-courses/testimonial001.jpg
+ - /resources/images/scalacenter-courses/testimonial002.jpg
+ - /resources/images/scalacenter-courses/testimonial003.jpg
+ - /resources/images/scalacenter-courses/testimonial004.jpg
+ - /resources/images/scalacenter-courses/testimonial005.jpg
+ - /resources/images/scalacenter-courses/testimonial006.jpg
+ - /resources/images/scalacenter-courses/testimonial007.jpg
+ - /resources/images/scalacenter-courses/testimonial008.jpg
+ - /resources/images/scalacenter-courses/testimonial009.jpg
+ - /resources/images/scalacenter-courses/testimonial010.jpg
+ - /resources/images/scalacenter-courses/testimonial011.jpg
+ - /resources/images/scalacenter-courses/testimonial012.jpg
+ - /resources/images/scalacenter-courses/testimonial013.jpg
+ - /resources/images/scalacenter-courses/testimonial014.jpg
+---
+
+The [Scala Center] produces online courses (a.k.a. MOOCs) of various levels, from beginner
+to advanced.
+
+**If you are a programmer and want to learn Scala**, there are two recommended
+approaches. The fast path consists of taking the course [Effective Programming
+in Scala](#effective-programming-in-scala).
+Otherwise, you can take the full [Scala Specialization], which is made of
+four courses (covering advanced topics such as big data analysis and
+parallel programming) and a capstone project.
+
+You can learn more about the courses in the following video:
+
+
+
-
- {% assign sips = site.sips | sort: date | reverse %}
{% for sip in sips %}
- {% if sip.vote-status == "under-review" or sip.vote-status == "pending" or sip.vote-status == "under-revision" %}
-
-
- {{ sip.title }}
- {{ sip.date | date: '%B %Y' }}-{{ site.data.sip-data[sip.vote-status].text }}+ {% if sip.stage == "design" or sip.stage == "implementation" %} +
-
+
+
+ {{ sip.title }}
+
+
+ Stage: {{ sipData[sip.stage].text }}+Status: {{ sipData[sip.status].text }}+ {% if sip.recommendation %} +Recommendation: {{ sipData[sip.recommendation].text }}+ {% endif %}
{% endif %}
{% endfor %}
-
+Thread: <{{ site.scala3ref }}/experimental/explicit-nulls.html>
Sébastien championing and presenting.
diff --git a/_sips/minutes/2020-03-12-minutes.md b/_sips/minutes/2020-03-12-minutes.md
index c83443462d..4e40af5e32 100644
--- a/_sips/minutes/2020-03-12-minutes.md
+++ b/_sips/minutes/2020-03-12-minutes.md
@@ -128,7 +128,7 @@ Run through https://dotty.epfl.ch/docs/reference/metaprogramming/inline.html
* Gui: inline interacts with overriding
* Nic: if in a subclass (say Range) you override a method (say foreach) with `inline` it only inlines if the type is cast
* Seb: I need both, inline if statically the type is Range, and use the optimised override if it's a Seq that's a Range at runtime
-* (After the meeting, this led to [lampepfl/dotty#8543](https://github.com/lampepfl/dotty/pull/8543) and [lampepfl/dotty#8564](https://github.com/lampepfl/dotty/issues/8564).)
+* (After the meeting, this led to [scala/scala3#8543](https://github.com/scala/scala3/pull/8543) and [scala/scala3#8564](https://github.com/scala/scala3/issues/8564).)
* Lukas: `inline` is perfect for macros, but it shouldn't exist for performance. The runtime is where performance should be fixed (and it's in a better position to do it)
* Lukas: inlining isn't on by default (in Scala 2) because it interacts with binary compatibility in non-obvious ways, and `inline` in Dotty does the same
@@ -144,7 +144,7 @@ Run through https://dotty.epfl.ch/docs/reference/metaprogramming/reflection.html
### Review match types
-Review https://github.com/dotty-staging/dotty/blob/fix-6709/docs/docs/reference/new-types/match-types.md (part of https://github.com/lampepfl/dotty/pull/8024)
+Review https://github.com/dotty-staging/dotty/blob/fix-6709/docs/docs/reference/new-types/match-types.md (part of https://github.com/scala/scala3/pull/8024)
```scala
type LeafElem[X] = X match {
@@ -157,7 +157,7 @@ type LeafElem[X] = X match {
* Olivier: The order of match type definitions is significant
* Olivier: The disjointness is between `X` and `String`, not between `String` and `Array`
-* Olivier: See https://github.com/lampepfl/dotty/issues/8493 as an example of disjointness requirement (can't use traits)
+* Olivier: See https://github.com/scala/scala3/issues/8493 as an example of disjointness requirement (can't use traits)
* Martin: Currently the use-cases can be implemented like Generic
* Olivier: Put at a very high level, the intent is to remove some of the computation that happens in implicits and do it (better) in match types
* Olivier: another problem is that when you type-check a type you can stackoverflow, which has bad UX, particularly given we have recursive types
diff --git a/_sips/minutes/2020-03-13-sip-minutes.md b/_sips/minutes/2020-03-13-sip-minutes.md
index 405755918d..7e394ea557 100644
--- a/_sips/minutes/2020-03-13-sip-minutes.md
+++ b/_sips/minutes/2020-03-13-sip-minutes.md
@@ -285,8 +285,8 @@ Martin:
- Used widely in compiler codebase for 6 months
- Does find is necessary to have vertical bars in editor for indentation
- Examples at:
- - https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/semanticdb/ExtractSemanticDB.scala
- - https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/typer/Nullables.scala
+ - https://github.com/scala/scala3/blob/main/compiler/src/dotty/tools/dotc/semanticdb/ExtractSemanticDB.scala
+ - https://github.com/scala/scala3/blob/main/compiler/src/dotty/tools/dotc/typer/Nullables.scala
- `then` in if expression was harder to get used to
Guillaume:
@@ -424,7 +424,7 @@ Sébastien:
- Asks if the new rules allow to add an implicit definition of a priority in-between two other definitions while preserving binary compatability?
Martin, in response:
-- Shows a [demo](https://github.com/lampepfl/dotty/blob/master/tests/run/implied-priority.scala) of how to insert a new implicit in between existing definitions.
+- Shows a [demo](https://github.com/scala/scala3/blob/main/tests/run/implied-priority.scala) of how to insert a new implicit in between existing definitions.
- The new scheme of priorities is more simple to grow than before because inheritance is fragile
Sébastien is satisfied with the demo, is fine either way to add to 3.0 or later. Someone should champion it.
diff --git a/_sips/process-specification.md b/_sips/process-specification.md
new file mode 100644
index 0000000000..93a15ce812
--- /dev/null
+++ b/_sips/process-specification.md
@@ -0,0 +1,342 @@
+---
+layout: sips
+title: Process Specification
+redirect_from: /sips/sip-submission.html
+---
+
+The Scala Improvement Process (sometimes called SIP process) is a process for
+submitting changes to the Scala language. This process aims to evolve Scala
+openly and collaboratively.
+
+The SIP process covers the Scala language (syntax, type system and semantics)
+and the core of the Scala standard library. The core is anything that is
+referenced from the language spec (such as primitive types or the definition
+of `Seq`). The SIP process is not concerned with compiler changes that do not
+affect the language (including but not limited to linting warnings,
+optimizations, quality of error messages).
+
+A proposed change requires a design document, called a Scala Improvement
+Proposal (SIP). The committee meets monthly to discuss, and eventually vote
+upon, proposals.
+
+The committee follows the following process when evaluating SIP documents,
+from an idea to the inclusion in the language.
+
+## Definitions
+
+- SIP (Scala Improvement Proposal): a particular proposal for changing the Scala
+ language (additions, changes, and/or removals).
+- Committee: a group of experienced Scala practitioners and language designers,
+ who evaluate changes to the Scala programming language. It consists of a
+ Secretary, a Chairperson, and Members.
+- Chairperson: person in charge of executing the process. They organize and
+ chair the meetings of the Committee, and generally make sure the process is
+ followed, but do not vote on proposals. The Chairperson is an appointed
+ employee of the Scala Center.
+- Committee Member: member of the Committee with voting rights. The Chairperson
+ cannot be a Member at the same time.
+- Secretary: person attending the regular meetings and responsible for writing
+ notes of the discussions.
+- SIP Author: any individual or group of people who writes a SIP for submission
+ to the Committee. The Chairperson and Committee Members may also be SIP Authors.
+ Authors are responsible for building consensus within the community and
+ documenting dissenting opinions before the SIP is officially discussed by the
+ SIP Committee. Their goal is to convince the committee that their proposal is
+ useful and addresses pertinent problems in the language as well as interactions
+ with already existing features. Authors can change over the life-cycle of the
+ SIP.
+- SIP Reviewers: a subset of Committee Members assigned by the Chairperson to
+ review in detail a particular SIP. The same person cannot be both a SIP Author
+ and a SIP Reviewer for the same SIP.
+- SIP Manager: one of the SIP Reviewers who is responsible for all the
+ communications related to the SIP, throughout its entire life-cycle. This includes requesting a vote on the SIP from the whole Committee, presenting the SIP to the Committee at the plenary meetings, merging or closing the corresponding PR, reporting to the community on the vote outcome, and announcing when it is available for testing.
+
+## Stages
+
+From being an idea to being part of the language, a SIP goes through several
+Stages that indicate the "maturity" level of the SIP. The following table
+summarizes the intent of the various stages.
+
+
+
+
+
+### The process in one graph
+
+
+
+### Pre-SIP Stage
+
+To initiate a discussion, any individual opens a "Pre-SIP" post in the Scala
+Contributors forum. The post should be in the
+[Scala Improvement Process](https://contributors.scala-lang.org/c/sip/13)
+category, and its title should start with "Pre-SIP:". The purpose of the Pre-SIP
+post is to present an idea to the Scala community: a Pre-SIP should present a
+problem that needs solving (i.e., motivate the changes) and present possible
+solutions with pros and cons. The community is encouraged to engage in the
+discussions by voicing support, comments and concerns.
+
+During the Pre-SIP stage, the Committee is not required to be involved.
+Committee Members and the Chairperson are expected to follow Pre-SIP
+discussions, but not required to engage.
+
+Once at least one month has passed and the author has built some community
+support for their Pre-SIP, they can Submit a SIP for discussion by the
+Committee. "Community support" is loosely defined. It involves a mix of positive
+comments, likes, etc. Generally, the Chairperson or a Committee member will post
+a comment on the thread suggesting to submit a SIP when they see that a Pre-SIP
+is ready to enter the process.
+
+### Entry into the process (SIP Submission)
+
+To submit a SIP, a SIP Author writes a pull request to the
+[scala/improvement-proposals](https://github.com/scala/improvement-proposals)
+repository, following the [tutorial]({% link _sips/sip-tutorial.md %}), and
+pointing to the Pre-SIP discussion. If the proposal correctly follows the
+template, and the Pre-SIP discussion seems to show some community support,
+the Chairperson will accept the SIP for review, assign a SIP number, assign
+3 reviewers to the SIP among the Committee Members, and assign one of the reviewers
+to be the Manager of that SIP. Since "community support" is
+loosely defined, any Committee Member can also comment on the PR to accept the
+SIP for review (this is meant mostly as an escape hatch to prevent the
+Chairperson from unilaterally blocking a SIP from entering the process). From
+that point onwards, the SIP has entered the Design Stage.
+
+If the template has not been correctly followed, or if none of the Committee
+Members nor the Chairperson think that the Pre-SIP has gathered enough support,
+the PR may be closed after 2 weeks.
+
+### PR states and GitHub labels
+
+As soon as a SIP PR is opened, the GitHub labels `stage:pre-sip` and
+`status:submitted` are applied to it. At any given moment, a SIP PR will have as
+labels one of the following possibilities:
+
+| | | |
+|------------------------|-------------------------------------|-------------------------|
+| `stage:pre-sip` | `status:submitted` | |
+| `stage:design` | `status:under-review` | |
+| `stage:design` | `status:vote-requested` | `recommendation:accept` |
+| `stage:design` | `status:vote-requested` | `recommendation:reject` |
+| `stage:implementation` | `status:waiting-for-implementation` | |
+| `stage:implementation` | `status:under-review ` | |
+| `stage:implementation` | `status:vote-requested` | `recommendation:accept` |
+| `stage:implementation` | `status:vote-requested` | `recommendation:reject` |
+| `stage:completed` | `status:accepted` | |
+| `stage:completed` | `status:shipped` | |
+| | `status:rejected` | |
+| | `status:withdrawn` | |
+
+### Design Stage -- Review
+
+Once a SIP has entered the Design Stage, the assigned reviewers will review (as
+a GitHub Review on the SIP PR) the proposal within 3 weeks. The authors may then
+address the concerns by pushing additional commits and ask for a new review.
+This phase is iterative, like any pull request to an implementation repository.
+After each request for a new review, the reviewers have 3 weeks to do another
+round.
+
+When the reviewers are confident that the SIP is in good shape to be discussed
+with the full Committee, the Manager sets its status to "Vote Requested" and decide on a
+Vote Recommendation that they will bring to the Committee. A Vote Recommendation
+is either "Recommend Accept" or "Recommend Reject". The proposal is then
+scheduled on the agenda of the next Committee meeting (which happens once a
+month).
+
+At any time, the SIP Author may voluntarily Withdraw their SIP, in which case it
+exits the process. It is possible for someone else (or the same person) to
+become the new SIP Author for that SIP, and therefore bring it back to the
+process. If a SIP Author does not follow up on Reviewers' comments for 2 months,
+the SIP will automatically be considered to be Withdrawn.
+
+### Design Stage -- Vote
+
+During the Committee meeting, the Managers of any scheduled SIP present the SIP
+to the Committee, their recommendation, and explain why they made that
+recommendation. After discussion, the Committee votes for advancing the SIP to
+the Implementation Stage. There are three possible outcomes:
+
+- Accept for implementation: the proposal then advances to the Implementation
+ Stage, and therefore becomes a formal recommendation to be implemented as an
+ Experimental feature into the compiler.
+- Reject: the proposal is rejected and the PR closed. It exits the process at
+ this point. The reviewers will communicate on the PR the reason(s) for the
+ rejection.
+- Keep: the proposal remains in the Design Stage for further iterations. The
+ reviewers will communicate on the PR the current concerns raised by the
+ Committee.
+
+In order to be accepted for implementation and advance to the next stage, a SIP
+must gather strictly more than 50% of "Advance" votes among the whole Committee. This means that an abstention is equivalent to "Do not advance" for this purpose, biasing the process in favor of the status quo. Furthermore, if more than half of the Committee members are absent at the meeting, the vote is cancelled.
+
+For instance, if the Committee is made of 11 members, at least 6 members have to vote "Advance" for the SIP to move to the next stage.
+
+If there was a strict majority in favor of "Advance", the PR for the SIP is Merged at this point by its Manager.
+Otherwise, a second vote between
+Reject and Keep will be used. A proposal needs more than 50% "Reject" votes to
+be rejected in that case. Otherwise, it is kept.
+
+The SIP Manager shares the outcome of the vote with the community by posting a comment to proposal’s Pre-SIP discussion.
+
+### Implementation Stage
+
+Once in the implementation stage, the Committee is not concerned with the SIP
+anymore, until new concerns are discovered or until the implementation is ready.
+The SIP is now a recommendation for the compiler team or any other individual or
+group of people to provide an implementation of the proposal, as a pull request
+to the Scala 3 compiler repository. There is no set timeline for this phase.
+
+Often, proposals not only need to be implemented in the compiler, but also in
+several other tools (IDEs, syntax highlighters, code formatters, etc.). As soon
+as a proposal reaches the implementation stage, the Chairperson notifies the
+impacted tools that they should start implementing support for it. A list of
+tools of the ecosystem is maintained in [this document][tooling ecosystem].
+
+An implementation will be reviewed by the compiler team, and once the
+implementation is deemed good enough, it can ship as an Experimental feature in
+the next release of the compiler where it's practical to do so. At that point, the SIP Manager posts a follow-up comment on the Pre-SIP discussion to invite the community to test the feature and provide feedback.
+
+The implementers may hit challenges that were not foreseen by the Committee.
+Early users may also provide feedback based on practical experience with the
+Experimental feature. This feedback can be sent back to the Committee by
+implementers. This is done with a PR to the SIP repository, amending the
+previously merged SIP document or raising questions for challenges. In that
+case, the SIP Author and Reviewers will work together with the implementers to
+address the feedback. This is again an iterative process. Reviewers may merge
+changes to the proposal at their discretion during this phase.
+
+Once the implementation is deemed stable, including appropriate tests and
+sufficient support by the tooling ecosystem, the implementers and reviewers can
+schedule the SIP to the next Committee meeting for final approval. Once again, a
+SIP needs to gather strictly more than 50% "Accept" votes to be Completed. If
+that is not achieved, it may likewise be sent back for refinements, or be
+rejected, with the same rules as in the "Design Stage -- Vote" section.
+
+### Completed Stage
+
+Once a SIP is accepted for shipping, it will be enabled by default (as
+non-Experimental) in the next practical Minor release of the language.
+
+From this point onwards, the feature is stable and cannot be changed anymore.
+Any further changes would have to come as an entirely new SIP.
+
+## The SIP Committee
+
+The current committee members are:
+
+- Björn Regnell ([@bjornregnell](https://github.com/bjornregnell)), Lund University
+- Chris Andrews ([@chrisandrews-ms](https://github.com/chrisandrews-ms)), Morgan Stanley
+- Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL
+- Haoyi Li ([@lihaoyi](https://github.com/lihaoyi)), Databricks
+- Lukas Rytz ([@lrytz](https://github.com/lrytz)), Lightbend
+- Martin Odersky ([@odersky](https://github.com/odersky)), EPFL
+- Oron Port ([@soronpo](https://github.com/soronpo)), DFiant Inc
+- Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center
+
+The current Chairperson is:
+
+- Dimi Racordon ([@kyouko-taiga](https://github.com/kyouko-taiga)), EPFL
+
+The current Secretary is:
+
+- Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend
+
+### Committee Meetings
+
+The plenary Committee Meetings are scheduled monthly by the Chairperson. They
+have the following purposes:
+
+- Vote to accept, keep or reject SIPs that are in a "Vote Requested" state
+- Be aware of the list of SIPs that are "Under review". If a SIP stays too long
+ under review, Committee Members may request for it to be put to discussion
+ and/or vote in a subsequent plenary meeting, even if the Reviewers do not
+ think it is ready. This is meant primarily as an escape hatch, preventing
+ Reviewers from blocking a SIP by infinitely stalling it.
+- Make any exception to the process that they judge necessary to unblock a
+ situation.
+
+If a Committee Member cannot attend a meeting, they are welcome to share their feedback about the proposals listed in the agenda of the meeting with the Chairperson, who will relate it during the meeting. A Committee Member cannot give their voting power to someone else. If a Committee Member misses more than 2 meetings within a year, they lose their seat.
+
+### Responsibilities of the Committee Members
+
+- Review the proposals they are assigned to:
+ 1. Discuss unclear points with the authors,
+ 2. Help them address their issues and questions,
+ 3. Provide them feedback from the discussions in the meetings, and
+ 4. Explain the latest progress in every meeting.
+- Play a role in the discussions, learn in advance about the topic if needed,
+ and make up their mind in the voting process.
+- Establish communication channels with the community to share updates about the evolution of proposals and collect feedback.
+
+### Guests
+
+Experts in some fields of the compiler may be invited to concrete meetings as
+guests when discussing related SIPs. Their input would be important to discuss
+the current state of the proposal, both its design and implementation.
+
+### On what basis are proposals evaluated?
+
+The Committee ultimately decides how to evaluate proposals, and on what grounds.
+The Committee does not need to justify its decisions, although it is highly
+encouraged to provide reasons.
+
+Nevertheless, here is a non-exhaustive list of things that the Reviewers and
+Committee are encouraged to take into account:
+
+- The proposal follows the "spirit" of Scala
+- The proposal is well motivated; it solves a recurring problem
+- The proposal evaluates the pros and cons of its solution; the solution put
+ forward is believed to be the best one
+- The proposal can be implemented in a way that does not break backward binary
+ nor TASTy compatibility
+- The proposal makes an effort not to break backward source compatibility
+- The proposal does not change the meaning of existing programs
+- The proposal can be implemented on all major platforms (JVM, JS and Native)
+
+## Exceptions and changes
+
+The present document tries to account for most situations that could occur in
+the lifetime of SIPs. However, it does not pretend to be an ultimate solution to
+all cases. At any time, the Committee can decide, by consensus, to make
+exceptions to the process, or to refine the process.
+
+## How do I submit?
+
+Follow the [submission tutorial]({% link _sips/sip-tutorial.md %}).
+
+[tooling ecosystem]: https://github.com/scala/improvement-proposals/blob/main/tooling-ecosystem.md
diff --git a/_sips/results/2022-08-26-meeting.md b/_sips/results/2022-08-26-meeting.md
new file mode 100644
index 0000000000..efec513d6c
--- /dev/null
+++ b/_sips/results/2022-08-26-meeting.md
@@ -0,0 +1,25 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 26th August 2022
+partof: results
+proposals:
+ - url: https://github.com/scala/improvement-proposals/pull/29
+ name: SIP-32 - Allow referring to other arguments in default parameters
+ result: rejected
+ - url: https://github.com/scala/improvement-proposals/pull/37
+ name: SIP-39 - Uncluttering Abuse of Match
+ result: rejected
+ - url: https://docs.scala-lang.org/sips/binary-integer-literals.html
+ name: SIP-42 - Binary Integer Literals
+ result: accepted
+ - url: https://github.com/scala/improvement-proposals/pull/42
+ name: SIP-40 - Name Based XML Literals
+ result: rejected
+ - url: https://github.com/scala/improvement-proposals/pull/41
+ name: SIP-45 - Curried varargs
+ result: rejected
+ - url: https://docs.scala-lang.org/sips/fewer-braces.html
+ name: SIP-44 - Fewer braces
+ result: accepted
+---
+
diff --git a/_sips/results/2022-09-16-meeting.md b/_sips/results/2022-09-16-meeting.md
new file mode 100644
index 0000000000..e18fd2a2da
--- /dev/null
+++ b/_sips/results/2022-09-16-meeting.md
@@ -0,0 +1,13 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 16th September 2022
+partof: results
+proposals:
+ - url: https://github.com/scala/improvement-proposals/pull/47
+ name: SIP-47 - Clause Interleaving
+ result: under-review
+ - url: https://github.com/scala/improvement-proposals/pull/46
+ name: SIP-46 - Use Scala CLI to implement the 'scala' command
+ result: under-review
+---
+
diff --git a/_sips/results/2022-10-21-meeting.md b/_sips/results/2022-10-21-meeting.md
new file mode 100644
index 0000000000..41347c6274
--- /dev/null
+++ b/_sips/results/2022-10-21-meeting.md
@@ -0,0 +1,16 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 21st October 2022
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/fewer-braces.html
+ name: SIP-44 - Fewer braces
+ result: accepted
+ - url: https://docs.scala-lang.org/sips/scala-cli.html
+ name: SIP-46 - Use Scala CLI to implement the 'scala' command
+ result: accepted
+ - url: https://docs.scala-lang.org/sips/clause-interleaving.html
+ name: SIP-47 - Clause Interleaving
+ result: accepted
+---
+
diff --git a/_sips/results/2022-11-18-meeting.md b/_sips/results/2022-11-18-meeting.md
new file mode 100644
index 0000000000..035164ad8b
--- /dev/null
+++ b/_sips/results/2022-11-18-meeting.md
@@ -0,0 +1,9 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 18th November 2022
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/polymorphic-eta-expansion.html
+ name: SIP-49 - Polymorphic Eta-Expansion
+ result: accepted
+---
diff --git a/_sips/results/2023-02-17-meeting.md b/_sips/results/2023-02-17-meeting.md
new file mode 100644
index 0000000000..ede0dfc5bf
--- /dev/null
+++ b/_sips/results/2023-02-17-meeting.md
@@ -0,0 +1,9 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 17th February 2023
+partof: results
+proposals:
+ - url: https://github.com/scala/improvement-proposals/pull/54
+ name: SIP-51 - Drop Forwards Binary Compatibility of the Scala 2.13 Standard Library
+ result: accepted
+---
diff --git a/_sips/results/2023-03-17-meeting.md b/_sips/results/2023-03-17-meeting.md
new file mode 100644
index 0000000000..7c1ef1e50f
--- /dev/null
+++ b/_sips/results/2023-03-17-meeting.md
@@ -0,0 +1,9 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 17th March 2023
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/scala-cli.html
+ name: SIP-46 - Scala CLI as default Scala command
+ result: accepted
+---
diff --git a/_sips/results/2023-04-21-meeting.md b/_sips/results/2023-04-21-meeting.md
new file mode 100644
index 0000000000..b522759d88
--- /dev/null
+++ b/_sips/results/2023-04-21-meeting.md
@@ -0,0 +1,12 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 21st April 2023
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/quote-pattern-type-variable-syntax.html
+ name: SIP-53 - Quote pattern explicit type variable syntax
+ result: accepted
+ - url: https://docs.scala-lang.org/sips/multi-source-extension-overloads.html
+ name: SIP-54 - Multi-Source Extension Overloads
+ result: accepted
+---
diff --git a/_sips/results/2023-06-16-meeting.md b/_sips/results/2023-06-16-meeting.md
new file mode 100644
index 0000000000..0ad96e5ffb
--- /dev/null
+++ b/_sips/results/2023-06-16-meeting.md
@@ -0,0 +1,9 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 16th June 2023
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/multi-source-extension-overloads.html
+ name: SIP-54 - Multi-Source Extension Overloads
+ result: accepted
+---
diff --git a/_sips/results/2023-07-21-meeting.md b/_sips/results/2023-07-21-meeting.md
new file mode 100644
index 0000000000..6d873e6717
--- /dev/null
+++ b/_sips/results/2023-07-21-meeting.md
@@ -0,0 +1,7 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 21st July 2023
+partof: results
+proposals: []
+---
+No voting was held on this meeting.
\ No newline at end of file
diff --git a/_sips/results/2023-09-11-meeting.md b/_sips/results/2023-09-11-meeting.md
new file mode 100644
index 0000000000..c7231e6d9b
--- /dev/null
+++ b/_sips/results/2023-09-11-meeting.md
@@ -0,0 +1,7 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 11th September 2023
+partof: results
+proposals: []
+---
+No voting was held on this meeting.
\ No newline at end of file
diff --git a/_sips/results/2023-10-20-meeting.md b/_sips/results/2023-10-20-meeting.md
new file mode 100644
index 0000000000..33abe5c90a
--- /dev/null
+++ b/_sips/results/2023-10-20-meeting.md
@@ -0,0 +1,9 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 20th October 2023
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/binary-api.html
+ name: SIP-52 - Binary APIs
+ result: accepted
+---
diff --git a/_sips/results/2023-11-17-meeting.md b/_sips/results/2023-11-17-meeting.md
new file mode 100644
index 0000000000..fcb63c9e26
--- /dev/null
+++ b/_sips/results/2023-11-17-meeting.md
@@ -0,0 +1,9 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 17th November 2023
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/match-types-spec.html
+ name: SIP-56 - Proper Specification for Match Types
+ result: accepted
+---
diff --git a/_sips/results/2023-12-15-meeting.md b/_sips/results/2023-12-15-meeting.md
new file mode 100644
index 0000000000..647b689123
--- /dev/null
+++ b/_sips/results/2023-12-15-meeting.md
@@ -0,0 +1,7 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 12th December 2023
+partof: results
+proposals: []
+---
+No voting was held on this meeting.
\ No newline at end of file
diff --git a/_sips/results/2024-01-19-meeting.md b/_sips/results/2024-01-19-meeting.md
new file mode 100644
index 0000000000..23f2f49c6a
--- /dev/null
+++ b/_sips/results/2024-01-19-meeting.md
@@ -0,0 +1,9 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 19th January 2024
+partof: results
+proposals:
+ - url: https://docs.scala-lang.org/sips/match-types-spec.html
+ name: SIP-56 - Proper Specification for Match Types
+ result: accepted as completed
+---
diff --git a/_sips/results/2024-04-19-meeting.md b/_sips/results/2024-04-19-meeting.md
new file mode 100644
index 0000000000..b5db00bc7a
--- /dev/null
+++ b/_sips/results/2024-04-19-meeting.md
@@ -0,0 +1,16 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 19th April 2024
+partof: results
+proposals:
+ - url: https://github.com/scala/improvement-proposals/pull/72
+ name: SIP-58 - Named Tuples
+ result: accepted
+ - url: https://github.com/scala/improvement-proposals/pull/79
+ name: SIP-62 - For comprehension improvements
+ result: accepted
+ - url: https://github.com/scala/improvement-proposals/pull/81
+ name: SIP-64 - Improve the syntax of context bounds and givens
+ result: accepted
+---
+SIP-61 and SIP-63 were discussed but no vote was held.
diff --git a/_sips/results/2024-05-24-meeting.md b/_sips/results/2024-05-24-meeting.md
new file mode 100644
index 0000000000..51bf1e0a34
--- /dev/null
+++ b/_sips/results/2024-05-24-meeting.md
@@ -0,0 +1,10 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 24th May 2024
+partof: results
+proposals:
+ - url: https://github.com/scala/improvement-proposals/pull/78
+ name: SIP-61 - Unroll default arguments for binary compatibility
+ result: accepted
+---
+SIP-64 was discussed but no vote was held.
diff --git a/_sips/results/2024-06-21-meeting.md b/_sips/results/2024-06-21-meeting.md
new file mode 100644
index 0000000000..9ebb1ca250
--- /dev/null
+++ b/_sips/results/2024-06-21-meeting.md
@@ -0,0 +1,10 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 21st June 2024
+partof: results
+proposals:
+ - url: https://github.com/scala/improvement-proposals/pull/47
+ name: SIP-47 - Clause interleaving
+ result: accepted
+---
+SIP-55, SIP-58, SIP-60, SIP-62, and SIP-64 were discussed but no vote was held.
diff --git a/_sips/results/2024-08-16-meeting.md b/_sips/results/2024-08-16-meeting.md
new file mode 100644
index 0000000000..73361aa923
--- /dev/null
+++ b/_sips/results/2024-08-16-meeting.md
@@ -0,0 +1,7 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 16th August 2024
+partof: results
+proposals: []
+---
+SIP-49, SIP-52, SIP-57, SIP-58, SIP-61, SIP-62, SIP-64, and SIP-66 were discussed but no vote was held.
diff --git a/_sips/results/2024-09-27-meeting.md b/_sips/results/2024-09-27-meeting.md
new file mode 100644
index 0000000000..bbb0bb8b81
--- /dev/null
+++ b/_sips/results/2024-09-27-meeting.md
@@ -0,0 +1,13 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 27th September 2024
+partof: results
+proposals:
+ - url: https://github.com/scala/improvement-proposals/pull/72
+ name: SIP-58 - Named Tuples
+ result: accepted
+ - url: https://github.com/scala/improvement-proposals/pull/81
+ name: SIP-64 - Improve the syntax of context bounds and givens
+ result: accepted
+---
+SIP-62 was discussed but no vote was held.
diff --git a/_sips/results/2024-11-15-meeting.md b/_sips/results/2024-11-15-meeting.md
new file mode 100644
index 0000000000..1a5da82052
--- /dev/null
+++ b/_sips/results/2024-11-15-meeting.md
@@ -0,0 +1,7 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 15th November 2024
+partof: results
+proposals: []
+---
+SIP-66 was discussed but no vote was held.
diff --git a/_sips/results/2024-12-20-meeting.md b/_sips/results/2024-12-20-meeting.md
new file mode 100644
index 0000000000..a9454f3250
--- /dev/null
+++ b/_sips/results/2024-12-20-meeting.md
@@ -0,0 +1,7 @@
+---
+layout: sip-meeting-results
+title: SIP Meeting Results - 20th December 2024
+partof: results
+proposals: []
+---
+SIP-62 and SIP-67 were discussed but no vote was held.
diff --git a/_sips/sip-submission.md b/_sips/sip-submission.md
deleted file mode 100644
index 1d7d1d0609..0000000000
--- a/_sips/sip-submission.md
+++ /dev/null
@@ -1,332 +0,0 @@
----
-layout: sips
-title: SIP Specification and Submission
----
-
-A **SIP** (_Scala Improvement Process_) is a process for submitting changes to
-the Scala language. Its main motivation is to become the primary mechanism to
-propose, discuss and implement language changes. In this process, all changes to
-the language go through design documents, called Scala Improvement Proposals
-(SIPs), which are openly discussed by a committee and only upon reaching a
-consensus are accepted to be merged into the Scala compiler.
-
-The aim of the Scala Improvement Process is to apply the openness and
-collaboration that have shaped Scala's documentation and implementation to the
-process of evolving the language. This document captures our guidelines,
-commitments and expectations regarding this process.
-
-## Why write a SIP?
-
-SIPs are key to making Scala better for the good of everyone. If you decide to
-invest the time and effort of putting a SIP forward and seeing it through, your
-efforts and time will shape and improve the language, which means that your
-proposal may impact the life of a myriad of developers all over the world,
-including those on your own team. For many, this aspect alone can be quite
-worthwhile.
-
-However, it's important to note that seeing a SIP through to its conclusion is
-an involved task. On the one hand, it takes time to convince people that your
-suggestions are a worthwhile change for hundreds of thousands of developers to
-accept. Particularly given the sheer volume of developers that could be affected
-by your SIP, SIP acceptance is conservative and carefully thought through.
-Typically, this includes many rounds of discussion with core Scala maintainers
-and the overall community, several iterations on the design of the SIP, and some
-effort at prototyping the proposed change. Often, it takes months of discussion,
-re-design, and prototyping for a SIP to be accepted and included in the Scala
-compiler. It is, therefore important to note that seeing a SIP through to its
-conclusion can be time-consuming and not all SIPs may end up in the Scala
-compiler, although they may teach us all something!
-
-If you’re motivated enough to go through this involved but rewarding process, go
-on with writing and keep on reading.
-
-## What's the process for submitting a SIP?
-
-There are four major steps in the SIP process:
-
-1. Initial informal discussion (2 weeks)
-2. Submission
-3. Formal presentation (up to 1 month)
-4. Formal evaluation (up to 6 months)
-
-### Initial informal discussion (2 weeks)
-
-Before submitting a SIP, it is required that you perform necessary preparations:
-
-Discuss your idea on the [Scala Contributors Page](https://contributors.scala-lang.org/) (currently, we suggest
-cross-posting on
-[Scala Improvement Process](https://contributors.scala-lang.org/c/sip) and
-[Language Design](https://contributors.scala-lang.org/c/language-design). This
-may change in the future.) Create a topic that starts with “Pre-SIP” and briefly
-describe what you would like to change and why you think it’s a good idea.
-
-Proposing your ideas on the mailing list is not an optional step. For every
-change to the language, it is important to gauge interest from the compiler
-maintainers and the community. Use this step to promote your idea and gather
-early feedback on your informal proposal. It may happen that experts and
-community members may have tried something similar in the past and may offer
-valuable advice.
-
-Within two weeks after your submission of the pre-SIP to the mailing list, the
-Process Lead will intervene and advise you whether your idea can be submitted as
-a SIP or needs more work.
-
-### Submission
-
-After receiving the green light from the Process Lead, you can write up your
-idea and submit it as a SIP.
-
-A SIP is a Markdown document written in conformance with the [process template](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md).
-It ought to contain a clear specification of the proposed changes. When such
-changes significantly alter the compiler internals, the author is invited to
-provide a proof of concept. Delivering a basic implementation can speed up the
-process dramatically. Even compiler hackers find very difficult to predict the
-interaction between the design and the implementation, so the sooner we have an
-evidence of a working prototype that interacts with all the features in Scala,
-the better. Otherwise, committee members may feel that the proposed changes are
-impossible and automatically dismiss them. If your changes are big or somewhat
-controversial, don’t let people hypothesize about them and show results upfront.
-
-A SIP is submitted as a pull request against [the official Scala website
-repo](https://github.com/scala/docs.scala-lang). Within a week of receiving the
-pull request, the Process Lead will acknowledge your submission, validate it and
-engage into some discussions with the author to improve the overall quality of
-the document (if necessary).
-
-When you and the Process Lead agree on the final document, it is formally
-accepted for review: assigned a reviewer and scheduled for formal presentation.
-
-### Formal presentation (up to 1 month)
-
-During the next available SIP Committee meeting, the appointed reviewer presents
-the SIP to the committee and kick starts the initial discussion.
-
-If the committee agrees that following through the SIP is a good idea, then the
-following happens:
-
-1. The SIP is assigned a number.
-2. The SIP pull request is merged into the official Scala website repo, and the
-merged document becomes the official webpage of the proposal.
-3. An issue to discuss the SIP is opened at the official Scala website repo. Then,
-the reviewer submits the initial feedback from the committee.
-4. An implementation is requested (if not already present).
-
-Otherwise, the SIP is rejected. The reviewer submits the collected feedback as a
-comment to the pull request, and the pull request is closed.
-
-### Formal evaluation (up to 6 iterations)
-
-Evaluation of a SIP is done in iterations. The maximum number of iterations is
-six. These iterations take place in the SIP meetings and are usually monthly.
-However, they can last longer, in which case the author has more time to
-implement all the required changes.
-
-The committee decides the duration of the next iteration depending upon the
-feedback and complexity of the SIP. Consequently, authors have more time to
-prepare all the changes. If they finish their revision before the scheduled
-iteration, the Process Lead will reschedule it for the next available meeting.
-
-During every iteration, the appointed reviewer presents the changes (updated
-design document, progress with the implementation, etc) to the SIP Committee.
-Based on the feedback, the SIP is either:
-
-1. Accepted, in which case the committee asks the compiler maintainers to
- indicate the earliest version of Scala that can include the language change.
-2. Rejected, in which case the SIP is closed and no longer evaluated in the
- future.
-3. Under revision, in which case the author needs to continue the formal
- evaluation and address all the committee's feedback. Thus, the follow-up
- discussion is scheduled for the next iteration.
-3. Postponed, in which case the committee does not evaluate the proposal anymore
- and sets it aside under some conditions are met. Then, the SIP will be
- resubmitted. This situation happens when proposals entirely depend on another
- pending proposals and need their admission. In such cases, the dependent
- proposal is postponed until the Committee votes on the other one.
-
-If no changes have been made to a SIP in two iterations, it’s marked as dormant
-and both the PR and issue are closed. Dormant SIPs can be reopened by any
-person, be it the same or different authors, at which point it will start from
-the formal evaluation phase.
-
-### Merging the proposal
-
-If the SIP is accepted, the committee will propose a release date to
-the compiler maintainers, where the role of the committee ends.
-(Compiler maintainers may choose to merge changes under a flag
-initially, for testing, or directly, as they deem appropriate,
-taking committee and community feedback into consideration.)
-
-## Structure of the process
-
-The SIP process involves the following parties:
-
-1. The SIP Author(s)
-2. The Process Lead
-3. The SIP Committee
-
-### The SIP Author(s)
-
-Authors are responsible for building consensus within the community and
-documenting dissenting opinions before the SIP is officially discussed by the
-SIP Committee. Their goal is to convince the committee that their proposal is
-useful and addresses pertinent problems in the language as well as interactions
-with already existing features. Authors can change over the life-cycle of the
-SIP.
-
-### The Process Lead
-
-The Process Lead is the responsible of the smooth running of SIPs and SLIPs. He
-or she appoints the committee members, calls the meetings monthly, assigns new
-proposals to the members, and ensures that all of them are discussed within a
-short period of time.
-
-### The SIP Committee
-
-The SIP Committee is an experienced group of people with knowledge of the
-compiler internals, responsible for the strategic direction of Scala. Members
-are tasked with (a) communicating with the community, (b) weighing in pros and
-cons of every proposal, and (c) accepting, postponing or rejecting the proposal.
-
-Committee members should be either individuals responsible for a specific part
-of the Scala codebase, committers or contributors of the Scala compiler.
-Exceptionally, members may also be important representatives of the community
-with a high technical knowledge to understand the implications of every proposal
-and participate into the discussions. New members are elected by existing
-members of the SIP Committee, based on their expertise and involvement in the
-community.
-
-The current committee members are:
-
-- Martin Odersky ([@odersky](https://github.com/odersky)), EPFL
-- Adriaan Moors ([@adriaanm](https://github.com/adriaanm)), Lightbend
-- Guillaume Martres ([@smarter](https://github.com/smarter)), EPFL
-- Heather Miller ([@heathermiller](https://github.com/heathermiller)), Carnegie Mellon University
-- Iulian Dragos ([@dragos](https://github.com/dragos)), Triplequote
-- Josh Suereth ([@jsuereth](https://github.com/jsuereth)), Google
-- Miles Sabin ([@milessabin](https://github.com/milessabin)), independent
-- Seth Tisue ([@SethTisue](https://github.com/SethTisue)), Lightbend
-- Sébastien Doeraene ([@sjrd](https://github.com/sjrd)), Scala Center
-
-The current Process Lead is:
-
-- Darja Jovanovic ([@darjutak](https://github.com/darjutak)), Scala Center
-
-### Reviewers
-
-The Process Lead assigns every proposal to a member of the committee, who
-becomes the reviewer. The main tasks of the reviewer are the following:
-
-1. Discuss unclear points with the authors,
-2. Help them address their issues and questions,
-3. Provide them feedback from the discussions in the meetings, and
-4. Explain the latest progress in every meeting.
-
-### SIP meetings
-
-SIP meetings are scheduled monthly by the Process Lead, and require a quorum of
-two-thirds (2/3) of the committee members. If the quorum is not reached the
-meeting is rescheduled.
-
-### Voting
-
-All SIP Committee members vote. They can either vote in the meeting or by
-casting their vote via email to the SIP Process Lead before the set deadline.
-
-SIP Committee members can vote "in favor", "against" or "abstain".
-
-For a SIP to be accepted, the following three requirements must be met:
-
-- At least 50% of the committee members vote in favor.
-- There are at least two-thirds "in favor" versus "against" votes.
-- Martin Odersky does not veto it.
-
-An alternative way to think of the two-thirds requirement is that the number of
-votes in favor must be at least twice the number of votes against. Abstentions
-are excluded in calculating a two-thirds vote.
-
-Note that, when calculating the lower bound, numbers round up. Therefore for a
-committee of 9 members, at least 50% means at least 5 members.
-
-The deadline to vote a proposal is decided on a case-by-case basis. The deadline
-will be decided by the committee members present at the last meeting and the SIP
-Process Lead, and will be made public right after the meeting.
-
-#### Examples
-
-Several voting situations are explained next.
-
-All of them assume that there are 9 committee members. The 50% requirement
-requires at least 5 members to vote in favor. We also assume that Martin does
-not veto them.
-
-| In favor | Against | Abstentions | Voting members | Result |
-| -------- | ------- | ----------- | -------------- | ------------ |
-| 6 | 2 | 1 | 8 | Accepted |
-| 5 | 3 | 1 | 8 | Not Accepted |
-| 5 | 2 | 2 | 7 | Accepted |
-
-In the first situation, the proposal is accepted because 6 is both greater than
-the 50% (5) and more than twice the votes against (2). In the second situation,
-the proposal meets the 50% requirement but fails the two-thirds requirement
-since 5 is less than twice the number of votes against, 3, therefore the
-proposal is not accepted. In the third situation, the proposal is accepted
-because 5 is equal to 50% of all the committee members and is greater than twice
-the number of votes against (2).
-
-### Responsibilities of the members
-
-- Review the proposals they are assigned to. The Process Lead will always notify
-them two weeks in advance, at minimum.
-- Play a role in the discussions, learn in advance about the topic if needed, and
-make up their mind in the voting process.
-- Decide which utilities should be inside the core module and are required by the
-compiler. The goal is to shrink it over time, and, where possible, move modules
-to the platform, that will be managed by the SLIP process.
-
-### Guests
-
-Experts in some fields of the compiler may be invited to concrete meetings as
-guests when discussing related SIPs. Their input would be important to discuss
-the current state of the proposal, both its design and implementation.
-
-## Proposal states
-
-The state of a proposal changes over time depending on the phase of the process
-and the decisions taken by the committee. A given proposal can be in one of
-several states:
-
-1. **Validated:** The Process Lead has validated the proposal and checked that
-meets all the formal requirements.
-2. **Numbered:** The committee agrees that the proposal is a valid document and
-it’s worth considering it. Then, the Process Lead gives it a number.
-3. **Awaiting review:** The proposal has been scheduled to be reviewed for a
-concrete date.
-4. **Under review:** Once the author has delivered a new version, the proposal will
-be under review until the next available SIP meeting takes place.
-5. **Under revision:** Authors are addressing the issues pinpointed by the
-committee or working on the implementation.
-6. **Dormant:** When a SIP has been under revision for more than two iterations
- and no progress has been made, the Process Lead will mark it as dormant (note
- that the committee does not have such privilege). This status means that the
- Process Lead will not assign its review in future meetings until authors
- provide the requested feedback or progress. Also, authors can also mark their
- proposals as dormant, and they are encouraged to do so if they think they
- will not have time for their update.
-7. **Postponed:** The SIP has been postponed under some concrete conditions. When these
-are met, the SIP can be resubmitted.
-8. **Rejected:** The SIP has been rejected with a clear and full explanation.
-9. **Accepted:** The SIP has been accepted and it’s waiting for the merge into the
-Scala compiler.
-
-## How do I submit? ##
-
-The process to submit is simple:
-
-* Fork the Scala documentation repository, [https://github.com/scala/docs.scala-lang](https://github.com/scala/docs.scala-lang).
-* Create a new SIP file in the `_sips/sips/`. Use the [S(L)IP template](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md)
- * Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`.
- * Use the [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax) to write your SIP.
- * Follow the instructions in the [README](https://github.com/scala/docs.scala-lang/) to build your SIP locally so you can ensure that it looks correct on the website.
-* Create a link to your SIP in the "pending sips" section of `index.md`
-* Commit your changes to your forked repository
-* Create a new [pull request](https://github.com/scala/docs.scala-lang/pull/new/gh-pages). This will notify the Scala SIP team.
diff --git a/_sips/sip-template.md b/_sips/sip-template.md
deleted file mode 100644
index b3caf4e276..0000000000
--- a/_sips/sip-template.md
+++ /dev/null
@@ -1,119 +0,0 @@
----
-layout: sip
-title: SIP-NN - SIP Title
-#vote-status: pending <- uncomment this line
-permalink: /sips/:title.html
-redirect_from: /sips/pending/{filename-without-md}.html
----
-
-**By: Author 1 and Author 2 and Author 3**
-
-This document is provided as a template to get you started. Feel free to add, augment,
-remove, restructure and otherwise adapt the structure for what you need after cloning it.
-The cloned document should be placed in sips/pending/_posts according to the naming
-conventions described in the [SIP tutorial](./sip-tutorial.html).
-
-## History
-
-| Date | Version |
-|---------------|---------------|
-| Feb 19th 2015 | Initial Draft |
-| Feb 20th 2015 | Alteration Details |
-
-## Introduction/Motivation/Abstract
-
-(feel free to rename this section to Introduction, Motivation, Abstract, whatever best suits
- your library proposal.)
-
-A high level overview of the library with:
-
-* Description of the scope/features of the library.
-* An explanation of the reason the library is needed, what's missing in the core libs
- that is supplied.
-* Simple code examples if they help clarify, note that there will be ample opportunity
- for more detailed code examples later in the SIP
-
-Think of the introduction as serving to describe the library addition in a way
-that lets a reader decide if this is what they are looking for, whether they think
-this is the right approach to supply the extra functionality, and whether they might
-want to get involved.
-
-## Motivating Examples
-
-### Examples
-
-Code heavy description of how the library functionality can be used.
-
-```scala
-// here is some example scala code, highlighted nicely
-import scala.concurrent._
-
-class Foo extends Bar {
- val x = 10
- def yo(name: String): String = s"hello $name"
-}
-```
-
-### Comparison Examples
-
-Code demonstrating why the library is needed, how equivalent functionality
-might be provided without it.
-
-### Counter-Examples
-
-What the library is not intended to be used for. Examples of what to avoid and
-why.
-
-## Design
-
-Discuss design decisions (including, as examples):
-
-* Reason about correctness of the implementation.
-* "Feel and fit" with existing core libraries.
-* Performance and threading considerations.
-* Naming of classes, traits, methods.
-* Footprint of API.
-* Potential conflicts with existing libraries, e.g. name clashes, IDE auto-import friction, etc.
-
-## Implementation
-
-Include consideration of the following:
-
-* Is this library intended to be bundled with the current core libs, or (recommended) live in
-a separate module distributed with the core distribution of Scala
-(e.g. parser combinators, reflection, etc.)
-* **Existing implementation(s)** (e.g. donor library, github project, etc.). Note that
-having an existing implementation library from which this will be drawn, and that people
-can download and try now, is highly recommended.
-* Time frame, target Scala version for inclusion.
-* Roll-out plan (start with external module, include in std distribution, move to core).
-* Other volunteers/contributors (with areas of expertise, github contact info, etc.)
-
-## Counter-Examples
-
-What the library is not intended to be used for. Examples of what to avoid and
-why.
-
-## Drawbacks
-
-Why should we *not* do this. Be honest, these questions will come out during the
-process anyway so it's better to get them out up front.
-
-## Alternatives
-
-* What other possibilities have been examined?
-* What is the impact of not implementing this proposal?
-
-## References
-
-1. [Existing (Donor) Project][1]
-2. [API Documentation][2]
-3. [Academic/Research papers/supporting material][3]
-4. [Alternative Libraries/Implementations][4]
-5. [Discussion forum/post/gitter/IRC][5]
-
-[1]: https://github.com "GitHub"
-[2]: https://www.scala-lang.org/api/ "Scaladoc"
-[3]: https://en.wikipedia.org/wiki/Academic_publishing "Academic/Research"
-[4]: https://github.com/dogescript/dogescript "Alternatives"
-[5]: https://gitter.im "Gitter"
diff --git a/_sips/sip-tutorial.md b/_sips/sip-tutorial.md
index 2696fd12af..95bb45b053 100644
--- a/_sips/sip-tutorial.md
+++ b/_sips/sip-tutorial.md
@@ -1,51 +1,90 @@
---
layout: sips
title: Writing a new SIP
+redirect_from: /sips/sip-template.html
---
-This tutorial details of how to write a new SIP and adding it to the website.
+This tutorial details of how to write a new Scala Improvement Proposal (SIP) and how to submit it.
+
+## Why write a SIP?
+
+SIPs are key to making Scala better for the good of everyone. If you decide to
+invest the time and effort of putting a SIP forward and seeing it through, your
+efforts and time will shape and improve the language, which means that your
+proposal may impact the life of a myriad of developers all over the world,
+including those on your own team. For many, this aspect alone can be quite
+worthwhile.
+
+However, it's important to note that seeing a SIP through to its conclusion is
+an involved task. On the one hand, it takes time to convince people that your
+suggestions are a worthwhile change for hundreds of thousands of developers to
+accept. Particularly given the sheer volume of developers that could be affected
+by your SIP, SIP acceptance is conservative and carefully thought through.
+
+It is important to note that seeing a SIP through to its
+conclusion can be time-consuming and not all SIPs may end up in the Scala
+compiler, although they may teach us all something!
+
+Last, but not least, delivering a basic implementation can speed up the
+process dramatically. Even compiler hackers find very difficult to predict the
+interaction between the design and the implementation, so the sooner we have an
+evidence of a working prototype that interacts with all the features in Scala,
+the better.
+
+If you’re motivated enough to go through this involved but rewarding process, go
+on with writing and keep on reading.
+
+The following sections provide an overview of the process, and guidelines on
+how to submit a proposal. The detailed process specification is available
+[here]({% link _sips/process-specification.md %}).
+
+## Overview of the process
+
+From being an idea to being part of the language, a SIP goes through several
+*stages* that indicate the “maturity” level of the SIP. The following diagram
+summarizes the purpose of each stage:
+
+
+
+0. **Pre-SIP** You should start by creating a discussion thread in the
+ [Scala Improvement Process](https://contributors.scala-lang.org/c/sip/13)
+ category of the Scala Contributors forum to gather initial community feedback
+ and support. The title of your discussion should start with "Pre-SIP". In
+ this discussion, the community might bring you alternative solutions to
+ the problem you want to solve, or possible bad interactions with other
+ features of the language. Eventually, these discussions may help you polish
+ your proposal.
+1. **Design** The next stage consists of submitting a detailed description of
+ your proposal for approval to the SIP Committee. See the section
+ [How do I submit?](#how-do-i-submit) to know the procedure and expected
+ format. Your proposal will first be reviewed by a small group of reviewers,
+ and eventually the full Committee will either approve it or reject it.
+2. **Implementation** If the Committee approved your proposal, you are
+ welcome to provide an implementation of it in the compiler so that it can
+ be shipped as an experimental feature. You may hit new challenges during the
+ implementation of the feature, or when testing it in practice. In such a
+ case, you should amend the proposal, which will be reviewed again by the
+ reviewers from the SIP Committee. Once the implementation is deemed stable,
+ the full Committee will vote again on the final state of the proposal.
+3. **Completed** If the Committee accepted the proposal, it will be shipped as
+ a stable feature in the next minor release of the compiler. The content of
+ the proposal may not change anymore.
## How do I submit? ##
-The process to submit is simple:
+The process to submit is the following:
-* Fork the [Scala documentation repository](https://github.com/scala/docs.scala-lang) and clone it.
-* Create a new SIP file in the `_sips/sips`. Use the [SIP template](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md)
- * Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Use the proposal date for `YYYY-MM-dd`.
+* Fork the [Scala improvement proposals repository](https://github.com/scala/improvement-proposals) and clone it.
+* Create a new branch off the `main` branch.
+* Copy the [SIP template](https://github.com/scala/improvement-proposals/blob/main/sip-template.md) into the directory `content/`
+ * Give a meaningful name to the file (e.g., `eta-expansion-of-polymorphic-functions.md`).
* Use the [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax) to write your SIP.
- * Follow the instructions in the [README](https://github.com/scala/docs.scala-lang/blob/master/README.md) to build your SIP locally so you can ensure that it looks correct on the website.
-* Create a link to your SIP in the "pending sips" section of `index.md`.
+ * The template is provided to help you get started. Feel free to add, augment, remove, restructure and otherwise adapt the structure for what you need.
* Commit your changes and push them to your forked repository.
-* Create a new pull request. This will notify the Scala SIP team.
-
-
-## SIP Post Format ##
-
-First, create a new SIP file in the `_sips/sips` directory. Make sure the new file follows the format: `YYYY-MM-dd-{title}.md`. Where:
-* `YYYY` is the current year when the proposal originated.
-* `MM` is the current month (`01` = January, `12` = December) when the proposal originated.
-* `dd` is the day of the month when the proposal originated.
-* `{title}` is the title for the SIP.
+* Create a new pull request. This will notify the Scala SIP team, which will get back to you within a couple of weeks.
### Markdown formatting ###
Use the [Markdown Syntax](https://daringfireball.net/projects/markdown/syntax) to write your SIP.
-If you would like a starting point, clone the [SIP Template](./sip-template.html) in
-`_sips/sip-template.md` and use that.
-
-See the [source](https://github.com/scala/docs.scala-lang/blob/master/_sips/sip-template.md) for this document (`sip-tutorial.md`) for how to do syntax highlighting.
-
-```scala
-class Foo
-```
-
-
-## Testing changes ##
-
-Testing changes requires installing [Jekyll](https://jekyllrb.com/docs/installation/). Since this site is hosted on github pages, make sure you have [whatever version of Jekyll that github is running](https://help.github.com/articles/using-jekyll-with-pages#troubleshooting). As of the writing of this README, that is version >= 1.0.x.
-
-After the installation, you need to start up the local server. The
-[README](https://github.com/scala/docs.scala-lang/blob/master/README.md) gives
-a concise explanation on how to do it. When the server is running, view your
-changes at [https://localhost:4000/sips](https://localhost:4000/sips).
+See the content of the [SIP template](https://github.com/scala/improvement-proposals/blob/main/sip-template.md) as a starting point, and for various examples, including syntax highlighting of code snippets.
diff --git a/_sips/sips/2011-10-13-uncluttering-control.md b/_sips/sips/2011-10-13-uncluttering-control.md
deleted file mode 100644
index e1ceb5d790..0000000000
--- a/_sips/sips/2011-10-13-uncluttering-control.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-layout: sip
-title: SIP-12 - Uncluttering Scala’s syntax for control structures.
-
-vote-status: rejected
-vote-text: The committee votes unanimously to reject the change. The conclusion is that there is not a clear benefit for it and the required invested time and efforts would be too high. For more explanation, read the minutes.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/uncluttering-control.html
----
-
-**By: Martin Odersky**
-
-## Motivation ##
-
-The more Scala code I write the more I get tripped up by the need to write conditions in if-then-else expressions and other control constructs in parentheses. I normally would not advocate syntax changes at this level, except that this has been the single syntax decision that feels worse for me the longer I use it.
-
-## Part 1: if ##
-
-Having to write parentheses is an unfortunate inheritance from C via Java. It makes code more cluttered than it could be. In C/C++/Java this was no big deal, but because Scala is much cleaner syntactically than these languages it starts to stick out like a sore thumb. This in particular because only one form of `if` comes with parentheses; if you use an if as a filter in a for expression or as a guard in a pattern, no parentheses are required.
-
-So, here is the proposal (for Scala 2.10):
-
-1. Introduce a new keyword, `then`.
-
-2. Allow the following alternative syntax form:
-
- if expression then expression [else expression]
-
-3. At some point in the future (there’s no rush) we could deprecate the form
-
- if (expression) expression else expression
-
- and then remove it.
-
-
-Once we have dealt with if, we should do the same thing with while, do-while and for.
-
-## Part 2: do-while ##
-
-do-while is easy. Simply do the following:
-
-1. Allow
-
- do expression while expression
-
- as syntax (i.e. drop the required parentheses around the condition).
-
-While loops and for loops are more tricky.
-
-## Part 3: while ##
-
-For while loops:
-
-1. Allow
-
- while expression do expression
-
- as syntax.We then have to deal with an ambiguity: What should we do with
-
- while (expression1) do expression2 while (expression3)
-
- ? I.e. a `do-while` loop inside an old-style `while` loop? Here’s a possible migration strategy.
-
-2. In Scala 2.10: Introduce
-
- while expression1 do expression2
-
- where `expression1` is not allowed to have parentheses at the outermost level (there’s no need to have them anyway). Also, emit a deprecation warning if the compiler comes across a do-while nested directly in an old-style while:
-
- while (expression1) do expression2 while expression3
-
- To write a `do-while` inside a `while` loop you will need braces, like this:
-
- while (expression1) { do expression2 while expression3 }
-
-3. In Scala 2.11: Disallow
-
- while (expression1) do expression2 while expression3
-
-4. In Scala 2.12: Drop the restriction introduced in 2.10. Conditions in a `while-do` can now be arbitrary expressions including with parentheses at the outside.
-
-## Part 4: for ##
-
-For-loops and for expressions can be handled similarly:
-
-1. Allow
-
- for enumerators yield expression
-
- as syntax. Enumerators are treated as if they were in braces, i.e. newlines can separate generators without the need for additional semicolons.
-
-2. Allow
-
- for enumerators do expression
-
- as syntax. Treat `do-while` ambiguities as in the case for `while`.
-
-3. At some point in the future: deprecate, and then drop the syntax
-
- for (enumerators) expression
- for {enumerators} expression
- for (enumerators) yield expression
- for {enumerators} yield expression
-
-## Examples ##
-
-Here are some examples of expressions enabled by the changes.
-
- if x < y then x else y
-
- while x >= y do x /= 2
-
- for x <- 1 to 10; y <- 1 to 10 do println(x * y)
-
- for
- x <- 0 until N
- y <- 0 until N
- if isPrime(x + y)
- yield (x, y)
-
-## Discussion ##
-
-The new syntax removes more cases than it introduces. It also removes several hard to remember and non-orthogonal rules where you need parentheses, where you can have braces, and what the difference is. It thus makes the language simpler, more regular, and more pleasant to use. Some tricky situations with migration can be dealt with; and should apply anyway only in rare cases.
diff --git a/_sips/sips/2012-03-09-self-cleaning-macros.md b/_sips/sips/2012-03-09-self-cleaning-macros.md
deleted file mode 100644
index 32d50df49f..0000000000
--- a/_sips/sips/2012-03-09-self-cleaning-macros.md
+++ /dev/null
@@ -1,16 +0,0 @@
----
-layout: sip
-title: SIP-16 - Self-cleaning Macros
-
-vote-status: rejected
-vote-text: The proposal is rejected unanimously because Scala Meta, the successor metaprogramming tool, is coming soon. For more explanation, read the minutes.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/self-cleaning-macros.html
----
-
-
-This SIP is an embedded google document. If you have trouble with this embedded document, you can visit the [document on Google Docs](https://docs.google.com/document/d/1O879Iz-567FzVb8kw6N5OBpei9dnbW0ZaT7-XNSa6Cs/edit?hl=en_US).
-
-
diff --git a/_sips/sips/2012-03-30-source-locations.md b/_sips/sips/2012-03-30-source-locations.md
deleted file mode 100644
index b80c95b23b..0000000000
--- a/_sips/sips/2012-03-30-source-locations.md
+++ /dev/null
@@ -1,66 +0,0 @@
----
-layout: sip
-title: SIP-19 - Implicit Source Locations
-vote-status: rejected
-vote-text: The proposal is rejected. We expect this to be easily implemented using macros without going through a full SIP. A modern implementation can be found here.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/source-locations.html
----
-
-**Philipp Haller**
-
-**30 March 2012**
-
-## Motivation ##
-
-The Scala compiler's error messages would be nearly useless if they wouldn't provide the corresponding source location, that is, file name, line number, and (some representation of the) character offset, of each error. However, source locations are also very useful outside of the compiler. Libraries and frameworks routinely deal with application- or system-level errors (usually in the form of exceptions), logging, debugging support through tracing, etc. All of these aspects greatly benefit from source location information.
-
-Moreover, embedded domain-specific languages often depend upon source location information for providing useful error messages. Domain-specific languages that employ staging for code generation can use source locations for debug information in the generated code.
-
-This proposal discusses a minimal extension of Scala's implicit parameters to provide access to the source location of method invocations. The design is analogous to the way manifests are generated by the compiler, and should therefore be natural to anyone familiar with manifests in Scala.
-
-## Example ##
-
-To obtain the source location for each invocation of a method `debug`, say, one adds an implicit parameter of type `SourceLocation`:
-
- def debug(message: String)(implicit loc: SourceLocation): Unit = {
- println("@" + loc.fileName + ":" + loc.line + ": " + message)
- }
-
-This means that inside the body of the `debug` method, we can access the source location of its current invocation through the `loc` parameter. For example, suppose
-we are invoking `debug` on line `34` in a file `"MyApp.scala"`:
-
- 34: if (debugEnabled) debug("debug message")
-
-Assuming `debugEnabled` evaluates to `true`, the above expression would lead to the following output:
-
- @MyApp.scala:34: debug message
-
-## The SourceLocation Trait ##
-
-The `SourceLocation` trait is a new type member of the `scala.reflect` package. It has the following members:
-
- trait SourceLocation {
- /** The name of the source file */
- def fileName: String
-
- /** The line number */
- def line: Int
-
- /** The character offset */
- def charOffset: Int
- }
-
-## Specification ##
-
-Implicit source locations are supported through the following small addition to Scala's implicit rules.
-
-If an implicit parameter of a method or constructor is of type `SourceLocation`, a source location object is determined according to the following rules.
-
-First, if there is already an implicit argument of type `SourceLocation`, this argument is selected. Otherwise, an instance of `SourceLocation` is generated by invoking the `apply` method of the object `scala.reflect.SourceLocation`, passing the components of the source location as arguments.
-
-## Implementation ##
-
-An implementation of this proposal can be found at: [https://github.com/phaller/scala/tree/topic/source-location](https://github.com/phaller/scala/tree/topic/source-location)
-
-An extension of this proposal is also part of Scala-Virtualized. The extension adds a subtrait `SourceContext` which in addition provides access to information, such as variable names in the context of a method invocation. More information can be found at: [https://github.com/TiarkRompf/scala-virtualized/wiki/SourceLocation-and-SourceContext](https://github.com/TiarkRompf/scala-virtualized/wiki/SourceLocation-and-SourceContext)
diff --git a/_sips/sips/2013-05-31-improved-lazy-val-initialization.md b/_sips/sips/2013-05-31-improved-lazy-val-initialization.md
deleted file mode 100644
index 1efe9e9eab..0000000000
--- a/_sips/sips/2013-05-31-improved-lazy-val-initialization.md
+++ /dev/null
@@ -1,749 +0,0 @@
----
-layout: sip
-title: SIP-20 - Improved Lazy Vals Initialization
-vote-status: dormant
-vote-text: This proposal lacks an implementation for Scalac and is looking for a new owner.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/improved-lazy-val-initialization.html
----
-
-**By: Aleksandar Prokopec, Dmitry Petrashko, Miguel Garcia, Jason Zaugg, Hubert Plociniczak, Viktor Klang, Martin Odersky**
-
-
-## Abstract ##
-
-This SIP describes the changes in the lazy vals initialization mechanism that address some of the unnecessary deadlock scenarios. The newly proposed lazy val initialization mechanism aims to eliminate the acquisition of resources during the execution of the lazy val initializer block, thus reducing the possibility of a deadlock. The concrete deadlock scenarios that the new lazy val initialization scheme eliminates are summarized below.
-
-The changes in this SIP have previously been discussed in depth on the mailing lists \[[1][1]\] \[[2][2]\] \[[9][9]\] \[[10][10]\].
-
-
-## Description ##
-
-The current lazy val initialization scheme uses double-checked locking to initialize the lazy val only once. A separate volatile bitmap field is used to store the state of the lazy val - a single bit in this bitmap denotes whether the lazy val is initialized or not.
-Assume we have the following declaration.
-
- final class LazyCell {
- lazy val value =
- }
-
-Here is an example of a manually written implementation equivalent to what the compiler currently does:
-
- final class LazyCell {
- @volatile var bitmap_0: Boolean = false
- var value_0: Int = _
- private def value_lzycompute(): Int = {
- this.synchronized {
- if (!bitmap_0) {
- value_0 =
- bitmap_0 = true
- }
- }
- value_0
- }
- def value = if (bitmap_0) value_0 else value_lzycompute()
- }
-
-We now describe several deadlock scenarios in an attempt to classify deadlocks related to the current lazy val initialization implementation.
-
-### No circular dependencies ###
-
-Assume there are two objects A and B with lazy vals `a0` and `a1`, and `b`, respectively:
-
- object A {
- lazy val a0 = B.b
- lazy val a1 = 17
- }
-
- object B {
- lazy val b = A.a1
- }
-
-The initialization block of `a0` above refers to `b` in B, and the initialization of `B.b` refers to `A.a1`. While a circular dependency exists between these two objects, there is no circular dependency **between specific lazy vals** `a0`, `a1` and `b`.
-
-In the scheme, there exists a possibility of a deadlock if thread Ta attempts to initialize `A.a0` and thread Tb attempts to initialize `B.b`. Assume that both Ta and Tb start their synchronized blocks simultaneously. A deadlock can occur due to each thread trying to grab the lock of the other object, while holding their own lock until the initialization completes.
-
-This SIP attempts to address this issue.
-
-### Circular dependencies ###
-
-Assume there are two objects A and B with lazy vals `a` and `b` respectively, where `a` needs `b` for initialization and vice versa. The current implementation scheme can cause a deadlock in this situation. Furthermore: in a single threaded scenario, circular dependencies between lazy vals lead to stack overflows with the current implementation:
-
- scala> object Test {
- | object A { lazy val a: Int = B.b }
- | object B { lazy val b: Int = A.a }
- | }
- defined object Test
-
- scala> Test
- res0: Test.type = Test$@6fd1046d
-
- scala> Test.A.a
- java.lang.StackOverflowError
-
-This is considered erroneous code, and this SIP does not attempt to address this.
-
-### No circular dependencies with other synchronization constructs ###
-
-Consider the declaration of the following lazy val:
-
- class A { self =>
- lazy val x: Int = {
- val t = new Thread() {
- override def run() { self.synchronized {} }
- }
- t.start()
- t.join()
- 1
- }
- }
-
-In the source there appears to be no circular dependency between the lazy val initialization block and the other synchronization construct, so there should be no reason for deadlock. As long as thread `t` completes a condition that the caller depends on and eventually lets go of the current object `self`, the lazy val should be able to initialize itself.
-
-With the current initialization scheme, however, initializing `x` causes a deadlock. The calling thread initializing `x`, holds the monitor of the current object `self`. The same monitor is needed by thread `t`, since it also synchronizes on `self`, thus causing a deadlock.
-
-This SIP attempts to address this issue.
-
-The thread that fulfills the condition that the lazy val initializer block suspends on could on the other hand permanently grab a hold of the monitor of the `self` object. Although this is not strictly speaking a deadlock, it is worth mentioning that the current lazy val initialization implementation might not complete in the following scenario case.
-
- class A { self =>
- val latch = new java.util.concurrent.CountDownLatch(1)
- val t = new Thread() {
- override def run() {
- latch.countDown()
- self.synchronized { while (true) {} }
- }
- }
- t.start()
- lazy val x: Int = {
- latch.await()
- 1
- }
- x
- }
-
-This SIP does not attempt to solve this issue - lazy val initialization semantics assume that the `self` object monitor is available or can be made available throughout the lazy val initialization.
-
-### Circular dependencies with other synchronization constructs ###
-
-Consider the declaration of the following lazy val:
-
- lazy val x: Int = {
- val t = new Thread() {
- override def run() { println(x) }
- }
- t.start()
- t.join()
- 1
- }
-
-In this code, the lazy val initialization block suspends until a condition is fulfilled. This condition can only be fulfilled by reading the value of lazy val `x` - another thread that is supposed to complete this condition cannot do so. Thus, a circular dependency is formed, and the lazy val cannot be initialized. Similar problems can arise with Scala singleton object initialization \[[3][3]\] when creating threads from the singleton object constructor and waiting for their completion, and with static initializer blocks in Java \[[4][4]\] \[[5][5]\].
-
-Note that this problem can also happen if two separate threads try to initialize two singleton objects that refer to each other, which is somewhat more severe. The rule of the thumb for programmers should be - singleton objects should not refer to each other during initialization.
-
-This is considered an anti-pattern, and this SIP does not attempt to address these issues.
-
-## Implementation ##
-
-The solution to the problems that this SIP attempts to address is based on avoiding the acquisition of the current object monitor during the time that the lazy val initializer block executes. Instead of executing the initializer block from within a synchronized block, the synchronized block is run twice, once at the beginning to publicize the information that the initializer block is being run and once after the initializer block to publicize the information that the lazy val field has been computed and assigned. The new scheme will require maintaining 2 bits per lazy field instead of 1, as in the current implementation.
-We will refer to the existing, current lazy val initialization implementation as V1.
-
-### Version V2 ###
-
-Here is an example of manually written implementation for the `LazyCell` class from the previous section:
-
- class LazyCell {
- @volatile var bitmap_0: Int = 0
- var value_0: Int = _
- private def value_lzycompute(): Int = {
- this.synchronized {
- if (bitmap_0 == 0) {
- bitmap_0 = 1
- } else {
- while (bitmap_0 == 1) {
- this.wait()
- }
- return value_0
- }
- }
- val result =
- this.synchronized {
- value_0 = result
- bitmap_0 = 3
- this.notifyAll()
- }
- value_0
- }
- def value = if (bitmap_0 == 3) value_0 else value_lzycompute()
- }
-
-The state of the lazy val is represented with 3 values: 0, 1 and 3. Note that only 2 bits are sufficient to represent them but we use an entire integer here for purposes of clarity. The state 0 represents a non-initialized lazy val. The state 1 represents the lazy val that is currently being initialized by some thread. The state 3 represents the lazy val that has been initialized.
-
-The first-arriving thread sets the state 1 from the synchronized block, leaves the synchronized block and proceeds by executing the initializer block. Subsequently arriving threads enter the synchronized block, see state 1 and `wait` until they are notified that the lazy val has been assigned. The first-arriving thread sets the state to 3 and notifies them after it computes the result and enters the second synchronized block.
-
-### Version V3 - the `notifyAll` improvement ###
-
-As noted in the previous discussions \[[1][1]\] \[[2][2]\] \[[6][6]\] \[[7][7]\], the `notifyAll` call in the proposed implementation bears a significant cost - in the uncontended case it slows down the initialization by a factor of at least 4x measured on a 3.4 GHz i7-2600 and JDK 7 update 4.
-
-Therefore, we propose the following implementation that avoids calling `notifyAll` unless the first-arriving thread knows that there are concurrent readers of the lazy val. We introduce the fourth state corresponding to the bitmap value 2, that denotes that there are concurrent readers of the lazy val. The first-arriving thread only calls the `notifyAll` if it finds state 2 in the second synchronized block.
-
- class LazyCell {
- @volatile var bitmap_0 = 0
- var value_0: Int = _
- private def value_lzycompute(): Int = {
- this.synchronized {
- (bitmap_0: @annotation.switch) match {
- case 0 =>
- bitmap_0 = 1
- case 1 =>
- bitmap_0 = 2
- do this.wait() while (bitmap_0 == 2.toByte)
- return value_0
- case 2 =>
- do this.wait() while (bitmap_0 == 2.toByte)
- return value_0
- case 3 =>
- return value_0
- }
- }
- val result =
- this.synchronized {
- val oldstate = bitmap_0
- value_0 = result
- bitmap_0 = 3
- if (oldstate == 2) this.notifyAll()
- }
- value_0
- }
- def value = if (bitmap_0 == 3) value_0 else value_lzycompute()
- }
-
-Measured on the same machine, this change seems to be 50% slower than the current lazy val implementation for the uncontended case.
-
-### Version V4 - the CAS improvement ###
-
-Each exit or entrance to a synchronized block in principle requires one atomic instruction, amounting to roughly 4 atomic instructions per lazy val initialization. This can be reduced by using the CAS instruction to switch between lazy val states.
-Here is an example of a simple implementation obtained by extending the `AtomicInteger` class:
-
- class LazyCell
- extends java.util.concurrent.atomic.AtomicInteger {
- var value_0: Int = _
- @tailrec final def value(): Int = (get: @switch) match {
- case 0 =>
- if (compareAndSet(0, 1)) {
- val result =
- value_0 = result
- if (getAndSet(3) != 1) synchronized { notify() }
- result
- } else value()
- case 1 =>
- compareAndSet(1, 2)
- synchronized {
- while (get != 3) wait()
- notify()
- }
- value_0
- case 2 =>
- synchronized {
- while (get != 3) wait()
- notify()
- }
- value_0
- case 3 => value_0
- }
- }
-
-This implementation has the following advantages:
-- it seems to have the same initialization performance as the current implementation, in the uncontended case
-- it relies less on synchronized blocks, needing them only in case of contention, thus being less prone to deadlocks
-
-Some disadvantages:
-- we cannot always extend `AtomicInteger`, some classes already inherit something else
-- in the contended worst-case, this scheme is equally prone to deadlocks, because it needs to acquire the synchronized block
-
-However, in the more general setting where there are two or more lazy val fields in an object:
-- the overall memory footprint could possibly increase - we would spend a minimum of 4 bytes per bitmap on first lazy val, where this was previously 1 byte
-- in a setting with multiple bitmaps or an existing base class, we cannot extend `AtomicInteger` (which internally uses `Unsafe` directly), and instead need to use `AtomicIntegerFieldUpdater`s that are slower due to extra checks
-- in a setting with multiple lazy val fields, we can no longer use `getAndSet` in the initialization (concurrent accesses to other lazy fields may modify the bitmap - we have to read and recompute the expected bitmap state) - we need a `compareAndSet` and have some retry-logic (see the `complete` method below), which is slower
-- due to the restrictions on the `AtomicIntegerFieldUpdater`s, we would need to make the `bitmap_0` field publicly visible on the byte-code level, which might be an issue for Java code interfacing with Scala code
-- it is much more complicated than the 2 synchronized blocks implementation
-
-Here is a more general implementation(V4-general), that is slower in the uncontended case than both the current implementation (V1) and the proposed implementation with synchronized blocks (V3). This implementation is, however, in the contended case twice as fast than the current implementation (V1).
-See the evaluation section for more information.
-
- class LazyCellBase { // in a Java file - we need a public bitmap_0
- public static AtomicIntegerFieldUpdater arfu_0 =
- AtomicIntegerFieldUpdater.newUpdater(LazyCellBase.class, "bitmap_0");
- public volatile int bitmap_0 = 0;
- }
-
- final class LazyCell extends LazyCellBase {
- import LazyCellBase._
- var value_0: Int = _
- @tailrec final def value(): Int = (arfu_0.get(this): @switch) match {
- case 0 =>
- if (arfu_0.compareAndSet(this, 0, 1)) {
- val result =
- value_0 = result
-
- @tailrec def complete(): Unit = (arfu_0.get(this): @switch) match {
- case 1 =>
- if (!arfu_0.compareAndSet(this, 1, 3)) complete()
- case 2 =>
- if (arfu_0.compareAndSet(this, 2, 3)) {
- synchronized { notifyAll() }
- } else complete()
- }
-
- complete()
- result
- } else value()
- case 1 =>
- arfu_0.compareAndSet(this, 1, 2)
- synchronized {
- while (arfu_0.get(this) != 3) wait()
- }
- value_0
- case 2 =>
- synchronized {
- while (arfu_0.get(this) != 3) wait()
- }
- value_0
- case 3 => value_0
- }
- }
-
-
-### Version 5 - retry in case of failure ###
-
-The current Scala semantics demand retrying the initialization in case of failure.
-The four versions presented above provide good performance characteristics in benchmarks, but may leave threads waiting forever due to failed initializations, thus leaking threads. Consider this example:
-
- class LazyCell {
- private var counter = -1
- lazy val value = {
- counter = counter + 1
- if(counter < 42)
- throw null
- else 0
- }
- }
-
-In this case, the first attempt to initialize the cell would fail. In version 4 this will leave the bitmap with a value still indicating that there's a thread currently computing the value. All the threads trying to access the value would wait for this (non-existent) thread to finish computation, causing the application to leak threads.
-
-In order to maintain current Scala semantics, we need to correctly handle failed initializations. Version 5 presented below, does this correctly:
-
-
- class LazyCellBase { // in a Java file - we need a public bitmap_0
- public static AtomicIntegerFieldUpdater arfu_0 =
- AtomicIntegerFieldUpdater.newUpdater(LazyCellBase.class, "bitmap_0");
- public volatile int bitmap_0 = 0;
- }
-
- final class LazyCell extends LazyCellBase {
- import LazyCellBase._
- var value_0: Int = _
- @tailrec final def value(): Int = (arfu_0.get(this): @switch) match {
- case 0 =>
- if (arfu_0.compareAndSet(this, 0, 1)) {
- val result =
- try {} catch {
- case x: Throwable =>
- complete(0);
- throw x
- }
- value_0 = result
-
- @tailrec def complete(newState: Int): Unit = (arfu_0.get(this): @switch) match {
- case 1 =>
- if (!arfu_0.compareAndSet(this, 1, newState)) complete()
- case 2 =>
- if (arfu_0.compareAndSet(this, 2, newState)) {
- synchronized { notifyAll() }
- } else complete()
- }
-
- complete(3)
- result
- } else value()
- case 1 =>
- arfu_0.compareAndSet(this, 1, 2)
- synchronized {
- while (arfu_0.get(this) != 3) wait()
- }
- value_0
- case 2 =>
- synchronized {
- while (arfu_0.get(this) != 3) wait()
- }
- value_0
- case 3 => value_0
- }
- }
-
-This version is basically the same as Version 4, but it handles retries in accordance with current Scala specification.
-Unfortunately, this comes with a slight performance slowdown. See the evaluation section for more information.
-
-
-### Version 6 - No synchronization on `this` and concurrent initialization of fields ###
-
-Note that the current lazy val initialization implementation is robust against the following scenario, in which the initialization block starts an asynchronous computation attempting to indefinitely grab the monitor of the current object.
-
- class A { self =>
- lazy val x: Int = {
- (new Thread() {
- override def run() = self.synchronized { while (true) {} }
- }).start()
- 1
- }
- }
-
-In the current implementation, the monitor is held throughout the lazy val initialization and released once the initialization block completes.
-All versions proposed above, release the monitor during the initialization block execution and re-acquire it back, so the code above could stall indefinitely.
-
-Additionally, usage of `this` as synchronization point may disallow concurrent initialization of different lazy vals in the same object. Consider the example below:
-
- class TwoLazies {
- lazy val slow = { Thread.sleep(100000); 0}
- lazy val fast = 1
- lazy val bad: Int = {
- (new Thread() {
- override def run() = self.synchronized { while (true) {} }
- }).start()
- 1
- }
- }
-
-Although the two `slow` and `fast` vals are independent, `fast` is required to
-wait for `slow` to be computed. This is due to the fact that they both
-synchronize on `this` for the entire initialization in the current
-implementation.
-
-In the versions presented above, a single call to `bad` may lead to the monitor
-for `this` being held forever, making calls to `slow` and `fast` also block
-forever.
-
-Note that these interactions are very surprising to users as they leak the
-internal limitations of the lazy val implementation.
-
-To overcome these limitations we propose a version that does not synchronize on
-`this` and instead uses external monitor-objects that are used solely for
-synchronization.
-
- final class LazyCell {
- import dotty.runtime.LazyVals
- var value_0: Int = _
- private var bitmap = 0
- @static private bitmap_offset = LazyVals.getOffset(classOf[LazyCell], "bitmap")
- def value(): Int = {
- var result: Int = 0
- var retry: Boolean = true
- val fieldId: Int = 0 // id of lazy val
- var flag: Long = 0L
- while retry do {
- flag = LazyVals.get(this, bitmap_offset)
- LazyVals.STATE(flag, 0) match {
- case 0 =>
- if LazyVals.CAS(this, bitmap_offset, flag, 1) {
- try {result = } catch {
- case x: Throwable =>
- LazyVals.setFlag(this, bitmap_offset, 0, fieldId)
- throw x
- }
- value_0 = result
- LazyVals.setFlag(this, bitmap_offset, 3, fieldId)
- retry = false
- }
- case 1 =>
- LazyVals.wait4Notification(this, bitmap_offset, flag, fieldId)
- case 2 =>
- LazyVals.wait4Notification(this, bitmap_offset, flag, fieldId)
- case 3 =>
- retry = false
- result = $target
- }
- }
- result
- }
- }
-
-This implementation relies on the helper functions provided in \[[11][11]\]
-module. The most important of these functions, `wait4Notification` and
-`setFlag`, are presented below:
-
- def setFlag(t: Object, offset: Long, v: Int, fieldId: Int) = {
- var retry = true
- while (retry) {
- val cur = get(t, offset)
- if (STATE(cur) == 1) retry = CAS(t, offset, cur, v)
- else {
- // cur == 2, somebody is waiting on monitor
- if (CAS(t, offset, cur, v)) {
- val monitor = getMonitor(t, fieldId)
- monitor.synchronized {
- monitor.notifyAll()
- }
- retry = false
- }
- }
- }
- }
-
- def wait4Notification(t: Object, offset: Long, cur: Long, fieldId: Int) = {
- var retry = true
- while (retry) {
- val cur = get(t, offset)
- val state = STATE(cur)
- if (state == 1) CAS(t, offset, cur, 2)
- else if (state == 2) {
- val monitor = getMonitor(t, fieldId)
- monitor.synchronized {
- monitor.wait()
- }
- }
- else retry = false
- }
- }
-
- val processors: Int = java.lang.Runtime.getRuntime.availableProcessors()
- val base: Int = 8 * processors * processors
- val monitors: Array[Object] = (0 to base).map {
- x => new Object()
- }.toArray
-
- def getMonitor(obj: Object, fieldId: Int = 0) = {
- var id = (java.lang.System.identityHashCode(obj) + fieldId) % base
- if (id < 0) id += base
- monitors(id)
- }
-
-This implementation has the following advantages compared to previous version:
-- it allows concurrent initialization of independent fields
-- it does not interact with user-written code that synchronizes on `this`
-- it does not require expanding monitor on the object to support `notifyAll`
-
-Some disadvantages:
-- the `Unsafe` class, used internally has a disadvantage that it can be disallowed with a custom `SecurityManager`.
-Note that this class is extracted from other place in standard library that uses it: scala.concurrent.util.Unsafe.instance
-- it requires usage of `identityHashCode` that is stored for every object inside object header.
-- as global arrays are used to store monitors, seemingly unrelated things may create contention. This is addressed in detail in evaluation section.
-
-Both absence of monitor expansion and usage of `identityHashCode` interact with
-each other, as both of them operate on the object header. \[[12][12]\] presents
-the complete graph of transitions between possible states of the object header.
-What can be seen from this transition graph is that in the contended case,
-versions V2-V5 were promoting object into the worst case, the `heavyweight
-monitor` object, while the new scheme only disables biasing.
-
-Note that under the schemes presented here, V2-V5, this change only happens in
-the event of contention and happens per-object.
-
-### Non-thread-safe lazy vals ###
-While the new versions introduce speedups in the contended case, they do
-generate complex byte-code and this may lead to the new scheme being less
-appropriate for lazy vals that are not used in concurrent setting. In order to
-perfectly fit this use-case we propose to introduce an encoding for
-single-threaded lazy vals that is very simple and efficient:
-
- final class LazyCell {
- var value_0 = 0
- var flag = false
- def value =
- if (flag) value_0
- else {
- value_0 = ;
- flag = true;
- }
- }
-
-This version is faster than all other versions on benchmarks but does not correctly handle safe publication in the case of multiple threads. It can be used in applications that utilize multiple threads if some other means of safe publication is used instead.
-
-### Elegant Local lazy vals ###
-Aside from lazy vals that are fields of objects, scala supports local lazy vals, defined inside methods:
-
- def method = {
- lazy val s =
- s
- }
-
-Currently, they use such encoding(we will call it L1):
-
- def method = {
- var @volatile flag: Byte = 0.toByte
- var s_0 = 0
- def s = {
- if(flag == 0){
- this.synchronized{
- if (flag == 0) {
- s_0 =
- flag = 1
- }
- }
- s_0
- }
- s
- }
-
-Which is later translated by subsequent phases to:
-
- private def method$s(flag: VolatileByteRef, s_0: IntRef) = {
- if(flag.value == 0){
- this.synchronized{
- if (flag.value == 0) {
- s_0.value =
- flag.value = 1
- }
- }
- s_0.value
- }
-
- def method = {
- var flag = new VolatileByteRef(0)
- var s_0 = new IntRef(0)
- method$s(flag, s_0)
- }
-
-
-
-The current implementation has several shortcomings:
- - it allocates two boxes
- - it synchronizes on `this`. This is most severe in case of lambdas, as lambdas do not introduce a new `this`.
-
-We propose a new scheme, that is both simpler in implementation and is more efficient and slightly more compact.
-The scheme introduces new helper classes to the standard library: such as `dotty.runtime.LazyInt`\[[17][17]\] and uses them to implement the local lazy val behavior.
-
- class LazyInt {
- var value: Int = _
- @volatile var initialized: Boolean = false
- }
-
- private def method$s(holder: LazyInt) = {
- if(!holder.initialized){
- holder.synchronized{
- if (!holder.initialized) {
- holder.value =
- holder.initialized = true
- }
- }
- holder.value
- }
-
- def method = {
- var holder = new LazyInt()
- method$s(holder)
- }
-
-This solves the problem with deadlocks introduced by using java8 lambdas.\[[14][14]\]
-
-
-### Language change ###
-To address the fact that we now have both thread safe and single-threaded lazy vals,
-we propose to bring lazy vals in sync with normal vals with regards to usage of `@volatile` annotation.
-
-In order to simplify migration, Scalafix the migration tool that will be used to migrate between versions of Scala, including Dotty, supports a `VolatileLazyVal` rewrite that adds `@volatile` to all `lazy vals` present in the codebase.
-
-
-## Evaluation ##
-
-We focus on the memory footprint increase, the performance comparison and byte-code size. Note that the fast path (i.e. the cost of accessing a lazy val after it has been initialized) stays the same as in the current implementation. Thus, the focus of our measurements is on the overheads in the lazy val initialization in both the uncontended and the contended case.
-The micro-benchmarks used for evaluation are available in a GitHub repo \[[6][6]\] and the graphs of the evaluation results are available online \[[7][7]\], \[[18][18]\], \[[19][19]\] . We used the ScalaMeter tool for measurements \[[9][9]\].
-
-### Memory usage footprint ###
-
-We expect that the proposed changes will not change the memory footprint for most objects that contain lazy vals. Each lazy val currently requires 4 or 8 bytes for the field, and an additional bit in the bitmap. As soon as the first bit is introduced into the bitmap, 1 additional byte is allocated for the object.
-
-Since we now use 2 bits per lazy val field instead of 1, for classes having 4 or less lazy val field declarations the memory footprint per instance will thus not grow. For classes having more lazy val field declarations the memory footprint per instance will in most cases not grow since the objects have to be aligned to an 8 byte boundary anyway.
-
-We measured the memory footprint of an array of objects with single lazy val fields. The memory footprint did not change with respect to the current version \[[6][6]\] \[[7][7]\].
-The detailed experimental measurements graphs of memory footprint can be seen in graphs.\[[18][18]\]
-
-### Performance ###
-
-We measured performance in both the uncontended and the contended case. We measured on an i7-2600, a 64-bit Oracle JVM, version 1.7 update 4.
-
-For the uncontended case, we measure the cost of creating N objects and initializing their lazy val fields. The measurement includes both the object creation times and their initialization, where the initialization is the dominant factor.
-
-For the contended case, we measure the cost of initializing the lazy fields of N objects, previously created and stored in an array, by 4 different threads that linearly try to read the lazy field of an object before proceeding to the next one. The goal of this test is to asses the effect of entering the synchronized block and notifying the waiting threads - since the slow path is slower, the threads that “lag” behind should quickly reach the first object with an uninitialized lazy val, causing contention.
-
-The current lazy val implementation (V1) seems to incur initialization costs that are at least 6 times greater compared to referencing a regular val. The handwritten implementation produces identical byte-code, with the difference that the calls are virtual instead of just querying the field value; this is probably the reason as to why it is up to 50% slower. The 2 synchronized blocks design with an eager notify (V2) is 3-4 times slower than the current implementation - just adding the `notifyAll` call changes things considerably. The 4 state/2 synchronized blocks approach (V3) is only 33-50% slower than the current implementation (V1). The CAS-based approach where `AtomicInteger`s are extended is as fast as the current lazy val initialization (V1), but when generalized and replaced with `AtomicReferenceFieldUpdater`s as discussed before, it is almost 50% slower than the current implementation (V1). The final version, V6 uses `Unsafe` to bring back performance and is as around twice as fast as current implementation (V1) while maintaining correct semantics.
-
-The CAS-based approaches (V4, V5 and V6) appear to offer the best performance here, being twice as fast than the current implementation (V1).
-
-The proposed solution with (V6) is 50% faster\[[19][19]\] than the current lazy val implementation in the contended case. This comes at a price of synchronizing on a global array of monitors, which may create contention between seemingly unrelated things. The more monitors that are created, the less is the probability of such contention. There's also a positive effect though, the reuse of global objects for synchronization allows the monitors on the instances containing lazy vals to not be expanded, saving on non-local memory allocation. The current implementation uses `8 * processorCount * processorCount` monitors and the benchmarks and by-hand study with "Vtune Amplifier XE" demonstrate that the positive effect dominates, introducing a 2% speedup\[[13][13]\]. It’s worth mentioning that this is not a typical use-case that reflects a practical application, but rather a synthetic edge case designed to show the worst-case comparison demonstrating cache contention.
-
-The local lazy vals implementation is around 6x faster than the current version, as it eliminates the need for boxing and reduces the number of allocations from 2 to 1.
-
-The concrete micro-benchmark code is available as a GitHub repo \[[6][6]\]. It additionally benchmarks many other implementations that are not covered in the text of this SIP, in particular it tests versions based on MethodHandles and runtime code generation as well as versions that use additional spinning before synchronizing on the monitor.
-For those wishing to reproduce the results, the benchmarking suite takes 90 minutes to run on contemporary CPUs. Enabling all the disabled benchmarks, in particular those that evaluate the `invokeDynamic` based implementation, will make the benchmarks take around 5 hours.
-
-The final result of those benchmarks is that amount proposed versions, the two that worth considering are (V4-general) and (V6).
-They both perform better than the current implementation in all the contended case.
-Specifically, in the contended case, V6 is 2 times faster than V1, while V4-general is 4 times faster.
-Unfortunately V4-general is 30% slower in the uncontended case than current implementation(V1), while V6 is in the same ballpark, being up to 5% slower or faster depending on the setup of the benchmark.
-
-Based on this, we propose V6 to be used as default in future versions of Scala.
-
-### Code size ###
-The versions presented in V2-V6 have a lot more complex implementation and this shows up the size of the byte-code. In the worst-case scenario, when the `` value is a constant, the current scheme (V1) creates an initializer method that has a size of 34 bytes, while dotty creates a version that is 184 bytes long. Local optimizations present in dotty linker\[[14][14]\] are able to reduce this size down to 160 bytes, but this is still substantially more than the current version.
-
-On the other hand, the single-threaded version does not need separate initializer method and is around twice smaller than the current scheme (V1).
-
-The proposed local lazy val transformation scheme also creates less byte-code, introducing 34 bytes instead of 42 bytes, mostly due to reduction in constant table size.
-
-## Current status ##
-Version V6 is implemented and used in Dotty, together with language change that makes lazy vals thread-unsafe if `@volatile` annotation is not specified.
-Dotty implementation internally uses `@static` proposed in \[[16][16]\].
-
-Both Dotty and released Scala 2.12 already implement "Elegant Local lazy vals". This was incorporated in the 2.12 release before this SIP was considered, as it was fixing a bug that blocked release\[[14][14]\].
-
-### Unsafe ###
-The proposed version, V6 relies on `sun.misc.Unsafe` in order to implement it's behaviour.
-While `sun.misc.Unsafe` will remain available in Java9 there's an intention to deprecate it and replace it with VarHandles.\[[20][20]\].
-The proposed version V6 can be implemented with using functionality present in Var Handles.
-
-## Acknowledgements ##
-
-We would like to thank Peter Levart and the other members of the concurrency-interest mailing list for their suggestions, as well as the members of the scala-internals mailing list for the useful discussions and input.
-
-
-## References ##
-1. [Summary of lazy vals discussions, Scala Internals Mailing list, May 2013][1]
-2. [The cost of `notifyAll`, Concurrency Interest Mailing List, May 2013][2]
-3. [Scala Parallel Collection in Object Initializer Causes a Program to Hang][3]
-4. [Program Hangs If Thread Is Created In Static Initializer Block][4]
-5. [Java Language Specification, 12.4.2][5]
-6. [GitHub Repo with Microbenchmarks][6]
-7. [Uncontended Performance Evaluation Results][7]
-8. [ScalaMeter GitHub Repo][8]
-9. [Lazy Vals in Dotty, Scala Internals Mailing list, February 2014][9]
-10. [Lazy Vals in Dotty, Dotty Internals Mailing list, February 2014][10]
-11. [LazyVals runtime module, Dotty sourcecode, February 2014][11]
-12. [Synchronization, HotSpot internals wiki, April 2008][12]
-13. [Lazy Vals in Dotty, cache contention discussion, February 2014][13]
-14. [SI-9824 SI-9814 proper locking scope for lazy vals in lambdas, April 2016][14]
-15. [Introducing Scalafix: a migration tool for Scalac to Dotty, October 2016][15]
-16. [@static sip, January 2016][16]
-17. [LazyVal Holders in Dotty][17]
-18. [Memory Footprint Evaluation Results][18]
-19. [Contended Performance Evaluation Results][19]
-20. [JEP 193: Variable Handles][20]
-
- [1]: https://groups.google.com/forum/#!topic/scala-internals/cCgBMp5k8R8 "scala-internals"
- [2]: https://cs.oswego.edu/pipermail/concurrency-interest/2013-May/011354.html "concurrency-interest"
- [3]: https://stackoverflow.com/questions/15176199/scala-parallel-collection-in-object-initializer-causes-a-program-to-hang "pc-object-hang"
- [4]: https://stackoverflow.com/questions/7517964/program-hangs-if-thread-is-created-in-static-initializer-block "static-init-hang"
- [5]: https://docs.oracle.com/javase/specs/jls/se7/html/jls-12.html#jls-12.4.2 "jls-spec"
- [6]: https://github.com/DarkDimius/lazy-val-bench/blob/CallSites/src/test/scala/example/package.scala "lazy-val-bench-code"
- [7]: https://d-d.me/tnc/30/lazy-sip-perf/report/#config=%7B%22filterConfig%22%3A%7B%22curves%22%3A%5B%220%22%2C%221%22%2C%225%22%2C%226%22%2C%227%22%2C%228%22%2C%2210%22%2C%2212%22%5D%2C%22order%22%3A%5B%22param-size%22%2C%22date%22%5D%2C%22filters%22%3A%5B%5B%22100000%22%2C%22300000%22%2C%22500000%22%2C%221000000%22%2C%223000000%22%2C%225000000%22%5D%2C%5B%221477397877000%22%5D%5D%7D%2C%22chartConfig%22%3A%7B%22type%22%3A0%2C%22showCI%22%3Afalse%7D%7D "lazy-val-bench-report"
- [8]: https://axel22.github.io/scalameter/ "scalameter-code"
- [9]: https://groups.google.com/forum/#!msg/scala-internals/4sjw8pcKysg/GlXYDDzCgI0J "scala-internals"
- [10]: https://groups.google.com/forum/#!topic/dotty-internals/soWIWr3bRk8 "dotty-internals"
- [11]: https://github.com/lampepfl/dotty/blob/5cbd2fbc8409b446f8751792b006693e1d091055/src/dotty/runtime/LazyVals.scala
- [12]: https://wiki.openjdk.java.net/display/HotSpot/Synchronization
- [13]: https://groups.google.com/d/msg/scala-internals/4sjw8pcKysg/gD0au4dmTAsJ
- [14]: https://github.com/scala/scala-dev/issues/133
- [15]: https://scala-lang.org/blog/2016/10/24/scalafix.html
- [16]: https://github.com/scala/docs.scala-lang/pull/491
- [17]: https://github.com/lampepfl/dotty/blob/f92f278ab686ab218e841082dcb026c6c8ef89b7/library/src/dotty/runtime/LazyHolders.scala
- [18]: https://d-d.me/tnc/30/lazy-mem/report/#config=%7B%22filterConfig%22%3A%7B%22curves%22%3A%5B%22-1%22%2C%220%22%2C%221%22%2C%222%22%2C%223%22%2C%224%22%2C%225%22%2C%226%22%2C%227%22%2C%228%22%5D%2C%22order%22%3A%5B%22param-size%22%2C%22date%22%5D%2C%22filters%22%3A%5B%5B%221000000%22%2C%222000000%22%2C%223000000%22%2C%224000000%22%2C%225000000%22%5D%2C%5B%221477396691000%22%5D%5D%7D%2C%22chartConfig%22%3A%7B%22type%22%3A0%2C%22showCI%22%3Afalse%7D%7D
- [19]: https://d-d.me/tnc/30/lazy-sip-perf/report/#config=%7B%22filterConfig%22%3A%7B%22curves%22%3A%5B%2216%22%2C%2217%22%2C%2218%22%2C%2219%22%2C%2221%22%2C%2222%22%2C%2223%22%5D%2C%22order%22%3A%5B%22param-size%22%2C%22date%22%5D%2C%22filters%22%3A%5B%5B%22100000%22%2C%22300000%22%2C%22500000%22%2C%221000000%22%2C%223000000%22%2C%225000000%22%5D%2C%5B%221477397877000%22%5D%5D%7D%2C%22chartConfig%22%3A%7B%22type%22%3A0%2C%22showCI%22%3Afalse%7D%7D
- [20]: https://openjdk.java.net/jeps/193
diff --git a/_sips/sips/2013-06-10-spores.md b/_sips/sips/2013-06-10-spores.md
deleted file mode 100644
index 1868410121..0000000000
--- a/_sips/sips/2013-06-10-spores.md
+++ /dev/null
@@ -1,459 +0,0 @@
----
-layout: sip
-title: SIP-21 - Spores
-vote-status: "dormant"
-vote-text: There is an implementation for Scala 2.11. A new owner is needed to champion this proposal for the current Scala version. The proposal needs to be updated to explain how to handle transitive spores.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/spores.html
----
-
-**By: Heather Miller, Martin Odersky, and Philipp Haller**
-
-Updated September 15th, 2013
-
-
-
-Functional programming languages are regularly touted as an enabling force, as
-an increasing number of applications become concurrent and distributed.
-However, managing closures in a concurrent or distributed environment, or
-writing APIs to be used by clients in such an environment, remains
-considerably precarious-- complicated environments can be captured by these
-closures, which regularly leads to a whole host of potential hazards across
-libraries/frameworks in Scala's standard library and its ecosystem.
-
-Potential hazards when using closures incorrectly:
-
-- Memory leaks
-- Race conditions, due to capturing mutable references
-- Runtime serialization errors, due to unintended capture of references
-
-This SIP outlines an abstraction, called _spores_, which enables safer use of
-closures in concurrent and distributed environments. This is achieved by
-controlling the environment which a spore can capture. Using an
-_assignment-on-capture_ semantics, certain concurrency bugs due to capturing mutable
-references can be avoided.
-
-## Motivating Examples
-
-### Futures and Akka Actors
-
-In the following example, an Akka actor spawns a future to concurrently
-process incoming requests.
-
-**Example 1:**
-
- def receive = {
- case Request(data) =>
- Future {
- val result = transform(data)
- sender ! Response(result)
- }
- }
-
-Capturing `sender` in the above example is problematic, since it does not
-return a stable value. It is possible that the future's body is executed at a
-time when the actor has started processing the next `Request` message which
-could be originating from a different actor. As a result, the `Response`
-message of the future might be sent to the wrong receiver.
-
-
-### Serialization
-
-The following example uses Java Serialization to serialize a closure. However,
-serialization fails with a `NotSerializableException` due to the unintended
-capture of a reference to an enclosing object.
-
-**Example 2:**
-
- case class Helper(name: String)
-
- class Main {
- val helper = Helper("the helper")
-
- val fun: Int => Unit = (x: Int) => {
- val result = x + " " + helper.toString
- println("The result is: " + result)
- }
- }
-
-Given the above class definitions, serializing the `fun` member of an instance
-of `Main` throws a `NotSerializableException`. This is unexpected, since `fun`
-refers only to serializable objects: `x` (an `Int`) and `helper` (an instance
-of a case class).
-
-Here is an explanation of why the serialization of `fun` fails: since `helper`
-is a field, it is not actually copied when it is captured by the closure.
-Instead, when accessing helper its getter is invoked. This can be made
-explicit by replacing `helper.toString` by the invocation of its getter,
-`this.helper.toString`. Consequently, the `fun` closure captures `this`, not
-just a copy of `helper`. However, `this` is a reference to class `Main` which
-is not serializable.
-
-The above example is not the only possible situation in which a closure can
-capture a reference to `this` or to an enclosing object in an unintended way.
-Thus, runtime errors when serializing closures are common.
-
-## Basic Usage
-
-Spores have a few modes of usage. The simplest form is:
-
- val s = spore {
- val h = helper
- (x: Int) => {
- val result = x + " " + h.toString
- println("The result is: " + result)
- }
- }
-
-In this example, no transformation is actually performed. Instead, the
-compiler simply ensures that the spore is _well-formed_, i.e., anything that's
-captured is explicitly listed as a value definition before the spore's
-closure. This ensures that the enclosing `this` instance is not accidentally
-captured, in this example.
-
-Spores can also be used in for-comprehensions:
-
- for { i <- collection
- j <- doSomething(i)
- } yield s"${capture(i)}: result: $j"
-
-Here, the fact that a spore is created is implicit, that is, the `spore`
-marker is not used explicitly. Spores come into play because the underlying
-`map` method of the type of `doSomething(i)` takes a spore as a parameter. The
-`capture(i)` syntax is an alternative way of declaring captured variables, in
-particular for use in for-comprehensions.
-
-Finally, a regular function literal can be used as a spore. That is, a method
-that expects a spore can be passed a function literal so long as the function
-literal is well-formed.
-
- def sendOverWire(s: Spore[Int, Int]): Unit = ...
- sendOverWire((x: Int) => x * x - 2)
-
-## Design
-
-The main idea behind spores is to provide an alternative way to create
-closure-like objects, in a way where the environment is controlled.
-
-A spore is created as follows.
-
-**Example 3:**
-
- val s = spore {
- val h = helper
- (x: Int) => {
- val result = x + " " + h.toString
- println("The result is: " + result)
- }
- }
-
-The body of a spore consists of two parts:
-
-1. **the spore header:** a sequence of local value (val) declarations only, and
-2. **the closure**.
-
-In general, a `spore { ... }` expression has the following shape.
-
-Note that the value declarations described in point 1 above can be `implicit`
-but not `lazy`.
-
-**Figure 1:**
-
- spore {
- val x_1: T_1 = init_1
- ...
- val x_n: T_n = init_n
- (p_1: S_1, ..., p_m: S_m) => {
-
- }
- }
-
-The types `T_1, ..., T_n` can also be inferred.
-
-The closure of a spore has to satisfy the following rule. All free variables
-of the closure body have to be either
-
-1. parameters of the closure, or
-2. declared in the preceding sequence of local value declarations, or
-3. marked using `capture` (see corresponding section below).
-
-**Example 4:**
-
- case class Person(name: String, age: Int)
- val outer1 = 0
- val outer2 = Person("Jim", 35)
- val s = spore {
- val inner = outer2
- (x: Int) => {
- s"The result is: ${x + inner.age + outer1}"
- }
- }
-
-In the above example, the spore's closure is invalid, and would be rejected
-during compilation. The reason is that the variable `outer1` is neither a
-parameter of the closure nor one of the spore's value declarations (the only
-value declaration is: `val inner = outer2`).
-
-### Evaluation Semantics
-
-In order to make the runtime behavior of a spore as intuitive as possible, the
-design leaves the evaluation semantics unchanged compared to regular closures.
-Basically, leaving out the `spore` marker results in a closure with the same
-runtime behavior.
-
-For example,
-
- spore {
- val l = this.logger
- () => new LoggingActor(l)
- }
-
-and
-
- {
- val l = this.logger
- () => new LoggingActor(l)
- }
-
-have the same behavior at runtime. The rationale for this design decision is
-that the runtime behavior of closure-heavy code can already be hard to reason
-about. It would become even more difficult if we would introduce additional
-rules for spores.
-
-### Spore Type
-
-The type of the spore is determined by the type and arity of the closure. If
-the closure has type `A => B`, then the spore has type `Spore[A, B]`. For
-convenience we also define spore types for two or more parameters.
-
-In example 3, the type of s is `Spore[Int, Unit]`.
-Implementation
-The spore construct is a macro which
-
-- performs the checking described above, and which
-- replaces the spore body so that it creates an instance of one of the Spore traits, according to the arity of the closure of the spore.
-
-The `Spore` trait for spores of arity 1 is declared as follows:
-
- trait Spore[-T, +R] extends Function1[T, R]
-
-For each function arity there exists a corresponding `Spore` trait of the same
-arity (called `Spore2`, `Spore3`, etc.)
-
-### Implicit Conversion
-
-Regular function literals can be implicitly converted to spores. This implicit
-conversion has two benefits:
-
-1. it enables the use of spores in for-comprehensions.
-2. it makes the spore syntax more lightweight, which is important in frameworks such as [Spark](https://spark.incubator.apache.org/) where users often create many small function literals.
-
-This conversion is defined as a member of the `Spore` companion object, so
-it's always in the implicit scope when passing a function literal as a method
-argument when a `Spore` is expected. For example, one can do the following:
-
- def sendOverWire(s: Spore[Int, Int]): Unit = ...
- sendOverWire((x: Int) => x * x - 2)
-
-This is arguably much lighter-weight than having to declare a spore before
-passing it to `sendOverWire`.
-
-In general, the implicit conversion will be successful if and only if the
-function literal is well-formed according to the spore rules (defined above in
-the _Design_ section). Note that _only function literals can be converted to spores_.
-This is due to the fact that the body of the function literal has to be checked
-by the spore macro to make sure that the conversion is safe. For _named_ function
-values (i.e., not literals) on the other hand, it's not guaranteed that the
-function value's body is available for the spore macro to check.
-
-### Capture Syntax and For-Comprehensions
-
-To enable the use of spores with for-comprehensions, a `capture` syntax has
-been introduced to assist in the spore checking.
-
-To see why this is necessary, let's start with an example. Suppose we have a
-type for distributed collections:
-
- trait DCollection[A] {
- def map[B](sp: Spore[A, B]): DCollection[B]
- def flatMap[B](sp: Spore[A, DCollection[B]]): DCollection[B]
- }
-
-This type, `DCollection`, might be implemented in a way where the data is
-distributed across machines in a cluster. Thus, the functions passed to `map`,
-`flatMap`, etc. have to be serializable. A simple way to ensure this is to
-require these arguments to be spores. However, we also would like for-comprehensions
-like the following to work:
-
- def lookup(i: Int): DCollection[Int] = ...
- val indices: DCollection[Int] = ...
-
- for { i <- indices
- j <- lookup(i)
- } yield j + i
-
-A problem here is that the desugaring done by the compiler for
-for-comprehensions doesn't know anything about spores. This is what
-the compiler produces from the above expression:
-
- indices.flatMap(i => lookup(i).map(j => j + i))
-
-The problem is that `(j => j + i)` is not a spore. Furthermore, making it a
-spore is not straightforward, as we can't change the way for-comprehensions
-are translated.
-
-We can overcome this by using the implicit conversion introduced in the
-previous section to convert the function literal implicitly to a spore.
-
-However, in continuing to look at this example, it's evident that the lambda
-still has the wrong shape. The captured variable `i` is not declared in the
-spore header (the list of value definitions preceding the closure within the
-spore), like a spore demands.
-
-We can overcome this using the `capture` syntax – an alternative way of
-capturing paths. That is, instead of having to write:
-
- {
- val captured = i
- j => j + i
- }
-
-One can also write:
-
- (j => j + capture(i))
-
-Thus, the above for-comprehension can be rewritten using spores and `capture`
-as follows:
-
- for { i <- indices
- j <- lookup(i)
- } yield j + capture(i)
-
-Here, `i` is "captured" as it occurs syntactically after the arrow of another
-generator (it occurs after `j <- lookup(i)`, the second generator in the
-for-comprehension).
-
-**Note:** anything that is "captured" using `capture` may only be a path.
-
-**A path** (as defined by the Scala Language Specification, section 3.1) is:
-
-- The empty path ε (which cannot be written explicitly in user programs).
-- `C.this`, where `C` references a class.
-- `p.x` where `p` is a path and `x` is a stable member of `p`.
-- `C.super.x` or `C.super[M].x` where `C` references a class and `x` references a stable member of the super class or designated parent class `M` of `C`.
-
-The reason why captured expressions are restricted to paths is that otherwise
-the two closures
-
- (x => + capture())
-
-and
-
- (x => + )
-
-(where `` and `` are not just paths) would not have the same
-runtime behavior, because in the first case, the closure would have to be
-transformed in a way that would evaluate `` "outside of the closure".
-Not only would this complicate the reasoning about spore-based code (see the
-section Evaluation Semantics above), but it's not clear what "outside of the
-closure" even means in a context such as for-comprehensions.
-
-### Macro Expansion
-
-An invocation of the spore macro expands the spore's body as follows. Given
-the general shape of a spore as shown above, the spore macro produces the
-following code:
-
- new [S_1, ..., S_m, R]({
- val x_1: T_1 = init_1
- ...
- val x_n: T_n = init_n
- (p_1: S_1, ..., p_m: S_m) => {
-
- }
- })
-
-Note that, after checking, the spore macro need not do any further
-transformation, since implementation details such as unneeded remaining outer
-references are removed by the new backend intended for inclusion in Scala
-2.11. It's also useful to note that in some cases these unwanted outer
-references are already removed by the existing backend.
-
-The spore implementation classes follow a simple pattern. For example, for
-arity 1, the implementation class is declared as follows:
-
- class SporeImpl[-T, +R](f: T => R) extends Spore[T, R] {
- def apply(x: T): R = f(x)
- }
-
-### Type Inference
-
-Similar to regular functions and closures, the type of a spore should be
-inferred. Inferring the type of a spore amounts to inferring the type
-arguments when instantiating a spore implementation class:
-
- new [S_1, ..., S_m, R]({
- // ...
- })
-
-In the above expression, the type arguments `S_1, ..., S_m`, and `R` should be
-inferred from the expected type.
-
-Our current proposal is to solve this type inference problem in the context of
-the integration of Java SAM closures into Scala. Given that it is planned to
-eventually support such closures, and to support type inference for these
-closures as well, we plan to piggyback on the work done on type inference for
-SAMs in general to achieve type inference for spores.
-
-## Motivating Examples, Revisited
-
-We now revisit the motivating examples we described in the above section, this
-time in the context of spores.
-
-### Futures and Akka actors
-
-The safety of futures can be improved by requiring the body of a new future to
-be a nullary spore (a spore with an empty parameter list).
-
-Using spores, example 1 can be re-written as follows:
-
- def receive = {
- case Request(data) =>
- future(spore {
- val from = sender
- val d = data
- () => {
- val result = transform(d)
- from ! Response(result)
- }
- })
- }
-
-In this case, the problematic capturing of `this` is avoided, since the result
-of `this.sender` is assigned to the spore's local value `from` when the spore
-is created. The spore conformity checking ensures that within the spore's
-closure, only `from` and `d` are used.
-
-### Serialization
-
-Using spores, example 2 can be re-written as follows:
-
- case class Helper(name: String)
-
- class Main {
- val helper = Helper("the helper")
-
- val fun: Spore[Int, Unit] = spore {
- val h = helper
- (x: Int) => {
- val result = x + " " + h.toString
- println("The result is: " + result)
- }
- }
- }
-
-Similar to example 1, the problematic capturing of `this` is avoided, since
-`helper` has to be assigned to a local value (here, `h`) so that it can be
-used inside the spore's closure. As a result, `fun` can now be serialized
-without runtime errors, since `h` refers to a serializable object (a case
-class instance).
diff --git a/_sips/sips/2013-06-30-async.md b/_sips/sips/2013-06-30-async.md
deleted file mode 100644
index a83bb6f5a4..0000000000
--- a/_sips/sips/2013-06-30-async.md
+++ /dev/null
@@ -1,298 +0,0 @@
----
-layout: sip
-title: SIP-22 - Async
-vote-status: dormant
-vote-text: Authors have marked this proposal as dormant. Details in the implementation need to be figured out. Check July 2016's minutes.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/async.html
----
-
-**By: Philipp Haller and Jason Zaugg**
-
-## Introduction
-
-This is a proposal to add constructs that simplify asynchronous and concurrent programming in Scala. The main constructs, async and await, are inspired by similar constructs introduced in C# 5.0. The main purpose of async/await is to make it possible to express efficient asynchronous code in a familiar direct style (where suspending operations look as if they were blocking). As a result, non-blocking code using Scala’s futures API \[[1][1]\] can be expressed without using higher-order functions, such as map and flatMap, or low-level callbacks.
-
-On the level of types, async and await are methods with simple, intuitive types:
-
- def async[T](body: => T): Future[T]
- def await[T](future: Future[T]): T
-
-Here, `Future[T]` refers to the `Future` trait in package `scala.concurrent`. (The system can be adapted to other implementations of future-like abstractions; at the moment the API with the required extension points is internal, though.) The above methods are used as follows:
-
- val fut = async {
- slowComputation()
- }
-
-The async construct marks a block of asynchronous code, and returns a future. Depending on the execution context in the implicit scope (see \[[1][1]\]), the block of asynchronous code is either executed on the current thread or in a thread pool. The async block can contain calls to await:
-
- val futureDOY: Future[Response] =
- WS.url("https://api.day-of-year/today").get
-
- val futureDaysLeft: Future[Response] =
- WS.url("https://api.days-left/today").get
-
- val respFut = async {
- val dayOfYear = await(futureDOY).body
- val daysLeft = await(futureDaysLeft).body
- Ok(s"$dayOfYear: $daysLeft days left!")
- }
-
-Line 1 and 4 define two futures obtained as results of asynchronous requests to two hypothetical web services using an API inspired by Play Framework \[[2][2]\] (for the purpose of this example, the definition of type `Response` is unimportant). The `await` on line 8 causes the execution of the `async` block to suspend until `futureDOY` is completed (with a successful result or with an exception). When the future is completed successfully, its result is bound to the `dayOfYear` val, and the execution of the `async` block is resumed. When the future is completed with an exception (for example, because of a timeout), the invocation of `await` re-throws the exception that the future was completed with. In turn, this completes future respFut with the same exception. Likewise, the `await` on line 9 suspends the execution of the `async` block until futureDaysLeft is completed.
-
-## Comparison with Scala’s Futures API
-
-The provided async and await constructs can significantly simplify code coordinating multiple futures. Consider the following example, written using Scala’s futures API together with for-comprehensions:
-
- def nameOfMonth(num: Int): Future[String] = ...
- val date = “““(\d+)/(\d+)“““.r
-
- for { doyResponse <- futureDOY
- dayOfYear = doyResponse.body
- response <- dayOfYear match {
- case date(month, day) =>
- for (name <- nameOfMonth(month.toInt))
- yield Ok(s“It’s $name!“)
- case _ =>
- Future.successful(NotFound(“Not a...“))
- }
- } yield response
-
-Line 1 defines an asynchronous method that converts an integer representing the number of a month to the name of the month (for example, the integer 2 is converted to "February"). Since the method is asynchronous, it returns a `Future[String]`. Line 2 defines a regular expression used to extract the month from a date string such as "07/24". The for-comprehension starting on line 4 first awaits the result of `futureDOY` (the example re-uses the definition of `futureDOY` shown earlier). Scala's futures provide methods like `map` and `flatMap`, and can thus be used as generators in for-comprehensions (for a more in-depth introduction of this feature see the official documentation \[[1][1]\]). The use of for-comprehensions can help make future-based code more clear, but in many cases it requires a significant amount of unnatural clutter and workarounds. The above example suffers from the following issues:
-
-- To extract `dayOfYear`, we are forced to introduce the name `doyResponse`, a useless intermediate result (line 4);
-- to await the completion of the future returned by `nameOfMonth`, we are forced to use a nested for-comprehension (line 8);
-- the nested for-comprehension forces us to bind the result of nameOfMonth to name, a useless intermediate variable (line 8);
-- the nested for-comprehension forces us to introduce an artificial future that's completed upon creation (line 11);
-- the artificial future introduces additional overhead and garbage (line 11);
-- finally, the use of for-yield might obscure the actual domain which is asynchronous computations with non-blocking awaits.
-
-The same example can be written using async/await as follows:
-
- async {
- await(futureDOY).body match {
- case date(month, day) =>
- Ok(s“It’s ${await(nameOfMonth(month.toInt))}!“)
- case _ =>
- NotFound(“Not a date, mate!“)
- }
- }
-
-This version avoids all drawbacks of the previous version listed above. In addition, the generated code is more efficient, because it creates fewer closures.
-
-## Illegal Uses
-
-The following uses of await are illegal and are reported as errors:
-- await requires a directly-enclosing async; this means await must not be used inside a closure nested within an async block, or inside a nested object, trait, or class.
-- await must not be used inside an expression passed as an argument to a by-name parameter.
-- await must not be used inside a Boolean short-circuit argument.
-- return expressions are illegal inside an async block.
-
-## Implementation
-
-We have implemented the present proposal using the macro system which has been introduced in Scala 2.10 as an experimental feature. Our implementation \[[3][3]\] is targeted at Scala 2.11.0, but runs on using Scala 2.10.1 without any limitations.
-
-## Async Transform Specification
-
-In the following we consider the transformation of an invocation `async { }` of the async macro.
-Before the block of code (``) is transformed, it is normalized into a form amenable to a transformation into a state machine. This form is called the "A-Normal Form" (ANF), and roughly means that:
-
-- `if`, `match`, and other control-flow constructs are only used as statements; they cannot be used as expressions;
-- calls to `await` are not allowed in compound expressions.
-
-After the ANF transform, the async macro prepares the state machine
-transformation by identifying vals, vars and defs that are accessed
-from multiple states. These will be lifted out to fields in the state
-machine object.
-
-The next step of the transformation breaks the code into "chunks."
-Each chunk contains a linear sequence of statements that concludes
-with a branching decision, or with the registration of a subsequent
-state handler as the continuation (the "on-completion handler"). Once
-all chunks have been built, the macro synthesizes a class representing
-the state machine. The class contains:
-
-- an integer representing the current state ID
-- the lifted definitions
-- an `apply(value: Try[Any]): Unit` method that will be called on completion of each future. The behavior of this method is determined by the current state. It records the downcast result of the future in a field, and calls the `resume()` method.
-- the `resume(): Unit` method that switches on the current state and runs the users code for one "chunk," and either: (a) registers the state machine as the handler for the next future, or (b) completes the result promise of the async block, if at the terminal state.
-- an `apply(): Unit` method that starts the evaluation of the async block's body.
-
-### Example
-
- val future = async {
- val f1 = async { true }
- val x = 1
- def inc(t: Int) = t + x
- val t = 0
- val f2 = async { 42 }
- if (await(f1)) await(f2) else { val z = 1; inc(t + z) }
- }
-
-After the ANF transform:
-- `await` calls are moved to only appear on the RHS of a value definition;
-- `if` is no longer used as an expression; instead each branch writes its result to a synthetic var;
-- the `ExecutionContext` used to run the async block is obtained as an implicit argument.
-
-Follows the end result of the ANF transform (with very minor
-simplifications).
-
- {
- ();
- val f1: scala.concurrent.Future[Boolean] = {
- scala.concurrent.Future.apply[Boolean](true)(scala.concurrent.ExecutionContext.Implicits.global)
- };
- val x: Int = 1;
- def inc(t: Int): Int = t.+(x);
- val t: Int = 0;
- val f2: scala.concurrent.Future[Int] = {
- scala.concurrent.Future.apply[Int](42)(scala.concurrent.ExecutionContext.Implicits.global)
- };
- val await$1: Boolean = scala.async.Async.await[Boolean](f1);
- var ifres$1: Int = 0;
- if (await$1)
- {
- val await$2: Int = scala.async.Async.await[Int](f2);
- ifres$1 = await$2
- }
- else
- {
- ifres$1 = {
- val z: Int = 1;
- inc(t.+(z))
- }
- };
- ifres$1
- }
-
-After the full async transform:
-
-- one class is synthesized that represents the state machine. Its `apply()` method is used to start the computation (even the code before the first await call is executed asynchronously), and the `apply(tr: scala.util.Try[Any])` method will continue after each completed future that the async block awaits;
-
-- each chunk of code is moved into the a branch of the pattern match in `resume$async`;
-
-- value and function definitions accessed from multiple states are lifted to be members of class `stateMachine`; others remain local, e.g. `val z`;
-
-- `result$async` holds the promise which is completed with the result of the async block;
-
-- `execContext$async` holds the `ExecutionContext` that has been inferred.
-
-Follows the end result of the full async transform (with very minor
-simplifications).
-
- {
- class stateMachine$7 extends StateMachine[scala.concurrent.Promise[Int], scala.concurrent.ExecutionContext] {
- var state$async: Int = 0;
- val result$async: scala.concurrent.Promise[Int] = scala.concurrent.Promise.apply[Int]();
- val execContext$async = scala.concurrent.ExecutionContext.Implicits.global;
- var x$1: Int = 0;
- def inc$1(t: Int): Int = t.$plus(x$1);
- var t$1: Int = 0;
- var f2$1: scala.concurrent.Future[Int] = null;
- var await$1: Boolean = false;
- var ifres$1: Int = 0;
- var await$2: Int = 0;
- def resume$async(): Unit = try {
- state$async match {
- case 0 => {
- ();
- val f1 = {
- scala.concurrent.Future.apply[Boolean](true)(scala.concurrent.ExecutionContext.Implicits.global)
- };
- x$1 = 1;
- t$1 = 0;
- f2$1 = {
- scala.concurrent.Future.apply[Int](42)(scala.concurrent.ExecutionContext.Implicits.global)
- };
- f1.onComplete(this)(execContext$async)
- }
- case 1 => {
- ifres$1 = 0;
- if (await$1)
- {
- state$async = 2;
- resume$async()
- }
- else
- {
- state$async = 3;
- resume$async()
- }
- }
- case 2 => {
- f2$1.onComplete(this)(execContext$async);
- ()
- }
- case 5 => {
- ifres$1 = await$2;
- state$async = 4;
- resume$async()
- }
- case 3 => {
- ifres$1 = {
- val z = 1;
- inc$1(t$1.$plus(z))
- };
- state$async = 4;
- resume$async()
- }
- case 4 => {
- result$async.complete(scala.util.Success.apply(ifres$1));
- ()
- }
- }
- } catch {
- case NonFatal((tr @ _)) => {
- {
- result$async.complete(scala.util.Failure.apply(tr));
- ()
- };
- ()
- }
- };
- def apply(tr: scala.util.Try[Any]): Unit = state$async match {
- case 0 => {
- if (tr.isFailure)
- {
- result$async.complete(tr.asInstanceOf[scala.util.Try[Int]]);
- ()
- }
- else
- {
- await$1 = tr.get.asInstanceOf[Boolean];
- state$async = 1;
- resume$async()
- };
- ()
- }
- case 2 => {
- if (tr.isFailure)
- {
- result$async.complete(tr.asInstanceOf[scala.util.Try[Int]]);
- ()
- }
- else
- {
- await$2 = tr.get.asInstanceOf[Int];
- state$async = 5;
- resume$async()
- };
- ()
- }
- };
- def apply: Unit = resume$async()
- };
- val stateMachine$7: StateMachine[scala.concurrent.Promise[Int], scala.concurrent.ExecutionContext] = new stateMachine$7();
- scala.concurrent.Future.apply(stateMachine$7.apply())(scala.concurrent.ExecutionContext.Implicits.global);
- stateMachine$7.result$async.future
- }
-
-## References
-
-1. [The Scala Futures API][1]
-2. [The Play! Framework][2]
-3. [Scala Async on GitHub][3]
-
- [1]: https://docs.scala-lang.org/overviews/core/futures.html "ScalaFutures"
- [2]: https://www.playframework.com/ "Play"
- [3]: https://github.com/scala/async "ScalaAsync"
diff --git a/_sips/sips/2015-6-18-repeated-byname.md b/_sips/sips/2015-6-18-repeated-byname.md
deleted file mode 100644
index ee71571b6a..0000000000
--- a/_sips/sips/2015-6-18-repeated-byname.md
+++ /dev/null
@@ -1,34 +0,0 @@
----
-layout: sip
-title: SIP-24 - Repeated By Name Parameters
-vote-status: dormant
-vote-text: Looking for a new owner. This proposal needs to be updated according to the SIP meeting in November 2016.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/repeated-byname.html
-
----
-
-**By: Martin Odersky**
-
-## Motivation
-
-Scala so far does not allow by-name repeated parameters. But I can't see a good reason why this combination should be disallowed. Also, the combination is necessary to allow vararg parameters that are passed as expressions to inline methods (instead of being lifted out).
-
-## Syntax
-
-The syntax for `ParamType` becomes
-
- ParamType ::= [`=>'] ParamValueType
- ParamValueType ::= Type [`*']
-
-The syntax implies that a type such as `=> T*`, which is both by-name and repeated is interpreted as `=> (T*)`, that is, as a by-name type of a repeated type.
-
-## Translation Rules
-
-If a parameter has a by-name repeated type `=> T*` it matches an arbitrary number of actual arguments of type `T`. As usual for by-name parameters, the arguments are not evaluated at the point of call. Instead, all arguments are evaluated each time the parameter is referenced in the called method.
-
-The same holds for an vararg argument of the form `e: _*`. The argument expression `e` is evaluated each time the parameter is referenced in the called method.
-
-## See also
-
-[Dotty Issue #499](https://github.com/lampepfl/dotty/issues/499)
diff --git a/_sips/sips/2016-07-25-unsigned-integers.md b/_sips/sips/2016-07-25-unsigned-integers.md
deleted file mode 100644
index ef8ecd7bf1..0000000000
--- a/_sips/sips/2016-07-25-unsigned-integers.md
+++ /dev/null
@@ -1,636 +0,0 @@
----
-layout: sip
-title: SIP-26 - Unsigned Integers
-
-vote-status: rejected
-vote-text: The committee votes to reject the proposal because of a 6% performance hit on the provided implementation by the authors.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/unsigned-integers.html
----
-
-__Sébastien Doeraene and Denys Shabalin__
-
-**Summary**: We propose the addition of 4 "primitive" types to represent
-unsigned integers: `UByte`, `UShort`, `UInt` and `ULong`.
-
-A prototype implementation of this proposal, with unit tests and benchmarks,
-can be found [here](https://github.com/scala/scala/compare/2.12.x...sjrd:uints).
-
-## History
-
-| Date | Version |
-|--------------|---------------|
-| Nov 9th 2015 | Initial Draft |
-
-## Introduction - Motivation - Abstract
-
-Scala was initially designed to target the JVM, and, as such, defines exactly
-9 primitive types corresponding to the 9 primitive types of the JVM (including
-`void`):
-
-* `Boolean`
-* `Char`
-* `Byte`
-* `Short`
-* `Int`
-* `Long`
-* `Float`
-* `Double`
-* `Unit`
-
-Compared to other languages, especially those in the tradition of
-compile-to-machine code, this list is missing types for unsigned integer types.
-
-When compiling Scala to other platforms than the JVM, such as JavaScript with
-Scala.js or native code/LLVM with the upcoming ScalaNative, the missing unsigned
-integer types are a liability, especially when it comes to *interoperability
-with host language libraries*.
-
-For example, if a C library defines a function accepting a `uint32_t`, how would
-we type it in a FFI definition? Even in JavaScript, which supposedly has only
-`Double`s, there are APIs working with unsigned integers. The most well-known
-one is
-[the TypedArray API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray).
-Currently, because of the lack of unsigned integers in Scala, the
-[facade types for `Uint8Array` in Scala.js](https://github.com/scala-js/scala-js/blob/v0.6.5/library/src/main/scala/scala/scalajs/js/typedarray/Uint8Array.scala)
-is forced to use `Short` elements instead of a more appropriate `UByte`. Worse,
-[the one for `Uint32Array`](https://github.com/scala-js/scala-js/blob/v0.6.5/library/src/main/scala/scala/scalajs/js/typedarray/Uint32Array.scala)
-has to work with *Doubles*, because there is no signed integer type existing on
-JavaScript that can represent all values of a 32-bit unsigned int.
-
-On the JVM, interoperability is not an issue. However, it is still sometimes
-useful to manipulate unsigned integers. An evidence of this fact is that Java 8
-has added methods in the JDK to *manipulate* signed integers *as if* they were
-unsigned. One example is
-[`java.lang.Integer.divideUnsigned`](https://docs.oracle.com/javase/8/docs/api/java/lang/Integer.html#divideUnsigned-int-int-).
-Using signed integer types but interpreting them as unsigned is an obvious lack
-of type safety, however. Java cannot decently add new primitive types for
-compatibility reasons, but Scala has custom-made `AnyVal`s and other
-Object-Oriented abstractions on top of primitive types that can allow for
-additional, zero-overhead "primitive" types.
-
-We therefore propose to extend the Scala programming language with 4 new
-primitive data types, representing unsigned integer types:
-
-* `scala.UByte`, an unsigned 8-bit integer
-* `scala.UShort`, an unsigned 16-bit integer
-* `scala.UInt`, an unsigned 32-bit integer
-* `scala.ULong`, an unsigned 64-bit integer
-
-These data types will support a set of operations similar to their signed
-counterparts, except that they will obviously encode the unsigned behavior.
-
-For example:
-
-```scala
-val x = Int.MaxValue.toUInt + 1.toUInt // 2147483648
-assert(x.toString == "2147483648")
-val y = Int.MaxValue.toUInt + 5.toUInt // 2147483652
-val z = x / y // unsigned division of 2147483652 by 2147483648
-assert(z == 1.toUInt)
-assert(x % y == 4.toUInt)
-```
-
-## Motivating Examples
-
-### Examples
-
-#### Interoperability with host language unsigned integers
-
-The most important use case for true unsigned integers specified by the
-language is interoperability with host languages with unsigned data types.
-
-If we try to manipulate an `Uint32Array` in Scala.js as currently defined, we
-end up manipulating `Double`s, which can become extremely confusing:
-
-```scala
-val array = new Uint32Array(js.Array(5, 7, 6, 98))
-val x = array(3) / array(0)
-println(x) // 19.6 (!)
-```
-
-This also causes type safety issues, since nothing prevents the developer from
-introducing a non-integer `Double` into such an array:
-
-```scala
-array(2) = 6.4 // compiles, silent drop of precision
-println(array(2)) // 6
-```
-
-If we can define `Uint32Array` as an array of `UInt` instead, our problems are
-solved:
-
-```scala
-val array = new Uint32Array(js.Array(5, 7, 6, 98).map(_.toUInt))
-val x = array(3) / array(0)
-println(x) // 19, as expected
-
-array(2) = 6.4 // does not compile, yeah!
-```
-
-#### Implementation of algorithms requiring unsigned operations
-
-No matter the platform, even on the JVM, we sometimes have to implement
-algorithms that are best defined in terms of unsigned operations. Particularly,
-more often than not, we want to treat bytes in a buffer as unsigned.
-
-For example, here is a (buggy) algorithm to decode text encoded in ISO-8859-1
-(latin1) into Unicode code points. Can you spot the issue?
-
-```scala
-def decodeISO88591(buffer: Array[Byte]): String = {
- val result = new StringBuilder(buffer.length)
- for (i <- 0 until buffer.length)
- result.append(buffer(i).toChar)
- result.toString()
-}
-```
-
-The problem is that `buffer(i).toChar` will first *sign-extend* the signed
-`Byte` to an `Int`, then cut off the 16 most significant bits. If the initial
-`Byte` was ">= 0x80", it was actually *negative*, and therefore the resulting
-`Char` will have its 8 most significant bits set to 1, which is a bug.
-
-Fixing the algorithm requires knowledge of 2's complement properties and how
-the bits are affected by arithmetic operations. The solution is
-`(buffer(i) & 0xff).toChar`, which is totally non-obvious.
-
-With unsigned bytes, the problem does not happen by construction, and the
-algorithm is straightforward:
-
-```scala
-def decodeISO88591(buffer: Array[UByte]): String = {
- val result = new StringBuilder(buffer.length)
- for (i <- 0 until buffer.length)
- result.append(buffer(i).toChar) // correct: UByte.toChar does not sign-extend
- result.toString()
-}
-```
-
-### Comparison Examples
-
-The blog post
-[Unsigned int considered harmful for Java](https://www.nayuki.io/page/unsigned-int-considered-harmful-for-java)
-explains in detail how to correctly manipulate signed integer types to make
-them behave as unsigned.
-
-There are two main problems with this, considering only the JVM target:
-
-* We have to remember what operations need dedicated methods to deal with the
- unsigned case.
-* We cannot express in the type of a value whether it is to be interpreted as
- a signed or unsigned integer. Effectively, we're back to *Assembly*-grade
- weak typing.
-
-In addition, those separate manipulations do not allow back-ends to other
-targets to effectively interoperate with host language unsigned data types.
-
-### Counter-Examples
-
-We do not intend to generalize unsigned numbers to Big integers nor to
-floating-point numbers.
-
-Also, it is out of the scope of this proposal to provide literal constant
-notations for unsigned integers. They should be constructed from their
-corresponding signed literals, and reinterpreted using `.toUInt` and similar.
-
-## Drawbacks
-
-### Performance of arrays
-
-Unless the implementation of unsigned integer types is very much special-cased
-in the compiler, arrays of unsigned integer types will likely suffer from the
-same performance penalty as arrays of user-defined `AnyVal`s, because the
-elements will be boxed.
-
-This might cause unexpected performance issues, as developers will think that
-`Array[UByte]` is as fast as `Array[Byte]`, when in fact it is not.
-Performance-critical code should still use `Array[Byte]`, and reinterpret the
-bytes into unsigned bytes and back using `sb.toUByte` and `ub.toByte`,
-respectively.
-
-## Alternatives
-
-The only other alternative is the status quo, where no unsigned integer types
-exist, and difficult 2's complement-aware manipulations must be done when we
-need them.
-
-## Design
-
-Naively, the design of the API is straightforward. We would define 4 new
-data types `UByte`, `UShort`, `UInt` and `ULong`, corresponding to the 4
-signed integer data types. They feature the same set of arithmetic and logic
-operations, as well as comparisons. However, such a naive design causes
-several issues, especially when signed integers and unsigned integers interact
-in operations.
-
-Here, we discuss the set of operations available, and their semantics.
-
-### No arithmetic/logic operations between signed and unsigned integers
-
-To prevent typical caveats when mixing signed and unsigned integers in most
-languages, we simply *forbid* any arithmetic or logic operations with operands
-of different signedness.
-
-### Universal equality, and hash codes
-
-The universal equality operators (`==` and `!=`) should behave consistently
-across signed and unsigned types. Since `5.toByte == 5` in Scala, we should
-also have `5.toUInt == 5`. This requires to modify the `==` implementation
-(in `BoxesRunTime`) to implement cooperative equality checks between all
-combinations of signed and unsigned values.
-
-Negative values of signed integers are *not* equal to any unsigned integer
-value. For example, this means that `(-1).toUInt != -1`. This is very simply
-explained by the fact that the mathematical value of `(-1).toUInt` is
-4294967295.
-
-Because of transitivity of equality, it must be the case that a large value of
-an unsigned integer (whose signed reinterpretation is negative, such as
-`0xffffffff.toUInt`) *is* equal to values of a larger signed integer types
-(such as `0xffffffffL`).
-
-Hash codes, as computed by `##`, must be made consistent with the generalized
-form of universal equality.
-
-Note that this definition of universal equality is *essential* for these new
-primitives to be usable for interoperability scenarios in Scala.js. This is
-because, at runtime, "boxed" versions of numeric types loose their type
-information, as they are all stuffed into primitive JavaScript numbers.
-Therefore, `0xffff.toUShort` is indistinguishable from `0xffff`, and they must
-be equal for this "non-boxing" to be valid.
-
-### Operations on `UByte` and `UShort`
-
-By analogy to the fact that operations on `Byte`s and `Short` start by
-converting their operands to `Int`s (using sign-extend), operations on `UByte`s
-and `UShort`s convert their operands to `UInt`s (without sign-extend,
-obviously).
-
-### Arithmetic operations on `UInt`s and `ULong`s.
-
-For two operands of the same unsigned integer type with N bits, `a + b`,
-`a - b`, `a * b`, `a / b` and `a % b` are computed modulo `2^N`.
-For `+`, `-` and `*`, this boils down to a primitive (signed) equivalent
-operations, on the JVM. `/` and `%` correspond to
-`java.lang.{Integer,Long}.divideUnsigned` and `remainderUnsigned`.
-
-If one of the operand is a `ULong` but the other isn't, the latter is converted
-to a `ULong` before performing the operation.
-
-There is no `unary_-`, because unsigned integers have no opposite. It could be
-argued that `-x` could be useful for low-level bit-twiddling-based algorithms.
-However, in that case, `~x + 1.toUInt` can be used instead. A basic peephole
-optimizer can simplify the latter as `-x` on platforms where this is relevant.
-
-### Logic (bitwise) operations on `UInt`s and `ULong`s
-
-`unary_~`, `|`, `&` and `^` behave in the obvious way. If you want a precise
-spec, they always behave as if the operand was reinterpreted into its signed
-equivalent, then the operation performed, then the result reinterpreted back
-into unsigned.
-
-### Bit shifting operations on `UInt`s and `ULong`s
-
-Shift left `<<` and shift logical right `>>>` behave in the obvious way.
-
-The case of shift arithmetic right `>>` is debatable. We argue that it should
-*not* be available on unsigned integers for two reasons.
-
-First, a shift arithmetic right does not appear to have any *meaning* on
-unsigned integers. The correct *arithmetic* shift if `>>>`. Therefore,
-similarly to `unary_-`, it should not be introduced.
-
-Second, existing languages that do have unsigned integer types, such as the C
-family, actually give different semantics to `>>` depending on whether it has
-a signed or unsigned operand: a `>>` on an unsigned operand does *not*
-sign-extend. It would be confusing to a C developer for `x >> 3` to sign-extend
-in Scala, but it would be equally confusing to a Scala developer that `x >> 3`
-*not* sign-extend. Therefore, we prefer to leave it out completely, and let a
-compiler error be raised.
-
-If a bit-twiddling-based algorithm needs the sign-extending shift right, it is
-always possible to reinterpret as signed, do the operation, and reinterpret
-back as unsigned: `(x.toInt >> 3).toUInt`.
-
-Note: the current implementation does provide `>>`, until we agree on this
-point.
-
-### Inequality operators
-
-`<`, `<=`, `>`, `>=` perform unsigned comparisons. On the JVM, they correspond
-to `java.lang.{Integer,Long}.compareUnsigned`.
-
-### String representation
-
-The string representation is similar to that of signed integers, except that
-all numbers are positive, obviously. On the JVM, they correspond to
-`java.lang.{Integer,Long}.toUnsignedString`.
-
-### Implicit widening conversions
-
-Unsigned integers can be implicitly widened to "larger" unsigned integer types.
-For example, `UShort` can be implicitly converted to `UInt` and `ULong`.
-
-There are no implicit conversions between signed and unsigned integers. It might
-be tempting to allow unsigned integers to be widened to larger signed integer
-types, since they can always accommodate their mathematical values. However,
-this consequently allows operations between signed and unsigned integers, such
-as `5L + 4.toUInt`, because of the conversion from `UInt` to `Long`. Since we
-want to disallow those to prevent caveats, we do not allow the implicit
-conversions.
-
-### Explicit conversions between signed and unsigned
-
-We have already extensively used explicit conversions between signed and
-unsigned integer types *of the same size* in this document, such as
-`someInt.toUInt`. These are specified as reinterpreting the bit pattern into
-the other type, with the common specification that integer types are represented
-in 2's complement.
-
-*Narrowing* conversions are also allowed in both directions, such as
-`someInt.toUByte` or `someUInt.toByte`. They are equally well specified as
-either `someInt.toUInt.toUByte` or `someInt.toByte.toUByte`, with the same
-results, and therefore no ambiguity exists.
-
-*Widening* conversions from unsigned integers to larger signed integers is
-allowed, and is specified by conserving the mathematical value, i.e., the
-widening does *not* sign-extend.
-
-Finally, widening conversions from signed integers to larger unsigned integers
-is *disallowed*, because both interpretations are equally valid, and therefore
-half of the developers will have the wrong expectation. For example,
-`someInt.toULong` can be equally validly specified as `someInt.toUInt.toULong`
-or `someInt.toLong.toULong`, but those do not yield the same result (the former
-does not sign-extend while the latter does).
-
-### Consequences on other parts of the library
-
-`scala.math` should receive new overloads of `max` and `min`, taking unsigned
-integer types as parameters, and performing the comparisons with unsigned
-semantics.
-
-There should be instances of the `Ordering` typeclass for unsigned integer
-types.
-
-There should *not* be instances of the `Numeric` and `Integral` typeclasses
-for unsigned integer types, since they do not support `unary_-`.
-
-It might be tempting to define `Range`s over unsigned integers, but we do not
-want to go there.
-
-### Performance considerations
-
-Since they will inevitably be "branded" as primitive data types, unsigned
-integer types should be as efficient as signed integer types.
-
-Fortunately, the JDK 8 added the necessary methods in the standard JDK to
-trivially implement all the operations on unsigned integers. It is expected
-that these methods be as fast primitive operations, since they can be
-intrinsified easily.
-
-There also exist efficient implementations of these methods in Scala.js. LLVM
-supports the relevant operations by default for ScalaNative, obviously.
-
-The implementations in `BoxesRunTime` for universal equality and hash codes
-receives additional cases, which could slow down `==` on `Any`s and generic
-values. However, if a codebase does not use any unsigned integer, the JVM,
-using global knowledge, can statically determine that the new type tests are
-always `false` and therefore remove them. There should be no performance
-penalty on such codebases.
-
-## Implementation
-
-Because of the cooperative equality with primitive signed integers, the
-addition of unsigned integers must necessarily integrate the core library.
-
-Besides that, there are two major strategies for the implementation: mostly
-user-space or mostly in compiler-space.
-
-### Mostly user-space vs compiler-space
-
-An existing implementation living mostly in user-space can be found at
-https://github.com/scala/scala/compare/2.12.x...sjrd:uints
-
-In this approach, unsigned integer types are user-defined `AnyVal`s, and all
-the new methods are implemented in the library. The compiler needs very little
-adaptations; basically only to dispatch `==` of unsigned integers to
-`BoxesRunTime` (otherwise, it is "optimized" as directly calling `equals()`).
-
-This approach has obvious advantages:
-* Little room for mistakes
-* Very simple implementation
-* Minimal impact on the compiler
-
-However, it also suffers from a couple of limitations, because the new
-"primitive" data types are not really primitive, and do not receive some of the
-semantic treatment of primitives.
-
-First, unboxing from `null`: a primitive data type unboxes `null` to its zero,
-but user-defined `AnyVal`s throw in those situations. One way to fix this would
-be to "fix" the behavior on `AnyVal`s in general, which we think would be a good
-idea on its own anyway.
-
-Second, weak conformance: unsigned integers don't receive the weak conformance
-properties. However, we argue that this is no big deal. The main use case for
-weak conformance is so that `List(1, 5, 3.5)` can be inferred as a
-`List[Double]` instead of a `List[AnyVal]`. The problem initially happens
-because of the way we write literal integers and literal doubles. Since unsigned
-integers have no literal notation, and are not implicitly compatible with
-signed integers nor doubles, this point is moot.
-
-In the short term, these limitations do not appear important, and we could live
-with them.
-
-More importantly, however, this implementation prevents specialization to be
-applied on unsigned integers, and imposes harsh constraints on how back-ends
-can implement unsigned integers.
-
-In Scala.js these constraints are not too hard from the point of view of
-interoperability scenarios, although they could limit the performance we can
-get out of unsigned integers. Since interoperability is paramount, we can again
-live with the constraints for the time being.
-
-For ScalaNative, the consequences of these constraints are, as of yet, unknown,
-but they could affect interoperability scenarios, and will most probably affect
-performance.
-
-In the longer term, we should therefore consider more tightly integrating
-unsigned integer types as true primitives of the compiler.
-
-Such a strategy will however be much riskier, and will take much more time to
-get right.
-
-### Performance evaluation
-
-To evaluate performance of our prototype we've implemented a simple jmh
-benchmark generator that checks composite performance of evaluation of complex
-arithmetic expressions for all number types (both primitive signed ones and
-user-defined unsigned ones.)
-
-For each type we've generated 4 benchmarks that use `+, -, *` ops (fastops)
-and 4 benchmarks that use `+, -, *, /, %` (allops). Each of the 4 benchmarks uses exactly
-the same arithmetic expressions for all types. Benchmarks on bytes and shorts wrap back
-to corresponding type after each operation.
-
-The split between fastops and allops is important because unsigned division is
-quite a bit slower than signed one on latest release of JDK 8:
-
- Benchmark Type Score Error Units
-
- division Int 289644141.092 ± 1544.707 ops/s
- division UInt 129838344.866 ± 95523.094 ops/s
- division Long 129839962.558 ± 90581.655 ops/s
- division ULong 116493219.034 ± 67688.631 ops/s
-
- remainder Int 289454769.011 ± 94380.057 ops/s
- remainder UInt 111032938.420 ± 679921.289 ops/s
- remainder Long 128315753.345 ± 35932.509 ops/s
- remainder ULong 97470062.788 ± 346773.054 ops/s
-
-And here are the results of composite benchmarks.
-
- Benchmark Type Score Error Units
-
- allop0 Byte 76612958.318 ± 97814.015 ops/s
- allop0 UByte 26160709.822 ± 2098.556 ops/s
- allop0 Short 76800575.238 ± 75373.970 ops/s
- allop0 UShort 27172978.979 ± 3244.075 ops/s
- allop0 Int 82816920.142 ± 50194.565 ops/s
- allop0 UInt 27232792.726 ± 5116.920 ops/s
- allop0 Long 28648964.226 ± 6115.162 ops/s
- allop0 ULong 29657228.040 ± 159758.363 ops/s
-
- allop1 Byte 73715102.215 ± 17282.291 ops/s
- allop1 UByte 26490808.836 ± 86628.862 ops/s
- allop1 Short 73718029.884 ± 19413.132 ops/s
- allop1 UShort 27041330.181 ± 4533.663 ops/s
- allop1 Int 83239625.538 ± 13575.756 ops/s
- allop1 UInt 28425497.966 ± 10927.728 ops/s
- allop1 Long 29251967.961 ± 8278.100 ops/s
- allop1 ULong 30537156.474 ± 14283.996 ops/s
-
- allop2 Byte 53138040.117 ± 7692.219 ops/s
- allop2 UByte 19912528.484 ± 104896.763 ops/s
- allop2 Short 52989318.748 ± 10075.293 ops/s
- allop2 UShort 19828139.740 ± 217.796 ops/s
- allop2 Int 60104405.263 ± 1888.322 ops/s
- allop2 UInt 20576204.367 ± 446.445 ops/s
- allop2 Long 20752333.428 ± 789.741 ops/s
- allop2 ULong 22949083.651 ± 5766.597 ops/s
-
- allop3 Byte 68147811.661 ± 7349.838 ops/s
- allop3 UByte 28016596.929 ± 4795.992 ops/s
- allop3 Short 68147020.665 ± 8444.864 ops/s
- allop3 UShort 29092855.210 ± 12323.477 ops/s
- allop3 Int 93592095.470 ± 2970.030 ops/s
- allop3 UInt 33298135.046 ± 15681.174 ops/s
- allop3 Long 32276341.887 ± 3748.706 ops/s
- allop3 ULong 53345993.564 ± 5486.483 ops/s
-
- fastop0 Byte 174384841.686 ± 13685.151 ops/s
- fastop0 UByte 172490336.775 ± 42178.142 ops/s
- fastop0 Short 174388762.469 ± 10303.837 ops/s
- fastop0 UShort 172545184.374 ± 37150.012 ops/s
- fastop0 Int 335919041.150 ± 121423.806 ops/s
- fastop0 UInt 335925277.378 ± 120408.170 ops/s
- fastop0 Long 339125057.494 ± 71538.513 ops/s
- fastop0 ULong 339306595.964 ± 70387.619 ops/s
-
- fastop1 Byte 174736448.461 ± 9934.579 ops/s
- fastop1 UByte 173817403.787 ± 20752.221 ops/s
- fastop1 Short 174734415.599 ± 9850.473 ops/s
- fastop1 UShort 173460828.250 ± 18068.154 ops/s
- fastop1 Int 285178506.838 ± 129027.835 ops/s
- fastop1 UInt 285137070.275 ± 145958.174 ops/s
- fastop1 Long 285590926.722 ± 147048.419 ops/s
- fastop1 ULong 274695574.679 ± 4878290.228 ops/s
-
- fastop2 Byte 168971931.233 ± 40481.486 ops/s
- fastop2 UByte 169665745.096 ± 27401.842 ops/s
- fastop2 Short 168979347.127 ± 11033.548 ops/s
- fastop2 UShort 169675543.605 ± 19494.266 ops/s
- fastop2 Int 287563728.176 ± 122987.272 ops/s
- fastop2 UInt 287559086.868 ± 126833.074 ops/s
- fastop2 Long 296129286.397 ± 171488.897 ops/s
- fastop2 ULong 296142819.979 ± 167330.949 ops/s
-
- fastop3 Byte 333536457.973 ± 63928.967 ops/s
- fastop3 UByte 339343014.623 ± 119819.041 ops/s
- fastop3 Short 333535961.005 ± 69587.789 ops/s
- fastop3 UShort 339354474.225 ± 121131.393 ops/s
- fastop3 Int 475167307.642 ± 140060.266 ops/s
- fastop3 UInt 475181473.416 ± 116982.494 ops/s
- fastop3 Long 487109297.325 ± 580807.835 ops/s
- fastop3 ULong 487190439.786 ± 737565.041 ops/s
-
-As you can see, fastops results have statistically insignificant differences
-between signed and unsigned numbers. The same is true for allops for `Long` vs
-`ULong`.
-
-Allops are 2-3x slower for `Byte`s, `Short`s and `Int`s, due to the fact that
-unsigned division isn't as well optimised. We can probably make divisions for
-`UByte` and `UShort` faster by using the regular division at the `Int` level,
-but the current implementation does not do that yet.
-
-### Time frame
-
-We propose that unsigned integers be integrated in their user-space form as
-early as possible, ideally in Scala 2.12, should this proposal be accepted in
-time. An implementation is already available for Scalac, and it comes with an
-exhaustive unit test suite.
-
-In the longer term, for 2.13 or 2.14, we propose to evaluate whether the
-benefits of a compiler-space implementation outweigh the risks. The existing
-test suite will make sure that the behavior of operations is unchanged. This
-second phase should probably be studied jointly with the developments of
-ScalaNative.
-
-## Previous discussions and implementations
-
-When
-[Value Classes (SIP-15)](https://docs.scala-lang.org/sips/value-classes.html)
-were first introduced, the possibility to have new numeric types such as
-unsigned integers was mentioned as a motivation. Subsequently, several people
-[came up with implementations](https://groups.google.com/forum/#!topic/scala-sips/xtmUjsY9gTY)
-of unsigned Ints and Longs. Those implementations were however more hacky
-proofs of concept than a really thought-out proposal.
-
-Our proposal improves on those early attempts in several aspects:
-
-* Comprehensive but curated set of operations that are available on unsigned
- integers, in particular no mixing signed and unsigned integers (avoid common
- pitfalls found in other languages)
-* Precise semantics for all operations (a specification)
-* A meaningful notion of equality, which works well with other primitive types
-* Use JDK 8 methods to implement operations that are specific to unsigned
- integers, such as division
-* Complete implementation with a test and benchmark suites
-
-## Out of scope
-
-The following related aspects are out of the scope of this proposal:
-
-### Literal notation for unsigned integers
-
-This proposal does not introduce any literal notation for unsigned integers.
-Instead, we always convert from signed literals, e.g., `5.toUInt`.
-
-Providing literal notation should be done in the context of a SIP for
-generalized user-defined literals.
-
-### Efficient arrays of unsigned integers
-
-We do not plan to address the issue of efficient arrays of unsigned integers.
-Solving this should be part of a broader context for efficient arrays of
-user-defined value classes in general, such as the encoding used in Dotty.
-
-## Unresolved questions
-
-* Should `>>` be available on unsigned integers?
-* Should `null` unbox to 0 for unsigned integers even in their user-space
- implementation? This would require some more changes to the compiler.
-
-## References
-
-1. [Implementation mostly in user-space for scalac/JVM](https://github.com/scala/scala/compare/2.12.x...sjrd:uints)
diff --git a/_sips/sips/2016-09-09-inline-meta.md b/_sips/sips/2016-09-09-inline-meta.md
deleted file mode 100644
index 8aa401d125..0000000000
--- a/_sips/sips/2016-09-09-inline-meta.md
+++ /dev/null
@@ -1,1012 +0,0 @@
----
-layout: sip
-title: SIP-28 and SIP-29 - Inline meta
-vote-status: dormant
-vote-text: This proposal needs an owner.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/inline-meta.html
----
-
-**By: Eugene Burmako, Sébastien Doeraene, Vojin Jovanovic, Martin Odersky, Dmitry Petrashko, Denys Shabalin**
-
-## History
-
-| Date | Version |
-| ---------------|----------------------------------------------|
-| Aug 22nd 2016 | Initial Pre-SIP |
-| Sep 9th 2016 | Initial SIP |
-
-## Preface
-
-This document represents the culmination of a design process that spans several years.
-We did our best to extensively evaluate the design space and comprehensively document our findings.
-
-As a result, this is going to be a very long read. If you're just interested in getting a quick idea
-of the proposal, you can read just the ["Intuition"][Intuition] section.
-
-## Motivation
-
-Def macros and macro annotations have become an integral
-part of the Scala ecosystem. They marry metaprogramming with types
-and work in synergy with other language features, enabling [practically important use cases][MacroUsecases].
-
-However, in addition to having the reputation of an indispensable tool, Scala macros have also gained notoriety
-as an arcane and brittle technology. The most common criticisms of Scala macros concern their
-subpar tool support and overcomplicated metaprogramming API powered by scala.reflect.
-
-While trying to fix these problems via evolutionary changes to the current macro system,
-we have realized that they are all caused by the decision to use compiler internals as the underlying metaprogramming API.
-Extensive use of desugarings and existence of multiple independent program representations may have worked well
-for compiler development, but they turned out to be inadequate for a public API.
-
-The realization that we cannot make meaningful progress while staying within the confines of scala.reflect
-meant that our macro system needs a redesign. We took the best part of the current macros - their smooth integration
-into the language - and discarded the rest, replacing scala.reflect with a better metaprogramming API
-and coming up with a lightweight declaration syntax. In this document, we present the current version of the design.
-
-## Table of contents
-
- * [Intuition](#intuition)
- * [Def macros](#def-macros)
- * [Discussion](#discussion)
- * [Inline/meta](#inlinemeta)
- * [Language features](#language-features)
- * [Inline definitions](#inline-definitions)
- * [Inline reduction](#inline-reduction)
- * [Meta expressions](#meta-expressions)
- * [Meta expansion](#meta-expansion)
- * [Meta APIs](#meta-apis)
- * [Design considerations](#design-considerations)
- * [Scala.meta](#scalameta)
- * [Tool support](#tool-support)
- * [Losing whiteboxity](#losing-whiteboxity)
- * [Losing compiler internals](#losing-compiler-internals)
- * [Macro annotations](#macro-annotations)
- * [Why inline](#why-inline)
- * [Out of scope](#out-of-scope)
- * [Conclusion](#conclusion)
- * [Credits](#credits)
-
-## Intuition
-
-In this section, we will walk through writing and using compile-time metaprograms that implement a subset of functionality
-expected of language-integrated queries. Without going into much detail,
-we will obtain high-level intuition behind the underlying mechanisms
-
-[Language-integrated query][Linq] is a technique that achieves smooth integration of database queries with programming languages.
-A common approach to LINQ, popularized by .NET Framework 3.5, consists in representing datasources
-by collection-like library types and then allowing users to write queries as series of calls to these types
-using familiar higher-order methods like `map`, `filter` and others.
-
-We will now develop a sketch of a database access library built in the spirit of LINQ.
-In this sketch, we will intentionally forgo the practicalities of building a LINQ library
-(e.g. mapping from classes to datasources, design of internal ASTs, error reporting, etc.)
-in order to clearly illustrate the role played by compile-time metaprogramming.
-
-Below we define a trait `Query[T]` that encapsulates a query returning a collection
-of objects of type `T`. Next to it, we define its children `Table` and `Map` that represent
-particular types of queries. `Table` stands for a datasource that knows about the underlying type
-(in this sketch, we use an imaginary typeclass `TypeInfo` for that purpose).
-`Map` models a restricted subset of SQL SELECT statements via a simple `Node` AST.
-
-```
-trait Query[T]
-case class Table[T: TypeInfo]() extends Query[T]
-case class Select[T, U](q: Query[T], fn: Node[U]) extends Query[U]
-
-trait Node[T]
-case class Ref[T](name: String) extends Node[T]
-
-object Database {
- def execute[T](q: Query[T]): List[T] = { ... }
-}
-```
-
-In this model, a SQL query string `"SELECT name FROM users"` is represented as `Select(Table[User](), Ref[String]("name"))`.
-Queries like the one just mentioned can be run via `Database.execute` that translates them into SQL, sends the SQL to the database,
-receives the response and finally translates it to data objects. For the sake of simplicity, we will assume such implementation as a given.
-
-The key aspect of a LINQ facility is a convenient notation for queries.
-Arguably, none of the aforementioned ways to write queries can be called convenient.
-SQL, as any string-based representation, is prone to syntax errors, type errors and injections.
-Explicit instantiation of `Query` objects is very verbose, and still doesn't solve all type errors.
-
-In this sketch, we define a LINQ API in the form of methods that mirror the collection API
-from the standard library. We would like our users to be able to encode queries in intuitively looking,
-statically typed calls to this API, e.g. `users.map(u => u.name)`, and then have our library translate these
-calls into calls to `Query` constructors.
-
-```
-object Query {
- implicit class QueryApi[T](q: Query[T]) {
- def map[U](fn: T => U): Query[U] = { ... }
- }
-}
-
-case class User(name: String)
-val users = Table[User]()
-users.map(u => u.name)
-// translated to: Select(users, Ref[String]("name"))
-```
-
-Among other ways, the desired effect can be achieved with compile-time metaprogramming.
-A metaprogram that runs at compile time can detect all calls to `Query.map` and rewrite them
-to invocations of `Select` with parameters of `map` transformed to corresponding instances of `Node`.
-
-### Def macros
-
-Before looking into the design of the new macro system, let's see how the problem at hand
-can be solved using the currently available macro system.
-
-```
-import scala.language.experimental.macros
-
-object Query {
- implicit class QueryApi[T](q: Query[T]) {
- def map[U](fn: T => U): Query[U] = macro QueryMacros.map
- }
-}
-```
-
-`QueryApi.map` is called a macro def. Since macros are experimental,
-in order to define a macro def, it is required to either have `import scala.language.experimental.macros`
-in the lexical scope of the definition or to enable the corresponding setting in compiler flags.
-This is only necessary to define a macro def, not to use it.
-
-Macro defs look like normal methods in the sense that
-they can have term parameters, type parameters and return types.
-Just like regular methods, macro defs can be declared either inside or outside of classes,
-can be monomorphic or polymorphic, and can participate in type inference and implicit search.
-Refer to [Appendix A][AppendixInteraction] for a detailed account of differences
-between macro defs and regular defs.
-
-Bodies of macro defs have an unusual syntax. The body of a macro def starts with the conditional keyword `macro` and
-is followed by a possibly qualified identifier that refers to a macro impl,
-an associated metaprogram run by the compiler when it encounters corresponding macro applications.
-Macro impls are defined as shown below.
-
-```
-import scala.reflect.macros.blackbox.Context
-
-object QueryMacros {
- def map(c: Context)(fn: c.Tree): c.Tree = {
- import c.universe._
- ...
- }
-}
-```
-
-Macro impls take a compiler context that represents the entry point into the macro API.
-The macro API consists of a general-purpose metaprogramming toolkit provided by scala.reflect
-and several specialized facilities exclusive to macro expansion.
-A typical first line of a macro impl is `import c.universe._` that makes the entire scala.reflect API available to the metaprogrammer.
-
-In addition to the compiler context, for every term parameter of a macro def, its macro impl
-takes a term parameter that carries a representation of the corresponding argument of the macro application.
-Macro impls can also get ahold of representation of type arguments, but this functionality is unnecessary for this example.
-
-A macro impl returns an abstract syntax tree, and this AST replaces the original macro application in the compilation pipeline.
-This is how we're going to perform the LINQ translation of calls to `Query.map`.
-
-```
-import scala.reflect.macros.blackbox.Context
-
-object QueryMacros {
- def map(c: Context)(fn: c.Tree): c.Tree = {
- import c.universe._
-
- // c.prefix looks like:
- // Query.QueryApi[]()
- val q"$_.$_[$_]($prefix)" = c.prefix
-
- val node: Tree = fn match {
- case q"($param) => $body" =>
- val sym = param.symbol
- body match {
- case q"$qual.$_" if qual.symbol == sym =>
- q"Ref[${body.tpe}](${sym.name.decodedName.toString})"
- }
- }
-
- q"Select($prefix, $node)"
- }
-}
-```
-
-In the listing above, we handle several challenges of macro writing.
-First, we get ahold of the prefix of the application, i.e. the `users` part of `users.map(u => u.name)`.
-Unlike macro arguments, prefixes aren't mapped onto parameters of macro impls,
-so we need to use the dedicated `c.prefix` API.
-
-The next challenge is to extract the prefix from the macro application.
-Since `Query.map` is an extension method, the actual prefix is going to be `QueryApi(users)`, not `users`,
-therefore we need to apply some non-trivial effort.
-
-One way of getting to the query is to access the corresponding field of the implicit class,
-doing something like `QueryApi(users).q`. Unfortunately, this is out of the question, because `q` is private,
-and we cannot make it public without adding an extension method called `q` to `Query`.
-
-Another way of achieving the desired result is to take apart the abstract syntax tree representing `QueryApi(users)`,
-extracting `users` as the argument of the application.
-It looks like quasiquotes,
-which are supposed to provide a convenient WYSIWYG interface to deconstructing Scala code,
-are going to be a perfect fit.
-
-Unfortunately for macro writers, the Scala compiler heavily desugars code during compilation,
-so even the modest `QueryApi(users)`
-will get to the macro impl in the form of `Query.QueryApi[User](users)`.
-Therefore the naive `q"$_($query)"` quasiquote is not going to work,
-and we need to apply additional effort. With a bit of knowledge about compiler internals,
-we take care of this.
-
-The final challenge is code generation.
-The pattern match in listing above transforms the user-provided lambda expression into an equivalent `Node`.
-Since our sketch only supports `Ref`, we only support simple lambdas that select a field from a parameter.
-Finally, we produce the macro expansion that has the desired shape.
-
-### Discussion
-
-Note how the ability of def macros to access types dramatically improves user experience in comparison with purely syntactic translation.
-First, even before `Query.map` gets to expand, the compiler typechecks its argument, making sure that
-queries are well-typed. Secondly, we have a way to reliably check the shape of the supported lambda.
-The symbol comparison in the nested pattern match makes sure that
-the qualifier of field selection refers precisely to the parameter of the lambda
-and not to something else accidentally having the same name. Finally, we use information about the type of the body
-in order to figure our the mandatory type parameter of `Ref`.
-
-Also note another piece of knowledge about compiler internals that was essential to robust operation of the macro.
-When generating a `Ref`, we can't simply call `sym.name.toString`, because the Scala compiler internally mangles non-alphanumeric names.
-If the parameter of the lambda has such a name, a simple `toString` will produce unsatisfying results,
-which is why we have to call `Name.decodedName` first.
-
-Before we conclude, let's highlight a very common metaprogramming mistake that we've just made in `QueryMacros.map`.
-Def macros are unhygienic, which means that they don't prevent inadvertent name capture, i.e. scenarios like the following.
-
-```
-val Select = "hijacked!"
-users.map(u => u.name)
-
-// error: too many arguments for
-// method apply: (index: Int)Char in class StringOps
-// users.map(u => u.name)
-// ^
-```
-
-If the macro user accidentally defines a term called `Select` or `Ref`, our macro is going to stop working
-with what looks like a nonsensical error message. Because principled tool support wasn't among the design goals of
-our macro system, a macro user getting this error is mostly helpless apart from trying to use internal compiler options
-that print all macro expansions and then going through the resulting wall of text.
-
-One reliable approach to prevent hygiene errors is to use fully-qualified names for external references and
-to generate unique names for local variables. A somewhat more concise, but potentially much more laborious approach is to explicitly
-assign symbols to references and definitions emitted in macro expansions.
-This approach often requires extensive knowledge of compiler internals, so it is less frequent in the wild.
-Common to both of these approaches is that they require explicit attention from metaprogrammers and
-failures to apply them typically go unnoticed.
-
-To sum it up, even in this simple macro we encountered situations where knowledge of compiler internals
-(the desugaring of the `QueryApi` application, the fact that non-alphanumeric names are encoded) was essential.
-We also ran into problems with tool support and hygiene, which demonstrates how important they are to a macro system.
-These are all common criticisms of def macros.
-
-### Inline/meta
-
-User interface of def macros is a seamless extension to the existing language interface.
-Thanks to macro defs looking like regular methods and macro applications looking like regular method applications,
-macro users are likely to not even realize that they are using macros.
-
-Unfortunately, metaprogrammer interface leaves much to be desired. First, in the current macro system,
-metaprograms have to be defined separately from their signatures, typically involving helper objects and
-duplication of parameters. Secondly, the underlying metaprogramming API requires
-knowing bits and pieces of compiler internals. For example, in the case of `Query.map`,
-the metaprogrammer had to know the internal representation of the `QueryApi` application
-and internal details of how names are represented.
-
-New-style macros provide the same user interface, and at the same time significantly improve metaprogrammer
-interface by enabling lightweight macro declaration syntax and using a better metaprogramming API.
-
-```
-object Query {
- implicit class QueryApi[T](q: Query[T]) {
- inline def map[U](fn: T => U): Query[U] = meta {
- import scala.meta._
-
- val q"$_($prefix)" = this
-
- val node: Tree = fn match {
- case q"($name: $_) => $body" =>
- body match {
- case q"$qual.$_" if qual =:= name =>
- q"Ref[${body.tpe}](${name.toString})"
- }
- }
-
- q"Select($prefix, $node)"
- }
- }
-}
-```
-
-At a glance, new-style macros simply forgo a noticeable amount of ceremony,
-merging the previously disparate macro defs and macro impls as well as swapping around a few keywords in the process.
-The underlying metaprogram doesn't seem to have changed much,
-still using quasiquotes and key APIs like `Tree.tpe` and `Name.toString`.
-
-First impression notwithstanding, the new design revamps a lot of underlying mechanisms.
-Below we provide a high-level overview of our new approach to compile-time metaprogramming,
-and refer curious readers to ["Language features"][LanguageFeatures] for information concerning the new expansion mechanism
-and to ["Scala.meta"][ScalaMetaSection] for details about the new metaprogramming API.
-
-**Expansion mechanism**. The new design takes the notions of inlining and compile-time execution
-from the current macro system and turns them into separate language features.
-
-The goal of the `inline` modifier on `Query.map` is to signify that applications of this method are inlined,
-i.e. replaced with the method body, in which references to enclosing `this`, self, and formal parameters are rewritten accordingly
-(see ["Inline reduction"][InlineExpansion] for details).
-
-The goal of the `meta` keyword is to demarcate code that executes at compile time and to provide
-that code with [scala.meta capabilities][MetaApis].
-The metaprogram written inside the meta scope has access to multiple implicit capabilities
-and can get ahold of representations of certain values and types from lexical scope.
-The compiler runs this metaprogram, interprets its result as an abstract syntax tree
-and replaces the meta expression with that tree (see ["Meta expansion"][MetaExpansion] for details).
-
-When the compiler encounters a call to `Query.map`,
-it simply inlines the body of `map` into the callsite without performing any compile-time function execution.
-For the running example of `users.map(u => u.name)`,
-this inlining produces the result illustrated in the listing below.
-
-```
-{
- val prefix$1: QueryApi = QueryApi(users)
- val fn$1: User => String = u => u.name
- meta {
- import scala.meta._
-
- val q"$_($prefix)" = q"QueryApi(users)"
-
- val node: Tree = q"u => u.name" match {
- case q"($name: $_) => $body" =>
- body match {
- case q"$qual.$_" if qual =:= name =>
- q"Ref[${body.tpe}](${name.toString})"
- }
- }
-
- q"Select($prefix, $node)"
- }
-}
-```
-
-Before inlining a method application, the compiler first hoists the prefix and by-value arguments of the application
-into temporary variables. This is done in order to guarantee that applications of inline methods
-are semantically equivalent to applications of regular methods.
-
-Afterwards, the compiler replaces the application with a block that consists of hoisted values and the transformed method body.
-In the method body, all regular references to `this` and self as well as
-by-value parameters are rewritten to references to the corresponding temporary variables.
-If such references are part of a meta scope, they are replaced with scala.meta-based representations of
-the prefix and the corresponding arguments, without going into temporary variables.
-
-When the compiler comes across a meta expression that isn't part of an inline method,
-it executes the code inside the expression and replaces the expression with the result of execution.
-For our running example, this produces the desired expansion that invokes query constructors corresponding
-to the LINQ notation.
-
-**New metaprogramming API**. Scala.meta noticeably improves on scala.reflect in the convenience of the API
-and no longer requires metaprogrammers to understand compiler internals in order to write macros.
-
-In particular, we don't need to know that construction of the implicit class involves
-expanding the reference to `QueryApi` into a fully-qualified name and inferring the missing type argument.
-The particular implementation of the scala.meta API that runs the meta expression may or may not
-do these desugarings, and scala.meta shields us from this fact.
-We can use the WYSIWYG pattern `q"$_($prefix)"` in order to unwrap the original prefix of the call.
-
-Moreover, we don't have to worry about the compiler internally mangling non-alphanumeric names.
-Again, even if the underlying macro engine internally does name mangling, scala.meta abstracts away such implementation details.
-
-Finally, we are able to improve on scala.reflect thanks to more precise quasiquotes.
-If in the current macro system, we used `q"($name: $_) => ..."` to match the `fn` argument,
-`name` would capture a scala.reflect `Name` that doesn't carry any semantic information.
-In scala.meta, names are full-fledged trees, so we can use `Tree.=:=` to semantically compare the name
-with the qualifier of the field selection.
-
-In order to use semantic APIs, scala.meta metaprograms need the [mirror capability][ScalaMetaSection],
-so it is implicitly provided inside meta scopes. As a result, meta expressions can use the full spectrum
-of APIs available in scala.meta.
-
-**To put it in a nutshell**, the new-style macro system combines two language features:
-[inline definitions][InlineDefs] and [meta expressions][MetaExprs]
-in order to provide a more lightweight syntax for the current def macros. Moreover, this macro system
-does a switchover from scala.reflect to scala.meta, featuring a new API that is more convenient and
-doesn't require compiler knowledge to be utilized effectively.
-
-## Language features
-
-### Inline definitions
-
-We introduce a new reserved word: `inline`, which can be used as a modifier for
-concrete vals, concrete methods and parameters of inline methods, as illustrated in the listing below.
-
-```
-inline val x = 4
-
-inline def square(x: Double) = x * x
-
-inline def pow(b: Double, inline n: Int): Double = {
- if (n == 0) 1
- else b * pow(b, n - 1)
-}
-```
-
-Inline vals are guaranteed to be compile-time constants, superseding the existing approach
-of declaring such constants with `final val`. Inline parameters get the same treatment, adding a previously
-non-existent functionality of guaranteeing that an argument of a method is a compile-time constant.
-
-A value is considered to be a compile-time constant if it is a Scala literal,
-or it is equivalent to one by the means of inline/meta expansion and constant folding.
-Future work may extend this notion to custom classes, but this discussion lies outside the scope of this proposal.
-
-Inline defs are guaranteed to be inlined at compile time, superseding the existing approach of
-annotating methods with the `@inline` annotation. After introducing `inline`, we expect to deprecate and phase out `@inline`.
-
-The problem with `@inline` is that it doesn't provide guarantees.
-As specified in documentation,
-`@inline` tells the compiler to "try especially hard to inline the annotated method".
-However, different backends interpret this request differently.
-The JVM backend ignores this annotation if optimizations are disabled and sometimes skips inlining even when optimizations are enabled.
-Both Scala.js and Scala Native always inline methods that are marked with this annotation.
-In contrast, `inline` achieves guaranteed inlining, regardless of the backend.
-
-Inline defs are very similar to macro defs in the sense that they look like regular defs and that they expand at compile time.
-As a result, the rules in [Appendix A][AppendixInteraction] also apply to inline defs with three exceptions.
-
- 1. Inline defs are effectively final; they cannot be overridden. Inline members also never override other members.
-The idea of allowing macro defs to override regular defs didn't find compelling use cases, so we prohibit this for inline defs.
-
- 1. Inline defs can have default parameters. Not supporting default parameters for macro defs was an oversight
-of the initial design, so now we fix this oversight in the new macro system.
-
- 1. Inline defs have regular bodies, just like regular defs. When an inline def is typechecked, its body
-is typechecked according to the usual rules, which means that inline defs are eligible for return type inference. If an inline def
-doesn't explicitly specify its result type, the result type gets inferred from the type of its body.
-
-### Inline reduction
-
-When the compiler encounters certain patterns of code that involve references to inline vals and applications of inline defs,
-it will perform the rewritings provided below, if and only if these patterns appear outside the bodies of inline vals and defs.
-
- 1. If `prefix.v` refers to an inline value, replace the expression with the body of `v`.
-
- 1. If `prefix.f[Ts](args1)...(argsN)` refers to a fully applied inline method, hoist the prefix and the arguments
-into temporary variables with fresh names and then replace the expression with the method body. In the body, replace parameter references
-with references to temporary variables created for the corresponding arguments. Also, replace enclosing `this`
-and self references with references to the temporary variable created for the prefix.
-
- ```
- {
- val prefix$1 = prefix
- val param1$1 = arg1
- ...
- val paramN$1 = argN
-
- }
- ```
-
- The hoisting is intended to preserve the semantics of method applications under inlining.
- A method call should have the same semantics with respect to side effects independently
- on whether the method was made inline or not.
- If an inline method has by-name parameters, then corresponding arguments are not hoisted.
-
- The rewriting is done in accordance with hygiene. Any references from the method body to its lexical scope
- will be kept in the rewritten code. If the result of the rewriting references private or protected definitions
- in the class that defines the inline method, these references will be changed to use accessors generated automatically by the compiler.
- To ensure that the rewriting works in the separate compilation setting,
- it is critical for the compiler to generate the accessors in advance.
- Most of these accessors can be pregenerated by analyzing the bodies of inline methods,
- except for members that are referred to inside meta scopes.
- Such references are disallowed, because it is impossible to generate them in advance.
-
- 1. If `prefix.f[Ts](args1)...(argsN)` refers to a partially applied inline method, an error is raised.
-Eta expansion of inline methods is prohibited.
-
-The rules of inline reduction are similar to the rules of feature interaction for macro applications ([Appendix A][AppendixInteraction])
-as well as relevant parts of the rules of def macro expansion ([Appendix B][AppendixExpansion]) with four exceptions.
-
- 1. Inline reductions in their current form preclude whitebox expansion.
-Since bodies of inline vals and defs are typechecked when their definitions are typechecked,
-potential meta expansions that may happen afterwards won't be able to change their types.
-Implications of this are discussed in ["Losing whiteboxity"][Whiteboxity].
-
- 1. By-value and by-name arguments behave differently. By-value arguments are hoisted in temporary variables,
-while by-name arguments remain as they were. This doesn't affect meta expansions,
-but it does make a semantic difference for parts of inline definitions that are not inside meta scopes.
-Note that `this` and self references always follow the by-value scheme,
-because there is no syntax in Scala that allows to define them as by-name.
-
- 1. Named and default arguments are fully supported. Again, not including them in the initial release of def macros
-was an oversight, which is now fixed.
-
- 1. The rules of rewriting mandate the "outside in" style, i.e. calls to inline methods are expanded before possible calls
-to inline methods in their prefixes and arguments. This is different from how the "inside out" style of def macros,
-where prefixes and arguments are expanded first. Previously, it was very challenging to
-take a look at unexpanded trees, but now the metaprogrammer can switch between unexpanded and expanded views using scala.meta.
-
-From the discussion above, we can see that inline reduction closely resembles the inlining aspect of the current macro system.
-The only significant difference is lack of support for whitebox expansion, which will be discussed in ["Losing whiteboxity"][Whiteboxity].
-
-### Meta expressions
-
-A meta expression is an expression of the form `meta { ... }`, where `{ ... }` is some block of Scala code, called meta scope.
-(In fact, `meta` may prefix arbitrary expressions, but blocks are expected to be used most commonly).
-
-Meta expressions can appear both
-in the bodies of inline methods (then their expansion is going to be deferred until the enclosing method expands)
-and in normal code (in that case, their expansion will take place immediately at the place where the meta expression is written).
-
-Meta scopes can contain arbitrary code, but they must return values that are either of type `scala.meta.Term` or are convertible
-to it via the `scala.meta.Lift` typeclass. There are standard instances of the typeclass that lift simple values to literals
-as well as ones that support frequently used collections of liftable values. Metaprogrammers may define and use their own instances
-as long as they are available in corresponding meta scopes.
-
-Inside meta scopes, metaprogrammers can use a combination of general-purpose and expansion-specific metaprogramming facilities.
-Refer to ["Meta APIs"][MetaApis] for more information.
-
-Since meta scopes must return scala.meta trees, and scala.meta trees are by design statically untyped,
-the type of meta expressions can't be computed from the inside
-and has to come from the outside. Therefore, meta expressions can only be used in contexts that specify an expected type.
-
-```
-// allowed, expected type provided by the return type
-inline def map[U](fn: T => U): Query[U] = meta { ... }
-
-// not allowed, no explicit return type
-val x = meta { ... }
-
-// allowed, expected type of a condition is Boolean
-if (meta(T.isPrimitive)) { ... }
-```
-
-Meta scopes can reference names in their lexical scope outside the enclosing meta expression.
-While crossing the `meta` boundary, references change their meaning.
-Concretely, here's how the transformation works for different references:
-
-**Inline vals and inline parameters**. These are guaranteed to be compile-time constants,
-so an inline value of type `T` is available inside a meta scope as a regular value of type `T`.
-
-**Inline defs**. When viewed from within a meta scope, inline defs become tree transformers.
-Types of their inline parameters are unchanged, their non-inline parameters and return type become typed as `scala.meta.Term`.
-For example, `inline def pow(b: Double, inline n: Int): Double` transforms into
-`def pow(b: scala.meta.Term, n: Int): scala.meta.Term`.
-
-**Term parameters of an inline method**. References to statically known term parameters,
-enclosing `this` or self become values of type `scala.meta.Term`. This is similar to `c.Expr`/`c.Tree`
-parameters of macro impls, but more lightweight, because there's no need
-to declare these parameters explicitly.
-
-**Type parameters of an inline method**. References to statically known type parameters become values
-of type `scala.meta.Type`. This is similar to `c.WeakTypeTag` parameters of macro impls,
-but more lightweight, because metaprogrammers don't need to explicitly manifest their interest in given type parameters
-in order to get access to their representations.
-
-This rule can create clashes between term and type namespaces.
-If such a clash happens, i.e. if a reference to a type parameter is ambiguous with an eponymous term,
-the compiler emits an error. This is regrettable, but Scala naming conventions make this situation unlikely,
-and there is always a workaround of renaming the type parameter.
-
-**Global definitions**. Statically available types and terms, e.g. `List` or `Int`,
-are usable inside meta scopes as themselves. This means that meta expressions, just like macro impls,
-can use the standard library and arbitrary third-party libraries.
-
-**Other definitions**. Macro scopes cannot reference definitions that don't fall into one of the categories mentioned above.
-This outlaws usages of local definitions - both terms and types. Such definitions may refer to state that only
-exists at runtime, so we prohibit them altogether. This has no analogues in the current macro system, because macro impls
-must be defined in static methods, which means that by definition their scope cannot contain local definitions.
-
-In other words, definitions that are statically available outside meta scopes remain available in meta scopes,
-term and type arguments of inline methods become available as their representations,
-while signatures of inline methods are recursively transformed according to the rules above.
-
-From the discussion above, we can see that meta expressions provide an analogue of the compile-time execution part
-of the current macro system. In addition to achieving feature parity, meta expressions also improve on the corresponding part of def macros
-by allowing metaprograms to easily obtain representations of their term and type parameters and
-making it possible to run anonymous snippets of metaprogramming code without wrapping them in a dedicated macro.
-
-### Meta expansion
-
-When the compiler encounters a meta expression that appears outside the bodies of inline vals and defs,
-it expands that expression as described below.
-
-A meta expression is expanded by evaluating its body and replacing the original meta expression with an expression
-that represents the result of the evaluation. The compiler is responsible for providing [the capabilities][MetaApis]
-necessary for meta scopes to evaluate and for converting between its internal representation for language model elements
-and representations defined in scala.meta, such as `scala.meta.Term` and `scala.meta.Type`.
-
-Meta expansion works very similarly to the relevant part of the def macro expansion pipeline ([Appendix B][AppendixExpansion]).
-Code in the meta scope is precompiled and then reflectively invoked by the compiler, sharing the class loader with other
-metaprograms run inside the compiler. Expansion can return normally or can be interrupted with an exception. Expansion results
-are typechecked against the expected type of the meta expression. Typecheck results are upcast to the expected type in blackbox style,
-as discussed in ["Losing whiteboxity"][Whiteboxity].
-
-Another practicality of meta expansion is the protocol of communication between `inline` and `meta`.
-On the one hand, a reasonable default for inlining that doesn't involve meta expressions is to hoist prefixes and by-value arguments
-as described in ["Inline reduction"][InlineExpansion]. On the other hand, macro writers default to having unfettered access to
-abstract syntax trees without needing to write additional boilerplate.
-These two design preferences are at odds with each other.
-
-Therefore, in our design `inline` both hoists eligible components of inline applications and passes their original
-representations into meta expressions. This way, both defaults are satisfied and, additionally, if meta expressions need
-to hoist something, they can use the new `hoist` API.
-
-In the case when an inline method consists in a single meta expression, the new macro engine removes temporary variables
-that are produced by hoisting and aren't claimed by `hoist`. In the case when an inline method doesn't contain
-meta expressions, all temporary variables are retained, because they are necessary to express method application semantics.
-Finally, in the case of a hybrid inline method, meta expressions can look into representations of hoisted expressions,
-but they cannot use them in their expansions without calling `hoist` first in order to avoid reordering or duplicating side effects.
-
-In a nutshell, meta expansion closely resembles the compile-time execution aspect of the current macro system.
-The only nuance is the interaction with hoisting performed by the mechanism of inline reduction.
-
-### Meta APIs
-
-In scala.meta, all APIs are available out of the box after doing `import scala.meta._`.
-However, in order to use most of them, metaprogrammers must have access to certain capabilities
-(see ["Scala.meta"][ScalaMetaSection] for details).
-
-Meta scopes provide two different capabilities. First, there are general-purpose metaprogramming facilities,
-enabled by a `Mirror`. Secondly, there are expansion-specific facilities enabled via a newly introduced `Expansion`.
-
-Mirrors are explained in ["Scala.meta"][ScalaMetaSection], and in this section
-we will cover the functionality enabled by expansions. We will also compare this functionality
-with macro APIs from the current macro system.
-
-First, `Context.prefix` is no longer necessary,
-because meta expressions can refer to prefixes of enclosing inline definitions via `this`.
-`Context.macroApplication` is unnecessary as well, because meta expressions may be written outside inline vals and defs,
-which means that they won't have a corresponding application at all. In the rare cases when it is useful to know
-the position that spans the entire inline application, it can be obtained by traversing prefixes or arguments via `Tree.parent`.
-
-Secondly, much like their counterparts in the current macro system, meta APIs support diagnostic messages.
-Since the only prevalent macro APIs in this group is `Context.abort`, with `Context.error`, `Context.warning`
-and others seeing rare use, we only expose `abort` that works similarly to its predecessor.
-
-Thirdly, we no longer expose APIs that tightly integrate with compiler internals. Most of these APIs take care
-of the limitations of the scala.reflect language model, so in the new metaprogramming framework based on scala.meta
-they are simply unnecessary. Others feature advanced functionality that accesses or manipulates internal compiler state,
-and this exactly the kind of thing that we would like to avoid in the macro system. We discuss the implications in
-["Losing compiler internals"][CompilerInternals].
-
-Finally, we also support `hoist`, which takes a `scala.meta.Term`, precomputes it in a temporary variable
-outside the meta expansion and returns a reference to it.
-Apart from `inline`-compatible precomputation of prefixes and arguments,
-this functionality seems relevant to solving the problem of sharing expansions of [implicit materializers][Materialization],
-so we are confident that it's a useful addition to the macro API.
-
-## Design considerations
-
-### Scala.meta
-
-Scala.meta is a clean-room implementation of a metaprogramming toolkit for Scala,
-designed to be simple, robust and portable. We are striving for scala.meta to become a successor of scala.reflect,
-the current de facto standard in the Scala ecosystem.
-
-We have recently released Scala.meta 1.0.0 that features support for syntactic APIs, such as parsing, tokenization,
-quasiquotes and prettyprinting. We are currently working on Scala.meta v2 that will enable semantic APIs, such as
-typechecking, name resolution and others.
-
-In [Appendix C][AppendixMeta], we provide a high-level overview of the architecture of scala.meta
-along with several practical examples that illustrate its functionality.
-
-### Tool support
-
-The key innovation of the new macro system is the fact that it's based on scala.meta, which finally makes it feasible to
-provide third-party implementations of mirrors.
-
-There now exists a prototype implementation of an IntelliJ mirror, and, in further effort of Mikhail Mutcianko from the IntelliJ team,
-this mirror has become the foundation for [an interactive expander of new-style macro annotations][PrototypeIntellij].
-This recent advancement strongly suggests that it was the right choice to bet on scala.meta to fix
-code compehension and error reporting issues with the current macro system.
-
-This takes some pressure off whitebox macros. In the current macro system, there is a preference towards blackbox macros,
-because they are much friendlier to IntelliJ. Once we have a fully-working mirror for IntelliJ, user experience of blackbox
-and whitebox macros should be equivalent. For additional discussion of whiteboxity from a language design and compiler development
-perspective, refer to ["Losing whiteboxity"][Whiteboxity].
-
-Improvements in support for incremental compilation, testing and debugging also hinge on a capability of scala.meta
-to enable custom mirror implementations.
-However, they also require significant new functionality to be developed in the corresponding tools
-([additional dependency tracking mechanisms for the incremental compiler][SbtMacroSupport] and changes to the vanilla debugger in IDEs).
-
-### Losing whiteboxity
-
-It is desirable for the new design to provide reasonable feature parity with the
-current macro system. So far, the biggest digression from this course is giving up whitebox expansion.
-In this section, we discuss what it will cost us to follow this through, identify the aspects of the new design that
-prevent whiteboxity and propose alternatives.
-
-The main motivation for getting rid of whitebox expansion is simplification - both of the macro expansion pipeline
-and the typechecker. Currently, they are inseparably intertwined, complicating both compiler evolution and tool support.
-Therefore, the new design tries to disentangle these systems.
-
-Let's recapitulate the limitations that def macro expansion applies to applications of blackbox macros,
-outlining the most important use cases that blackboxity cannot express. This won't give us the full picture,
-because there are many macros in the wild that we haven't classified, but nonetheless it will provide an understanding
-of the significant chunk of the Scala macros ecosystem.
-
- 1. When an application of a blackbox macro expands into a tree `x`, the expansion is wrapped into a type ascription `(x: T)`,
-where `T` is the declared return type of the blackbox macro def with type arguments and path dependencies applied in consistency
-with the particular macro application being expanded.
-This invalidates blackbox macros as an implementation vehicle for [anonymous type providers][AnonymousTypeProviders].
-
- 1. When an application of a blackbox macro is used as an implicit candidate, no expansion is performed until the macro
-is selected as the result of the implicit search.
-This makes it impossible to dynamically calculate availability of implicit macros,
-precluding some advanced aspects of [materialization][Materialization].
-
- 1. When an application of a blackbox macro still has undetermined type parameters after the Scala type inference algorithm has finished
-working, these type parameters are inferred forcibly, in exactly the same manner as type inference happens for normal methods.
-This makes it impossible for blackbox macros to influence type inference, prohibiting [fundep materialization][Materialization].
-
- 1. When an application of a blackbox macro is used as an extractor in a pattern match,
-it triggers an unconditional compiler error, preventing [customizations of pattern matching implemented with macros][ExtractorMacros].
-This precludes blackbox macros from providing precise types to values extracted from patterns written in external DSLs,
-preventing a library-based implementation of quasiquotes.
-
-As we can see, whitebox expansion plays an important role in several use cases, the most practically significant
-of them being fundep materialization and quasiquote patterns. Fundep materialization is paramount to the design of Shapeless.
-Quasiquote patterns are an integral part of writing any kinds of macros - both blackbox and whitebox - which is the main
-reason to use scala.reflect.
-
-It is now clear that our desire for simplification is at odds with the ways how the Scala community uses macros.
-In order to resolve the apparent conflict, we outline several solutions, whose evaluation we leave for later.
-
-**Give up on simplification**. This is probably the most obvious approach, in which we admit
-that tight coupling with the typechecker is intrinsic to the essence of Scala macros and change the new design
-to enable whitebox expansion.
-
-Concretely, accommodating whiteboxity in the new macro system requires changing the aspects of the new design
-specified in ["Inline reduction"][InlineExpansion] and ["Meta expansion"][MetaExpansion] according to the
-plan provided below.
-
- * Force inline reductions and meta expansions inside the typechecker. Currently, both the rules of inline reduction
-and the rules of meta expansion are intentionally vague about the exact point in the compilation pipeline that does expansions,
-but whiteboxity will leave us no room for that.
- * Delay typechecking of the bodies of inline vals and defs until their expansion. Meta expressions inside inline definitions
-are not expanded, which means that eager typechecking of these definitions precludes whitebox expansion.
- * Allow using meta expressions without expected type. This captures the main idea of whitebox expansion, in which compile-time
-metaprogramming has the final say about the type of transformed snippets of code.
-
-**Assimilate the most popular use cases**. Instead of supporting the general notion of whiteboxity,
-we can introduce dedicated compiler support for the most popular uses cases including the `Generic`
-mechanism in Shapeless and quasiquote patterns in scala.reflect.
-
-This is an attempt at a compromise. On the one hand, this approach allows us to follow through with simplification.
-On the other hand, it significantly minimizes the impact on the existing users of whitebox macros.
-
-The downside of this solution is that it requires an extensive design process (because it involves adding new language features to Scala)
-and assumes that the internalized techniques have reached their final form. If a new version of Shapeless
-or a new version of scala.reflect (read: scala.meta) decide to adapt their designs after these designs have been assimilated,
-they will have a very hard time doing that.
-
-**Dedicated support for type-level computations**. Manifestations of whiteboxity are quite diverse,
-but a lot of them are reducible to type-level computations.
-
-For example, let's take a macro `join` that takes two objects and outputs an object that
-has fields of both. Since Scala doesn't have row polymorphism, it is impossible to write a type signature
-for this macro, so we have to declare it as whitebox.
-
-```
-scala> def join(x: Any, y: Any): Any = macro ...
-defined term macro join: (x: Any, y: Any)Any
-
-scala> join(new { val x = 2 }, new { val y = 3 })
-res0: AnyRef{val x: Int; val y: Int} = $anon$1@64af328d
-```
-
-Here we can see how the whitebox macro encapsulates a type-level computation that takes
-the types of both arguments (`AnyRef{ val x: Int }` and `AnyRef{ val y: Int }`)
-and merges them into the result type. Since this computation doesn't involve the abstract syntax trees
-of the arguments, the whitebox part of the macro can be extracted into a helper, making the macro itself
-blackbox.
-
-```
-scala> :paste
-// Entering paste mode (ctrl-D to finish)
-
-trait Join[T, U, V]
-object Join {
- implicit def materialize[T, U, V]: Join[T, U, V] = macro ...
-}
-
-// Exiting paste mode, now interpreting.
-
-defined trait Join
-defined object Join
-
-scala> def join[T, U, V](x: T, y: U)
- | (implicit ev: Join[T, U, V]): V = macro ...
-defined term macro join: [T, U, V](x: T, y: U)...
-```
-
-This approach can express some macros that refine their return type, all fundep materialization macros,
-and even some macros that dynamically compute availability of implicits (such macros can be modified to take
-an additional implicit parameter whose failure to materialize can be used to control availability of the enclosing implicit) -
-that is, all macros whose whiteboxity depends only on types of their prefix and arguments.
-
-Now, after eligible whitebox macros are rewritten this way, we can replace the whitebox materializers
-that compute types, e.g. `Join.materialize`, with a dedicated language feature that natively expresses them.
-The listing below provides a sketch of an imaginary syntax that assumes inline types and type-generating meta expressions.
-
-```
-inline type Join[T, U] = meta {
- import scala.meta._
- val jointVals = union(T, U)
- t"{ ..$jointVals }"
-}
-
-inline def join[T, U](x: T, y: U): Join[T, U] = meta { ... }
-```
-
-From the discussion above, we can see that whiteboxity is an important feature of the current macro system
-and is used in multiple highly popular open-source libraries. As a result, giving up whiteboxity
-may lead to undesired practical consequences.
-
-More work is needed to reconcile the design of the new macro system
-and existing use cases, and in this section we provided several approaches to addressing this need. In the opinion of the author,
-the approach that involves dedicated support to type-level computations is the most promising, because it both simplifies
-the macro system and provides support for the most important use cases of whiteboxity.
-
-### Losing compiler internals
-
-One of the main goals of this proposal is to stop exposing overcomplicated and brittle compiler internal APIs
-in order to make macros more accessible and more robust.
-
-However, some of the compiler APIs may actually capture useful idioms that we may be able to expose in a principled fashion.
-`c.internal.enclosingOwner` immediately comes to mind here.
-
-More work in collaboration with macro authors is needed to make sure that we don't unnecessarily break existing macros
-in the name of elusive conceptual purity.
-
-### Macro annotations
-
-Much like the current macro system can get extended to support macro annotations,
-the new macro system can get extended to support new-style macro annotations that provide similar functionality.
-
-```
-import scala.annotation.StaticAnnotation
-
-class h2db(url: String) extends StaticAnnotation {
- inline def apply(defns: Any): Any = meta {
- ...
- }
-}
-
-object Test {
- def main(args: Array[String]): Unit = {
- @h2db("coffees") object Db
- val brazilian = Db.Coffees.insert("Brazilian", 99.0)
- Db.Coffees.update(brazilian.copy(price = 100.0))
- println(Db.Coffees.all)
- }
-}
-```
-
-In the current macro system, a macro annotation is a subclass of `StaticAnnotation` that define
-a macro def called `macroTransform`.
-
-Analogously, in the new design, a macro annotation is a subclass of `StaticAnnotation`
-that defines an inline def called `apply`. We decided to change the magic name, because the old one no longer applies.
-We also simplified the signature to take a block wrapping the definitions being expanded and returns a block wrapping expansion results,
-i.e. `Any => Any`, as opposed to having `Any* => Any` in the current system.
-
-Expansion of new-style macro annotations is very similar to expansion of vanilla macro annotations.
-The only difference is that we only provide syntactic APIs, informed about [the limitations][AnnotationsTypecheck]
-brought by exposing semantic APIs in macros that generate top-level definitions.
-Concretely, meta scopes in macro annotations expose a `Dialect` capability instead of a `Mirror`.
-As a result, we can afford to expand on enter without any limitations to the shape of expansion.
-
-### Why inline
-
-The main motivation behind inline is to provide a templating system that can express simple use cases
-of compile-time metaprogramming in an lightweight declarative style that minimizes explicit introspection.
-
-For example, in one of the code snippets that illustrates inline defs and inline parameters, we can use the newly
-introduced mechanism to express partial evaluation. Thanks to constant folding facilities built into the compiler,
-usages of the `pow` method provided below will expand into a sequence of multiplications - all that without
-a single line of macro code.
-
-```
-inline def pow(b: Double, inline n: Int): Double = {
- if (n == 0) 1
- else b * pow(b, n - 1)
-}
-```
-
-### Out of scope
-
-This proposal addresses a lot of pain points of the current macro system, but it doesn't talk about two very common
-problems: lack of hygiene and presence of the separate compilation restriction.
-
-These two problems have a lot in common: we have experimented with both of them, our initial results are promising but insufficient,
-both of them can be developed independently of inline/meta.
-
-Given that both hygiene and joint compilation still require significant research to materialize,
-we decided not to include them in this proposal. We think that even without these features, inline/meta represents a significant
-improvement over the state of the art, so we leave them for future work that may be submitted in follow-up SIPs when it's done.
-
-## Conclusion
-
-Pioneered by def macros and macro annotations,
-the area of language-integrated compile-time metaprogramming in Scala has shown significant practical value.
-
-During the last several years, we have been utilizing and maintaining the current macro system in industrial projects.
-Learning from this experience, we have created a new design based on `inline` and `meta` that provides
-comparable functionality and avoids the most common pitfalls of existing macros.
-
-The user interface of the new system is a conservative evolution of def macros.
-[Inline defs][InlineDefs] work similarly to macro defs, and
-[meta expressions][MetaExprs] play the compile-time execution role of macro impls.
-These new language features are designed to be used together,
-and in this capacity their look and feel can hardly be distinguished from that of def macros.
-
-The metaprogrammer interface of the new system is a drastic redesign. We have merged macro defs and macro impls,
-and, more importantly, we have switched the underlying metaprogramming API from scala.reflect to [scala.meta][ScalaMetaSection].
-This has allowed us to make significant improvements in robustness and tool support.
-
-The main open question of the new design is [whether whiteboxity will stay or will be removed][Whiteboxity] from the new macro system.
-We also need to figure out [which internal compiler APIs we may want to approximate][CompilerInternals] in the new macro system.
-Future work outside the scope of this proposal includes
-hygiene and lifting the separate compilation restriction.
-
-At the time of writing, `inline` and `meta` are partially implemented in [a prototype compiler plugin for Scala 2.11][PrototypeScalac]
-and [an accompanying experimental branch of IntelliJ][PrototypeIntellij].
-We are excited with our initial results and are planning to develop the new design further.
-
-## Credits
-
-This design was created by Eugene Burmako, Denys Shabalin and Martin Odersky
-and was further elaborated together with other members of the inline working group at EPFL:
-Sébastien Doeraene, Vojin Jovanovic and Dmitry Petrashko.
-
-Over time, the ideas behind the design were refined based on experiments carried out by:
-Uladzimir Abramchuk, Igor Bogomolov, Mathieu Demarne, Martin Duhem, Adrien Ghosn, Zhivka Gucevska,
-Mikhail Mutcianko, Dmitry Naydanov, Artem Nikiforov, Vladimir Nikolaev, Jatin Puri and Valentin Rutz.
-
-The prototype of scalac integration was developed by Eugene Burmako with open-source contributions from
-Tamer Mohammed Abdul-Radi, David Dudson, Takeshi D. Itoh, Oleksandr Olgashko and Hiroshi Yamaguchi.
-
-The prototype of IntelliJ integration was developed by Mikhail Mutcianko.
-
-## References
-
- 1. [Prototype of scalac integration][PrototypeScalac]
- 1. [Prototype of IntelliJ integration][PrototypeIntellij]
- 1. [(Appendix A) Def macros: feature interaction][AppendixInteraction]
- 1. [(Appendix B) Def macros: macro expansion][AppendixExpansion]
- 1. [(Appendix C) Scala.meta: high-level overview][AppendixMeta]
-
-[ScalaMetaSection]: #scalameta
-[ScalaMetaWebsite]: https://scalameta.org/
-[MacroUsecases]: https://scalamacros.org/paperstalks/2014-02-04-WhatAreMacrosGoodFor.pdf
-[PrototypeScalac]: https://github.com/scalameta/paradise
-[PrototypeIntellij]: https://www.youtube.com/watch?v=IPnd_SZJ1nM&feature=youtu.be&t=1360
-[Intuition]: #intuition
-[LanguageFeatures]: #language-features
-[InlineDefs]: #inline-definitions
-[InlineExpansion]: #inline-reduction
-[MetaExprs]: #meta-expressions
-[MetaExpansion]: #meta-expansion
-[MetaApis]: #meta-apis
-[Whiteboxity]: #losing-whiteboxity
-[CompilerInternals]: #losing-compiler-internals
-[Hygiene]: #hygiene
-[SeparateCompilation]: #separate-compilation-restriction
-[Linq]: https://dl.acm.org/citation.cfm?id=1142552
-[Materialization]: https://docs.scala-lang.org/overviews/macros/implicits.html
-[SbtMacroSupport]: https://github.com/sbt/sbt/issues/1729
-[AnonymousTypeProviders]: https://docs.scala-lang.org/overviews/macros/typeproviders.html#anonymous-type-providers
-[ExtractorMacros]: https://docs.scala-lang.org/overviews/macros/extractors.html
-[AnnotationsTypecheck]: https://github.com/scalamacros/paradise/issues/75
-[AppendixInteraction]: https://gist.github.com/xeno-by/e26a904051a171e4bc8b9096630220a7
-[AppendixExpansion]: https://gist.github.com/xeno-by/5dde62aedcc23afc85ecf4d795ac67c2
-[AppendixMeta]: https://gist.github.com/xeno-by/9741ce7532cb30368b3753521bbfce4e
diff --git a/_sips/sips/2017-01-11-refer-other-arguments-in-args.md b/_sips/sips/2017-01-11-refer-other-arguments-in-args.md
deleted file mode 100644
index 6d5097038a..0000000000
--- a/_sips/sips/2017-01-11-refer-other-arguments-in-args.md
+++ /dev/null
@@ -1,107 +0,0 @@
----
-layout: sip
-title: SIP-32 - Allow referring to other arguments in default parameters
-vote-status: pending
-permalink: /sips/:title.html
-redirect_from: /sips/pending/refer-other-arguments-in-args.html
----
-
-**By: Pathikrit Bhowmick**
-
-## History
-
-| Date | Version |
-|---------------|------------------|
-| Jan 11th 2017 | Initial Draft |
-| Jan 12th 2017 | Initial Feedback |
-| Jan 16th 2017 | Minor Changes |
-
-## Introduction
-Currently there is no way to refer to other arguments in the default parameters list:
-
-Does not compile:
-```scala
-def substring(s: String, start: Int = 0, end: Int = s.length): String
-```
-
-The workaround to achieve this is by using a curried-function:
-```scala
-def substring(s: String, start: Int = 0)(end: Int = s.length): String
-```
-
-However, the above workaround is not always suitable in all situations since you may not want a curried function.
-
-The other more verbose alternative is by overloading:
-```scala
-def substring(s: String, start: Int): String
- = substring(s, start = 0, end = s.length)
-def substring(s: String, start: Int = 0, end: Int): String
-```
-
-The above is quite verbose as it required 1 extra function definition per argument that refers other args.
-
-### Proposal
-Allow to refer to ***any*** parameters in the same (or left) curried parameter list:
-```scala
-def substring(s: String, start: Int = 0, end: Int = s.length) // Legal
-def substring(start: Int = 0, end: Int = s.length, s: String) // Legal !!!
-def substring(s: String, start: Int = 0)(end: Int = s.length) // Legal (works currently)
-def substring(start: Int = 0, end: Int = s.length)(s: String) // Illegal
-```
-
-The same applies for class arguments:
-```scala
-class Substring(s: String, start: Int = 0, end: Int = s.length) // Legal
-class Substring(start: Int = 0, end: Int = s.length, s: String) // Legal
-class Substring(s: String, start: Int = 0)(end: Int = s.length) // Legal
-class Substring(start: Int = 0, end: Int = s.length)(s: String) // Illegal
-```
-
-We should also be able to refer to ***multiple*** parameters:
-```scala
-def binarySearch(start: Int, end: Int, middle: Int = (start + end)/2) // Legal
-```
-
-# Motivating examples:
-
-TBD
-
-## Interactions with other syntax
-
-#### Partially Applied Functions:
-Works as expected:
-```scala
-def substring(s: String, start: Int = 0, end: Int = s.length)
-
-substring(_, start = 0, end = 5) // Legal
-substring(_, end = 5) // Legal (start = 0)
-substring(_, start = 5) // Legal (same as s => substring(s, start = 5, end = s.length)
-```
-
-#### Multiple Implicit Parameters
-[Multiple implicit parameters](https://github.com/scala/docs.scala-lang/pull/520) should also be allowed to refer to one another (left to right):
-```scala
-def codec[A](data: A)(implicit encoder: Encoder[A])(implicit decoder: Decoder[A] = encoder.reverse) // Legal
-```
-
-#### Referring to type members:
-The default parameters should be able to refer to type members of other arguments e.g.:
-```scala
-trait Codec {
- type Input
- type Output
-}
-
-def codec(codec: Codec, in: codec.Input, out: codec.Output) // Legal !!!
-```
-
-### Other languages
-The following languages allow referring to previously declared arguments in the function signature:
-* [CoffeeScript](https://coffeescript.org/)
-* [Kotlin](https://kotlinlang.org)
-* [TypeScript](https://www.typescriptlang.org/)
-
-AFAIK, there are no major languages where referring to parameters declared to the ***right*** is allowed.
-
-### Discussions
-[Scala Lang Forum](https://contributors.scala-lang.org/t/refer-to-previous-argument-in-default-argument-list/215/6)
diff --git a/_sips/sips/2017-01-13-binary-compatibility.md b/_sips/sips/2017-01-13-binary-compatibility.md
deleted file mode 100644
index 96be472776..0000000000
--- a/_sips/sips/2017-01-13-binary-compatibility.md
+++ /dev/null
@@ -1,299 +0,0 @@
----
-layout: sip
-title: SIP-34 - Improving binary compatibility with @stableABI
-vote-status: dormant
-vote-text: When the author of this proposal figures out which features should be binary compatible and has more information on the future implementation, the SIP Committee will start the review period.
-permalink: /sips/:title.html
-redirect_from: /sips/pending/binary-compatibility.html
----
-
-__Dmitry Petrashko__
-
-__first submitted 13 January 2017__
-
-## Introduction
-
-Scala is a language which evolves fast and thus made a decision to only promise binary compatibility across minor releases\[[3]\].
-At the same time, there is a demand to develop APIs that live longer than a major release cycle of Scala.
-This SIP introduces an annotation `@stableABI` that checks that `what you write is what you get`.
-
-`@stableABI` is a linter, that does not change binary output, but will fail compilation if Public API of a class uses features
-of Scala that are desugared by compiler and may be binary incompatible across major releases.
-
-As long as declarations in source have not changed, `@stableABI` annotated classes will be compatible across major versions of Scala.
-It complements MiMa\[[2]\] in indicating if a class will remain binary compatible across major Scala releases.
-
-## Term definitions
-
-* ##### Binary descriptors
-
-As defined by the JVM spec\[[4]\]:
-
- > A descriptor is a string representing the type of a field or method. Descriptors are represented in the class file format using modified UTF-8 strings (§4.4.7)
- > and thus may be drawn, where not further constrained, from the entire Unicode codespace.
- >
- > A method descriptor contains zero or more parameter descriptors, representing the types of parameters that the method takes, and a return descriptor, representing the type of the value (if any) that the method returns.
-
- Binary descriptors are used in the bytecode to indicate what fields and methods are accessed or invoked.
- If a method or field has its descriptor changed, previously compiled classes that used different descriptor will fail in
- runtime as they no longer link to the changed field.
-
- In this document we use the term `binary descriptor` to refer to both method and field descriptors used by the JVM.
-
-* ##### Public API
-
- Methods and fields marked with `ACC_PUBLIC`\[[5]\] may be accessed from any class and package.
- This loosely corresponds to absence of AccessModifier\[[6]\] in Scala source.
- Changing a binary descriptor of a method or a field marked with `ACC_PUBLIC` is a binary incompatible change
- which may affect all classes in all packages leading to a runtime linkage failure.
-
- Methods and fields marked with `ACC_PROTECTED`\[[5]\] may be accessed within subclasses.
- This loosely corresponds to presence of `protected` AccessModifier\[[6]\] in Scala source.
- Changing a binary descriptor of a method or a field marked with `ACC_PROTECTED` is a binary incompatible change
- which may affect all subclasses of this class leading to a runtime linkage failure.
-
- In this document we use the term `Public API` to refer both to methods and fields defined as `ACC_PUBLIC` and `ACC_PROTECTED`.
- Changes do binary descriptors of Public API may lead to runtime linkage failures.
-
-* ##### Binary compatibility
-
- Two versions of the same class are called binary compatible if there are no changes to the Public API of this class,
- meaning that those two classes can be substituted in runtime without linkage errors.
-
-## Use cases
-
-1. Publishing a library that would work across major Scala versions, such as 2.12 & 2.13 and Dotty.
-2. Defining a class which is supposed to be used from other JVM languages such as Java\Kotlin.
-`@stableABI` will ensure both binary compatibility and that there are no unexpected methods
- that would show up in members of a class or an interface.
-3. Library authors can take advantage of language features introduced in new major versions of Scala
- while still serving users on older language versions by defining their Public API as `@stableABI`.
-
-The important use-case envisioned here by the authors is migration to Dotty.
-We envision that there might be code-bases that for some reason don't compile either with Dotty or with Scalac.
-This can be either because they rely on union types, only present in Dotty,
-or because they need early initializers, which are only supported by Scalac.
-
-At the same time, by marking either those classes themselves or their parents as `@stableABI`,
-the compiled artifacts could be used in both Dotty-compiled and Scalac-compiled projects.
-
-
-## Current Status
-In case there's a need to develop an API that will be used by clients compiled using different major versions of Scala,
-the current approach is to either develop them in Java or to use best guess to restrict what Scala features should be used.
-
-There's also a different approach which is used by sbt: instead of publishing a binary `compiler-interface`, sources are published instead that would be locally compiled.
-
-Examples:
-
- 1. Zinc\[[8]\] is writing their interfaces in Java because the interface has to be Scala version agnostic, as it is shipped in every sbt release, independently of Scala version that was used to compile zinc or will be used in to compile the project.
-sbt additionally compiles on demand the compiler bridge, which implements this Java interface.
-
- 2. Dotty\[[7]\] currently uses java defined interfaces as public API for IntelliJ in order to ensure binary compatibility.
-These interfaces can be replaced by `@stableABI` annotated traits to reach the same goal.
-
-## Design Guidelines
-`@stableABI` is a feature which is supposed to be used by a small subset of the ecosystem to be binary compatible across major versions of Scala.
-Thus this is designed as an advanced feature that is used rarely and thus is intentionally verbose.
-It's designed to provide strong guarantees, in some cases sacrificing ease of use and to be used in combination with MiMa\[[2]\]
-
-The limitations enforced by `@stableABI` are designed to be an overapproximation:
-instead of permitting a list of features known to be compatible, `@stableABI` enforces a stronger
-check which is sufficient to promise binary compatibility.
-
-This SIP intentionally follows a very conservative approach.
-This is because we will be able to allow more features later, but we won't have an opportunity to remove them.
-
-## Overview ##
-In order for a class, trait or an object to succeed compilation with the `@stableABI` annotation it has to be:
-
- - defined on the top level;
- - if a class or an object has a companion annotated with `@stableABI`, than annotation applies to both of them;
- - use a subset of Scala that during compilation does not require changes to public API of the class, including
- - synthesizing new members, either concrete or abstract;
- - changing binary descriptors of existing members, either concrete or abstract;
-
-`@stableABI` does not change the compilation scheme of a class:
- compiling a class previously annotated with the `@stableABI`, will produce the same bytecode with or without `@stableABI` annotation.
-
-Below are several examples of classes and traits that succeed compilation with `@stableABI`
-
-{% highlight scala %}
-@stableABI
-trait AbstractFile {
- def name(): String
-
- def path(): String
-
- def jfile(): Optional[File]
-}
-
-@stableABI
-trait SourceFile extends AbstractFile {
- def content(): Array[Char]
-}
-
-@stableABI
-trait Diagnostic {
- def message(): String
-
- def level(): Int
-
- def position(): Optional[SourcePosition]
-}
-
-@stableABI
-object Diagnostic {
- @static final val ERROR: Int = 2
- @static final val WARNING: Int = 1
- @static final val INFO: Int = 0
-}
-
-@stableABI
-class FeaturesInBodies {
- def apiMethod: Int = {
- // as body of the method isn't part of the public interface, one can use all features of Scala here.
- lazy val result = 0 // while lazy vals are prohibited in the class, they are allowed in the bodies of methods
- result
- }
-}
-{% endhighlight %}
-
-## Features that will fail compilation with `@stableABI`
-The features listed below have complex encodings that may change in future versions. We prefer not to compromise on them.
-Most of those features can be simulated in a binary compatible way by writing a verbose re-implementation
-which won't rely on desugaring performed inside compiler.
-Note that while those features are prohibited in the public API, they can be safely used inside bodies of the methods.
-
- - public fields. Can be simulated by explicitly defining public getters and setters that access a private field;
- - lazy vals. Can be simulated by explicitly writing an implementation in source;
- - case classes. Can be simulated by explicitly defining getters and other members synthesized for a case class(`copy`, `productArity`, `apply`, `unapply`, etc).
-
-The features listed below cannot be easily re-implemented in a class or trait annotated with `@stableABI`.
-
- - default arguments;
- - default methods. See Addendum;
- - constant types(both explicit and inferred);
- - inline.
-
-## Binary compatibility and transitivity ##
-Consider a class, that is binary compatible but takes a non-binary compatible argument:
-
-{% highlight scala %}
-@stableABI
-class Example {
- def foo[T](a: MyOption[T]): T = a.get
-}
-
-trait MyOption[T]{
- lazy val get: T = ???
-}
-{% endhighlight %}
-
-
-Consider a situation when we re-compile `MyOption` using a different major compiler version than the one used to compile `Example`.
-Let's assume the new major version of compile has changing binary descriptor of method `get`.
-
-While the code in runtime would still successfully invoke the method `Example.foo`, this method will fail in execution,
-as it will itself call a `MyOption.get` using an outdated descriptor.
-
-While in perfect world it would be nice to require all `@stableABI` classes and traits to only take `@stableABI` arguments
-and only return `@stableABI` values, we believe that all-or-nothing system will be a lot harder to adopt and migrate to.
-
-Because of this we propose to emmit warnings in those cases:
-
- - non-`@stableABI` value is returned from a method or field defined inside a `@stableABI` class or trait;
- - an invocation to a method not-defined inside a `@stableABI` class is used in
- implementation of a method or a field initializer inside a `@stableABI` class or trait.
-
-Those warnings can be suppressed using an `@unchecked` annotations or made fatal using `+Xfatal-warnings`.
-
-## The case of the standard library ##
-The Standard library defines types commonly used as arguments or return types such as `Option` and `List`,
-as well as methods and implicit conversions imported from `scala` and `Predef`.
-
-As such Standard library is expected to be the biggest source of warnings defined in previous section.
-
-We propose to consider either making some classes in standard library use `@stableABI` or define new `@stableABI`
-super-interfaces for them that should be used in `@stableABI` classes.
-This would also allow to consume Scala classes from other JVM languages such as Kotlin and Java.
-## `@stableABI` and Scala.js
-
-Allowing to write API-defining classes in Scala instead of Java will allow them to compile with Scala.js,
-which would have benefit of sharing the same source for two ecosystems.
-
-Scala.js currently is binary compatible as long as original bytecode compiled by Scala JVM is binary compatible.
-Providing stronger binary compatibility guarantees for JVM will automatically provide stronger guarantees for Scala.js.
-
-
-## Comparison with MiMa ##
-The Migration Manager for Scala (MiMa in short) is a tool for diagnosing binary incompatibilities for Scala libraries.
-MiMa allows to compare binary APIs of two already compiled classfiles and reports errors if APIs do not match perfectly.
-
-MiMa and `@stableABI` complement each other, as `@stableABI` helps to develop APIs that stay compatible
-across major versions, while MiMa checks that previously published artifacts indeed have the same API.
-
-`@stableABI` does not compare the currently compiled class or trait against previous version,
-so introduction of new members won't be prohibited. This is a use-case for MiMa.
-
-MiMa does not indicate how hard, if possible, would it be to maintain compatibility of a class across future versions of Scala.
-Multiple features of Scala, most notably lazy vals and traits, have been compiled differently by different Scala versions
-making porting existing compiled bytecode across versions very hard.
-MiMa will complain retroactively that the new version is incompatible with the old one.
-`@stableABI` will instead indicate at compile time that the old version used features whose encoding is prone to change.
-This provides early guidance and warning when designing long-living APIs before they are publicly released.
-
-## Compilation scheme ##
-No modification of typer or any existing phase is planned. The current proposed scheme introduces a late phase that runs before the very bytecode emission that checks that:
-
- - classes, traits and objects annotated as `@stableABI` are on the top level;
- - compiler did not introduce new Public API methods or fields inside `@stableABI` classes, traits and objects;
- - compiler did not change descriptors of existing Public API methods or fields inside `@stableABI` classes, traits and objects.
-
-This phase additionally warns if Public API method or field takes an argument or returns a value that isn't marked as `@stableABI`.
-This warning can be suppressed by annotating with `@unchecked`.
-
-The current prototype is implemented for Dotty and supports everything described in this SIP, except warnings.
-The implementation is simple with less than 50 lines of non-boilerplate code.
-The current implementation has a scope for improvement of error messages that will report domain specific details for disallowed features,
-but it already prohibits them.
-
-## Addendum: Default methods ##
-By `default methods` we mean non-abstract methods defined and implemented by a trait.
-
-The way how those methods are implemented by compiler has changed substantially over years.
-At the same time, `invokeinterface` has always been a reliable way to invoke such a method,
-independently from how it was implemented under the hood.
-
-One might reason that, as there has been a reliable way to call methods on the binary level,
-it should be allowed to use them in binary compatible APIs.
-
-At the same time, the mixin composition protocol that is followed when a class inherits those traits has also
-changed substantially.
-The classes which have been correctly inheriting those traits compiled by previous versions of Scala
-may need recompilation if trait has been recompiled with a new major version of Scala.
-
-Thus, the authors of this SIP has decided not to allow default methods in the
-`@stableABI` traits.
-
-## See Also ##
-
- 1. [dotty#1900][1]
- 2. [MiMa][2]
- 3. [releases-compatibility][3]
- 4. [Descriptor definition in JVM Specification][4]
- 5. [JVM access flags][5]
- 6. [Scala AccessModifiers][6]
- 7. [Dotty interfaces][7]
- 8. [Zinc interfaces][8]
-
-
-[1]: https://github.com/lampepfl/dotty/pull/1900 "an implementation for Dotty"
-[2]: https://github.com/typesafehub/migration-manager "MiMa"
-[3]: https://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html "Binary compatibility of Scala releases"
-[4]: https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.3 "Descriptor definition in JVM Specification"
-[5]: https://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.6-200-A.1 "JVM access flags"
-[6]: https://www.scala-lang.org/files/archive/spec/2.11/05-classes-and-objects.html#modifiers "Scala AccessModifiers"
-[7]: https://github.com/lampepfl/dotty/tree/master/interfaces/src/dotty/tools/dotc/interfaces "Dotty interfaces"
-[8]: https://github.com/sbt/zinc/tree/v1.0.0/internal/compiler-interface/src/main/java/xsbti "zinc interfaces"
-
diff --git a/_sips/sips/2017-02-22-comonadic-comprehensions.md b/_sips/sips/2017-02-22-comonadic-comprehensions.md
deleted file mode 100644
index 92db697c41..0000000000
--- a/_sips/sips/2017-02-22-comonadic-comprehensions.md
+++ /dev/null
@@ -1,223 +0,0 @@
----
-layout: sip
-title: SIP-NN - comonadic-comprehensions
-vote-status: rejected
-permalink: /sips/:title.html
-redirect_from: /sips/pending/comonadic-comprehensions.html
----
-
-**By: Shimi Bandiel**
-
-## History
-
-| Date | Version |
-|---------------|---------------|
-| Feb 22nd 2017 | Initial Draft |
-
-## Motivation
-
-Scala provides a concise syntax for working with Monads(map & flatMap):
-the for comprehension.
-
-Following is a proposal for a concise syntax for working with Comonads(map, extract & coflatMap):
-the cofor comprehension.
-
-The proposal has an existing implementation in PR 5725
-
-## Motivating Examples
-
-### Examples
-
-Consider the following class:
-
-{% highlight scala %}
-
-case class StreamZipper[A](left: Stream[A], focus: A, right: Stream[A]) {
- def map[B](f: A => B): StreamZipper[B] =
- StreamZipper(left.map(f), f(focus), right.map(f))
- def extract: A =
- focus
- def coflatMap(f: StreamZipper[A] => B): StreamZipper[B] =
- ???
-}
-
-{% endhighlight %}
-
-StreamZipper[A] represents a non-empty Stream of As with a cursor (focus).
-
-
- text & hexadecimal reference & decimal reference
-
-```
-
-will be translated to
-
-``` scala
-xml.literal(
- xml.elements.`tag-name`(
- xml.attributes.`attribute-1`(xml.values.value),
- xml.texts.`$u000A text `,
- xml.entities.amp,
- xml.texts.` hexadecimal reference `,
- xml.entities.AMP,
- xml.texts.` decimal reference$u000A `,
- xml.elements.`child-1`(),
- xml.texts.`$u000A `,
- xml.comment(" my comment "),
- xml.texts.`$u000A `,
- xml.interpolation(math.random),
- xml.texts.`$u000A `,
- xml.cdata(" raw "), // or (xml.texts.` raw `), if `-Xxml:coalescing` flag is set
- xml.texts.`$u000A `
- )
-)
-```
-
-Note that hexadecimal references and decimal references will be unescaped and translated to `xml.texts` automatically, while entity references are translated to fields in `xml.entities` .
-
-### Prefixes without `xmlns` bindings.
-
-``` scala
-
- content
-
-
-```
-
-will be translated to
-
-``` scala
-xml.literal(
- `prefix-1`.elements.`tag-name-1`(
- `prefix-1`.attributes.`attribute-1`(`prefix-1`.values.`value-1`),
- `prefix-2`.attributes.`attribute-2`(`prefix-2`.values.`value-2`),
- `prefix-1`.texts.`$u000A `,
- xml.elements.`tag-name-2`(
- xml.texts.content
- ),
- `prefix-1`.texts.`$u000A `,
- `prefix-1`.comment(" my comment "),
- `prefix-1`.texts.`$u000A`
- )
-)
-```
-
-Note that unprefixed attribute will be treated as if it has the same prefix as its enclosing element.
-
-### `xmlns` bindings.
-
-``` scala
-
- content
-
-
-```
-
-will be translated to
-
-``` scala
-xml.literal(
- xml.prefixes.`prefix-1`(xml.uris.`http://example.com/1`).elements.`tag-name-1`(
- xml.prefixes.`prefix-1`(xml.uris.`http://example.com/1`).attributes.`attribute-1`(xml.prefixes.`prefix-1`(xml.uris.`http://example.com/1`).values.`value-1`),
- xml.prefixes.`prefix-2`(xml.uris.`http://example.com/2`).attributes.`attribute-2`(xml.prefixes.`prefix-2`(xml.uris.`http://example.com/2`).values.`value-2`),
- xml.prefixes.`prefix-1`(xml.uris.`http://example.com/1`).texts.`$u000A `,
- xml.noPrefix(xml.uris.`http://example.com/0`).elements.`tag-name-2`(
- xml.noPrefix(xml.uris.`http://example.com/0`).texts.content
- ),
- xml.prefixes.`prefix-1`(xml.uris.`http://example.com/1`).texts.`$u000A `,
- xml.prefixes.`prefix-1`(xml.uris.`http://example.com/1`).comment(" my comment "),
- xml.prefixes.`prefix-1`(xml.uris.`http://example.com/1`).texts.`$u000A`
- )
-)
-```
-
-## Implementation
-
-The implementation of this proposal can be two parts:
-
-1. Compile-time XML translator
-2. XML library vendors
-
-### Compile-time XML translator
-
-Compile-time XML translator will translate XML literal to Scala AST before type checking. It can be implemented either in the Scala compiler or in a white box macro. [nameBasedXml.scala](https://github.com/GlasslabGames/nameBasedXml.scala) is an implementation of the proposal in a white box macro.
-
-### XML library vendors
-
-An XML library vendor should provide a package or object named `xml` , which contains the following methods or values:
-
-* `elements`
-* `attributes`
-* `values`
-* `entities`
-* `processInstructions`
-* `texts`
-* `comment`
-* `cdata`
-* `interpolation`
-* `noPrefix`
-* `prefixes`
-* `uris`
-* `literal`
-
-All above methods except `literal` should return a builder, and `literal` will turn one or more builders into an XML object / or an XML node list.
-
-An XML library user can switch different implementations by importing different `xml` packages or objects. `scala.xml` is used by default when no explicit import is present.
-
-In a schema-aware XML library like Binding.scala, its `elements` , `attributes` , `processInstructions` and `entities` methods should return factory objects that contain all the definitions of available tag names and attribute names. An XML library user can provide additional tag names and attribute names in user-defined implicit classes for `tags` and `attributes` .
-
-In a schema-less XML library like `scala-xml` , its `elements` , `attributes` , `processInstructions` and `entities` should return builders that extend [scala.Dynamic](https://www.scala-lang.org/api/current/scala/Dynamic.html) in order to handle tag names and attribute names in `selectDynamic` or `applyDynamic` .
-
-Those XML libraries can be extended with the help of standard XML namespace bindings. A plug-in author can create `implicit class` for `xml.uris` to introduce foreign elements embedded in existing XML literals.
-
-[html.scala](https://github.com/GlasslabGames/html.scala) is an XML library vendor for creating reactive HTML templates.
-
-## Drawbacks
-
-### Name clash
-
-`_ of _O_ then we have
> observed divergence and we're done.
->
+>
> + If _d_ has no implicit arguments then the result is the value yielded by _d_.
->
+>
> + Otherwise for each implicit argument _a_ of _d_, resolve _a_ against _O+_, and the result is
> the value yielded by _d_ applied to its resolved arguments.
@@ -643,8 +646,8 @@ larger than _U_ despite using only elements that are present in _U_.
This gives us the following,
-> To resolve an implicit of type _T_ given stack of open implicits _O_,
->
+> To resolve an implicit of type _T_ given stack of open implicits _O_,
+>
> + Identify the definition _d_ which satisfies _T_.
>
> + if there is an element _e_ of _O_ of the form __ such that at least one element between _e_
@@ -655,7 +658,7 @@ This gives us the following,
> observed divergence and we're done.
>
> + If _d_ has no implicit arguments then the result is the value yielded by _d_.
->
+>
> + Otherwise for each implicit argument _a_ of _d_, resolve _a_ against _O+_, and the result is
> the value yielded by _d_ applied to its resolved arguments.
@@ -848,7 +851,7 @@ object Test {
because the path `foo` in `foo.Out` is not stable. Full parity with shapeless's `Lazy` would require
lazy (rather than byname) implicit parameters (see [this Dotty
-ticket](https://github.com/lampepfl/dotty/issues/3005) for further discussion) and is orthogonal to
+ticket](https://github.com/scala/scala3/issues/3005) for further discussion) and is orthogonal to
this SIP in that they would drop out of support for lazy parameters more generally, as described in
[this Scala ticket](https://github.com/scala/bug/issues/240).
diff --git a/_sips/sips/clause-interleaving.md b/_sips/sips/clause-interleaving.md
new file mode 100644
index 0000000000..e9809815e2
--- /dev/null
+++ b/_sips/sips/clause-interleaving.md
@@ -0,0 +1,173 @@
+---
+layout: sip
+title: SIP-47 - Clause Interleaving
+stage: completed
+status: shipped
+permalink: /sips/:title.html
+---
+
+**By: Quentin Bernet and Guillaume Martres and Sébastien Doeraene**
+
+## History
+
+| Date | Version |
+|---------------|-----------------------|
+| May 5th 2022 | Initial Draft |
+| Aug 17th 2022 | Formatting |
+| Sep 22th 2022 | Type Currying removed |
+
+## Summary
+
+We propose to generalize method signatures to allow any number of type parameter lists, interleaved with term parameter lists and using parameter lists. As a simple example, it would allow to define
+~~~ scala
+def pair[A](a: A)[B](b: B): (A, B) = (a, b)
+~~~
+Here is also a more complicated and contrived example that highlights all the possible interactions:
+~~~ scala
+def foo[A](using a: A)(b: List[A])[C <: a.type, D](cd: (C, D))[E]: Foo[A, B, C, D, E]
+~~~
+
+
+## Motivation
+
+Consider an API for a heterogenous key-value store, where keys know what type of value they must be associated to:
+~~~ scala
+trait Key:
+ type Value
+
+class Store:
+ def get(key: Key): key.Value = …
+ def put(key: Key)(value: => key.Value): Unit = …
+~~~
+We want to provide a method `getOrElse`, taking a default value to be used if the key is not present. Such a method could look like
+~~~ scala
+def getOrElse(key: Key)(default: => key.Value): key.Value = …
+~~~
+However, at call site, it would prevent from using as default value a value that is not a valid `key.Value`. This is a limitation compared to other `getOrElse`-style methods such as that of `Option`, which allow passing any supertype of the element type.
+
+In current Scala, there is no way to define `Store.getOrElse` in a way that supports this use case. We may try to define it as
+~~~ scala
+def getOrElse[V >: key.Value](key: Key)(default: => V): V = …
+~~~
+but that is not valid because the declaration of `V` needs to refer to the path-dependent type `key.Value`, which is defined in a later parameter list.
+
+We might also try to move the type parameter list after `key` to avoid that problem, as
+~~~ scala
+def getOrElse(key: Key)[V >: key.Value](default: => V): V = …
+~~~
+but that is also invalid because type parameter lists must always come first.
+
+A workaround is to return an intermediate object with an `apply` method, as follows:
+~~~ scala
+class Store:
+ final class StoreGetOrElse[K <: Key](val key: K):
+ def apply[V >: key.Value](default: => V): V = …
+ def getOrElse(key: Key): StoreGetOrElse[key.type] = StoreGetOrElse(key)
+~~~
+This definition provides the expected source API at call site, but it has two issues:
+* It is more complex than expected, forcing a user looking at the API to navigate to the definition of `StoreGetOrElse` to make sense of it.
+* It is inefficient, as an intermediate instance of `StoreGetOrElse` must be created for each call to `getOrElse`.
+* Overloading resolution looks at clauses after the first one, but only in methods, the above is ambiguous with any `def getOrElse(k:Key): ...`, whereas the proposed signature is not ambiguous with for example `def getOrElse(k:Key)[A,B](x: A, y: B)`
+
+Another workaround is to return a polymorphic function, for example:
+~~~scala
+def getOrElse(k:Key): [V >: k.Value] => (default: V) => V =
+ [V] => (default: V) => ???
+~~~
+While again, this provides the expected API at call site, it also has issues:
+* The behavior is not the same, as `default` has to be a by-value parameter
+* The definition is hard to visually parse, as users are more used to methods (and it is our opinion this should remain so)
+* The definition is cumbersome to write, especially if there are a lot of term parameters
+* It is inefficient, as many closures must be created for each call to `getOrElse` (one per term clause to the right of the first non-initial type clause).
+* Same problem as above with overloading
+
+## Proposed solution
+### High-level overview
+
+To solve the above problems, we propose to generalize method signatures so that they can have multiple type parameter lists, interleaved with term parameter lists and using parameter lists.
+
+For the heterogeneous key-value store example, this allows to define `getOrElse` as follows:
+~~~ scala
+def getOrElse(key: Key)[V >: key.Value](default: => V): V = …
+~~~
+It provides the best of all worlds:
+* A convenient API at call site
+* A single point of documentation
+* Efficiency, since the method erases to a single JVM method with signature `getOrElse(Object,Object)Object`
+
+### Specification
+We amend the syntax of def parameter clauses as follows:
+~~~
+DefDcl ::= DefSig ‘:’ Type
+DefDef ::= DefSig [‘:’ Type] ‘=’ Expr
+DefSig ::= id [DefParamClauses] [DefImplicitClause]
+DefParamClauses ::= DefParamClause { DefParamClause } -- and two DefTypeParamClause cannot be adjacent
+DefParamClause ::= DefTypeParamClause
+ | DefTermParamClause
+ | UsingParamClause
+DefTypeParamClause ::= [nl] ‘[’ DefTypeParam {‘,’ DefTypeParam} ‘]’
+DefTypeParam ::= {Annotation} id [HkTypeParamClause] TypeParamBounds
+DefTermParamClause ::= [nl] ‘(’ [DefTermParams] ‘)’
+UsingParamClause ::= [nl] ‘(’ ‘using’ (DefTermParams | FunArgTypes) ‘)’
+DefImplicitClause ::= [nl] ‘(’ ‘implicit’ DefTermParams ‘)’
+DefTermParams ::= DefTermParam {‘,’ DefTermParam}
+DefTermParam ::= {Annotation} [‘inline’] Param
+Param ::= id ‘:’ ParamType [‘=’ Expr]
+~~~
+
+The main rules of interest are `DefParamClauses` and `DefParamClauseChunk`, which now allow any number of type parameter clauses, term parameter clauses and using parameter clauses, in any order as long as there are no two adjacent type clauses.
+
+Note that these are also used for the right-hand side of extension methods, thus clause interleaving also applies to them.
+
+It is worth pointing out that there can still only be at most one implicit parameter clause, which, if present, must be at the end.
+
+The type system and semantics naturally generalize to these new method signatures.
+
+### Restrictions
+
+#### Type Currying
+Currying type clauses enables partial type inference, as the left clause can be specified while the right one is not.
+As this is a very useful feature, we expect people would use it liberally, and recommending the curried form.
+We are uncertain about the readability of the resulting methods, we have therefore decided to not include type currying as part of this proposal.
+
+Note however that, if absolutely necessary, it is still possible to curry type parameters as such: `def foo[A](using DummyImplicit)[B]`, since the implicit search for `DummyImplicit` will always succeed.
+This is sufficiently unwieldy that it is unlikely the above becomes the norm.
+
+#### Class Signatures
+Class signatures are unchanged. Classes can still only have at most one type parameter list, which must come first. For example, the following definition is still invalid:
+~~~ scala
+class Pair[+A](val a: A)[+B](val b: B)
+~~~
+Class signatures already have limitations compared to def signatures. For example, they must have at least one term parameter list. There is therefore precedent for limiting their expressiveness compared to def parameter lists.
+
+The rationale for this restriction is that classes also define associated types. It is unclear what the type of an instance of `Pair` with `A` and `B` should be. It could be defined as `Foo[A][B]`. That still leaves holes in terms of path-dependent types, as `B`'s definition could not depend on the path `a`. Allowing interleaved type parameters for class definitions is therefore restricted for now. It could be allowed with a follow-up proposal.
+
+Note: As `apply` is a normal method, it is totally possible to define a method `def apply[A](a: A)[B](b: B)` on `Pair`'s companion object, allowing to create instances with `Pair[Int](4)[Char]('c')`.
+
+#### LHS of extension methods
+The left hand side of extension methods remains unchanged, since they only have one explicit term clause, and since the type parameters are very rarely passed explicitly, it is not as necessary to have multiple type clauses there.
+
+Currently, Scala 2 can only call/override methods with at most one leading type parameter clause, which already forbids calling extension methods like `extension (x: Int) def bar[A](y: A)`, which desugars to `def bar(x: Int)[A](y: A)`. This proposal does not change this, so methods like `def foo[A](x: A)[B]` will not be callable from Scala 2.
+
+### Compatibility
+The proposal is expected to be backward source compatible. New signatures currently do not parse, and typing rules are unchanged for existing signatures.
+
+Backward binary compatibility is straightforward.
+
+Backward TASTy compatibility should be straightforward. The TASTy format is such that we can extend it to support interleaved type parameter lists without added complexity. If necessary, a version check can decide whether to read signatures in the new or old format. For typechecking, like for source compatibility, the typing rules are unchanged for signatures that were valid before.
+
+Of course, libraries that choose to evolve their public API to take advantage of the new signatures may expose incompatibilities.
+
+## Alternatives
+The proposal is a natural generalization of method signatures.
+We could have extended the proposal to type currying (allowing partial type inference), but have not due to the concerns mentionned in [Restrictions](#restrictions).
+This might be the subject of a follow up proposal, if the concerns can be addressed.
+
+As discussed above, we may want to consider generalizing class parameter lists as well. However, we feel it is better to leave that extension to a follow-up proposal, if required.
+
+## Related work
+* Pre-SIP: [https://contributors.scala-lang.org/t/clause-interweaving-allowing-def-f-t-x-t-u-y-u/5525](https://contributors.scala-lang.org/t/clause-interweaving-allowing-def-f-t-x-t-u-y-u/5525)
+* An implementation of the proposal is available as a pull request at [https://github.com/scala/scala3/pull/14019](https://github.com/scala/scala3/pull/14019)
+
+## FAQ
+Currently empty.
diff --git a/_sips/sips/comonadic-comprehensions.md b/_sips/sips/comonadic-comprehensions.md
new file mode 100644
index 0000000000..d668fc4d78
--- /dev/null
+++ b/_sips/sips/comonadic-comprehensions.md
@@ -0,0 +1,6 @@
+---
+title: SIP-NN - comonadic-comprehensions
+status: rejected
+pull-request-number: 32
+
+---
diff --git a/_sips/sips/concurrency-with-higher-order-coroutines.md b/_sips/sips/concurrency-with-higher-order-coroutines.md
new file mode 100644
index 0000000000..837df46236
--- /dev/null
+++ b/_sips/sips/concurrency-with-higher-order-coroutines.md
@@ -0,0 +1,7 @@
+---
+title: SIP-55 - Concurrency with Higher-Order Coroutines
+status: under-review
+pull-request-number: 63
+stage: design
+
+---
diff --git a/_sips/sips/2018-08-20-converters-among-optional-functions-partialfunctions-and-extractor-objects.md b/_sips/sips/converters-among-optional-functions-partialfunctions-and-extractor-objects.md
similarity index 96%
rename from _sips/sips/2018-08-20-converters-among-optional-functions-partialfunctions-and-extractor-objects.md
rename to _sips/sips/converters-among-optional-functions-partialfunctions-and-extractor-objects.md
index 7bd7571ea8..cad08453c3 100644
--- a/_sips/sips/2018-08-20-converters-among-optional-functions-partialfunctions-and-extractor-objects.md
+++ b/_sips/sips/converters-among-optional-functions-partialfunctions-and-extractor-objects.md
@@ -1,11 +1,14 @@
---
layout: sip
-title: SIP-NN - Converters among optional Functions, PartialFunctions and extractor objects
-vote-status: pending
+title: SIP-38 - Converters among optional Functions, PartialFunctions and extractor objects
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/converters-among-optional-functions-partialfunctions-and-extractor-object.html
---
+> This proposal has been implemented in Scala 2.13.0 and Scala 3.0.0.
+
**By: Yang Bo**
diff --git a/_sips/sips/curried-varargs.md b/_sips/sips/curried-varargs.md
new file mode 100644
index 0000000000..402630e152
--- /dev/null
+++ b/_sips/sips/curried-varargs.md
@@ -0,0 +1,6 @@
+---
+title: SIP-45 - Curried varargs
+status: rejected
+pull-request-number: 41
+
+---
diff --git a/_sips/sips/drop-stdlib-forwards-bin-compat.md b/_sips/sips/drop-stdlib-forwards-bin-compat.md
new file mode 100644
index 0000000000..771804f668
--- /dev/null
+++ b/_sips/sips/drop-stdlib-forwards-bin-compat.md
@@ -0,0 +1,315 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: implementation
+status: under-review
+title: SIP-51 - Drop Forwards Binary Compatibility of the Scala 2.13 Standard Library
+---
+
+**By: Lukas Rytz**
+
+
+## History
+
+| Date | Version |
+|----------------|--------------------|
+| Dec 8, 2022 | Initial Version |
+
+
+## Summary
+
+I propose to drop the forwards binary compatibility requirement that build tools enforce on the Scala 2.13 standard library.
+This will allow implementing performance optimizations of collection operations that are currently not possible.
+It also unblocks adding new classes and new members to existing classes in the standard library.
+
+
+## Backwards and Forwards Compatibility
+
+A library is backwards binary compatible if code compiled against an old version works with a newer version on the classpath.
+Forwards binary compatibility requires the opposite: code compiled against a new version of a library needs to work with an older version on the classpath.
+A more in-depth explanation of binary compatibility is available on the [Scala documentation site](https://docs.scala-lang.org/overviews/core/binary-compatibility-of-scala-releases.html).
+
+Scala build tools like sbt automatically update dependencies on the classpath to the latest patch version that any other dependency on the classpath requires.
+For example, with the following definition
+
+~~~ scala
+libraryDependencies ++= List(
+ "com.softwaremill.sttp.client3" %% "core" % "3.8.3", // depends on ws 1.3.10
+ "com.softwaremill.sttp.shared" %% "ws" % "1.2.7", // for demonstration
+)
+~~~
+
+sbt updates the `ws` library to version 1.3.10.
+Running the `evicted` command in sbt displays all dependencies whose version were changed.
+
+This build tool feature allows library authors to only maintain backwards binary compatibility in new versions, they don't need to maintain forwards binary compatibility.
+Backwards binary compatible changes include the addition of new methods in existing classes and the addition of new classes.
+Such additions don't impact existing code that was compiled against an older version, all definitions that were previously present are still there.
+
+### The Standard Library
+
+The Scala standard library is treated specially by sbt and other build tools, its version is always pinned to the `scalaVersion` of the build definition and never updated automatically.
+
+For example, the `"com.softwaremill.sttp.client3" %% "core" % "3.8.3"` library has a dependency on `"org.scala-lang" % "scala-library" % "2.13.10"` in its POM file.
+When a project uses this version of the sttp client in a project with `scalaVersion` 2.13.8, sbt will put the Scala library version 2.13.8 on the classpath.
+
+This means that the standard library is required to remain both backwards and forwards binary compatible.
+The implementation of sttp client 3.8.3 can use any feature available in Scala 2.13.10, and that compiled code needs to work correctly with the Scala 2.13.8 standard library.
+
+The suggested change of this SIP is to drop this special handling of the Scala standard library and therefore lift the forwards binary compatibility requirement.
+
+
+## Motivation
+
+### Adding Overrides for Performance
+
+The forwards binary compatibility constraint regularly prevents adding optimized overrides to collection classes.
+The reason is that the bytecode signature of an overriding method is not necessarily identical to the signature of the overridden method.
+Example:
+
+~~~ scala
+class A { def f: Object = "" }
+class B extends A { override def f: String = "" }
+~~~
+
+The bytecode signature of `B.f` has return type `String`.
+(In order to implement dynamic dispatch at run time (overriding), the compiler generates a "bridge" method `B.f` with return type `Object` which forwards to the other `B.f` method.)
+Adding such an override is not forwards binary compatible, because code compiled against `B` can link to the `B.f` method with return type `String`, which would not exist in the previous version.
+
+It's common that forwards binary compatibility prevents adding optimizing overrides, most recently in [LinkedHashMap](https://github.com/scala/scala/pull/10235#issuecomment-1336781619).
+
+Sometimes, if an optimization is considered important, a type test is added to the existing implementation to achieve the same effect.
+These workarounds could be cleaned up.
+Examples are [`mutable.Map.mapValuesInPlace`](https://github.com/scala/scala/blob/v2.13.10/src/library/scala/collection/mutable/Map.scala#L201-L204), [`IterableOnce.foldLeft`](https://github.com/scala/scala/blob/v2.13.10/src/library/scala/collection/IterableOnce.scala#L669-L670), [`Set.concat`](https://github.com/scala/scala/blob/v2.13.10/src/library/scala/collection/Set.scala#L226-L227), and many more.
+
+### Adding Functionality
+
+Dropping forwards binary compatiblity allows adding new methods to existing classes, as well as adding new classes.
+While this opens a big door in principle, I am certain that stability, consistency and caution will remain core considerations when discussing additions to the standard library.
+However, I believe that allowing to (carefully) evolve the standard library is greatly beneficial for the Scala community.
+
+Examples that came up in the past
+ - various proposals for new operations are here: https://github.com/scala/scala-library-next/issues and https://github.com/scala/scala-library-next/pulls
+ - addition of `ExecutionContext.opportunistic` in 2.13.4, which could not be made public: https://github.com/scala/scala/pull/9270
+ - adding `ByteString`: https://contributors.scala-lang.org/t/adding-akkas-bytestring-as-a-scala-module-and-or-stdlib/5967
+ - new string interpolators: https://github.com/scala/scala/pull/8654
+
+## Alternatives and Related Work
+
+For binary compatible overrides, it was considered to add an annotation that would enforce the existing signature in bytecode.
+However, this approach turned out to be too complex in the context of further overrides and Java compatibility.
+Details are in the [corresponding pull request](https://github.com/scala/scala/pull/9141).
+
+Extensions to the standard library can be implemented in a separate library, and such a library exists since 2020 as [scala-library-next](https://github.com/scala/scala-library-next).
+This library has seen very little adoption so far, and I personally don't think this is likely going (or possible) to change.
+One serious drawback of an external library is that operations on existing classes can only be added as extension methods, which makes them less discoverable and requires adding an import.
+This drawback could potentially be mitigated with improvements in Scala IDEs.
+
+An alternative to `scala-library-next` would be to use the Scala 3 library (`"org.scala-lang" % "scala3-library_3"`) which is published with Scala 3 releases.
+This library is handled by build tools like any other library and therefore open for backwards binary compatible additions.
+Until now, the Scala 3 library is exclusively used as a "runtime" library for Scala 3, i.e., it contanis definitions that are required for running code compiled with Scala 3.
+Additions to the Scala 3 library would not be available to the still very large userbase of Scala 2.13.
+Like for `scala-library-next`, additions to existing classes can again only be done in the form of extension methods.
+Also, I believe that there is great value in keeping the Scala 2.13 and 3 standard libraries aligned for now.
+
+
+## Implications
+
+### Possible Linkage Errors
+
+The policy change can only be implemented in new build tool releases, which makes it possible that projects run into linkage errors at run time.
+Concretely, a project might update one of its dependencies to a new version which requires a more recent Scala library than the one defined in the project's `scalaVersion`.
+If the project continues using an old version of sbt, the build tool will keep the Scala library pinned.
+The new library might reference definitions that don't exist in the older Scala library, leading to linkage errors.
+
+### Scala.js and Scala Native
+
+Scala.js distributes a JavaScript version of the Scala library.
+This artifact is currently released once per Scala.js version.
+When a new Scala version comes out, a new Scala.js compiler is released, but the Scala library artifact continues to be used until the next Scala.js version.
+This scheme does not work if the new Scala version has new definitions, so it needs to be adjusted.
+Finding a solution for this problem is necessary and part of the implementation phase.
+
+A similar situation might exist for Scala Native.
+
+### Compiler and Library Version Mismatch
+
+Defining the `scalaVersion` in a project would no longer pin the standard library to that exact version.
+The Scala compiler on the other hand would be kept at the specified version.
+This means that Scala compilers will need to be able to run with a newer version of the Scala library, e.g., the Scala compiler 2.13.10 needs to be able to run with a 2.13.11 standard library on the compilation classpath.
+I think this will not cause any issues.
+
+Note that there are two classpaths at play here: the runtime classpath of the JVM that is running the Scala compiler, and the compilation classpath in which the compiler looks up symbols that are referenced in the source code being compiled.
+The Scala library on the JVM classpath could remain in sync with the compiler version.
+The Scala library on the compilation classpath would be updated by the build tool according to the dependency graph.
+
+### Newer than Expected Library
+
+Because the build tool can update the Scala library version, a project might accidentally use / link to new API that does not yet exist in the `scalaVersion` that is defined in the build definition.
+This is safe, as the project's POM file will have a dependency on the newer version of the Scala library.
+The same situation can appear with any other dependency of a project.
+
+### Applications with Plugin Systems
+
+In applications where plugins are dynamically loaded, plugins compiled with a new Scala library could fail to work correctly if the application is running with an older Scala library.
+
+This is however not a new issue, the proposed change would just extend the existing problem to the Scala library.
+
+## Limitations
+
+Adding new methods or fields to existing traits remains a binary incompatible change.
+This is unrelated to the Standard library, the same is true for other libraries.
+[MiMa](https://github.com/lightbend/mima) is a tool for ensuring changes are binary compatible.
+
+
+## Build Tools
+
+### Mill
+
+In my testing, Mill has the same behavior as sbt, the Scala library version is pinned to the project's `scalaVersion`.
+
+` token that reads as
+the standard colon "`:`" but is generated instead of it where ``
+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`, "`)`", and "`]`".
+
+> An indentation region can start after a ``. A template body may be either enclosed in braces, or it may start with
+` ` and end with ``.
+Analogous rules apply for enum bodies, type refinements, and local packages containing nested definitions.
+
+Generally, the possible indentation regions coincide with those regions where braces `{...}` are also legal, no matter whether the braces enclose an expression or a set of definitions. There is so far one exception, though: Arguments to functions can be enclosed in braces but they cannot be simply indented instead. Making indentation always significant for function arguments would be too restrictive and fragile.
+
+To allow such arguments to be written without braces, a variant of the indentation scheme is implemented under language import
+```scala
+import language.experimental.fewerBraces
+```
+This SIP proposes to make this variant the default, so no language import is needed to enable it.
+In this variant, a `` token is also recognized where function argument would be expected. Examples:
+
+```scala
+times(10):
+ println("ah")
+ println("ha")
+```
+
+or
+
+```scala
+credentials `++`:
+ val file = Path.userHome / ".credentials"
+ if file.exists
+ then Seq(Credentials(file))
+ else Seq()
+```
+
+or
+
+```scala
+xs.map:
+ x =>
+ val y = x - 1
+ y * y
+```
+What's more, a `:` in these settings can also be followed on the same line by the parameter part and arrow of a lambda. So the last example could be compressed to this:
+
+```scala
+xs.map: x =>
+ val y = x - 1
+ y * y
+```
+and the following would also be legal:
+```scala
+xs.foldLeft(0): (x, y) =>
+ x + y
+```
+
+The grammar changes for this variant are as follows.
+
+```
+SimpleExpr ::= ...
+ | SimpleExpr ColonArgument
+InfixExpr ::= ...
+ | InfixExpr id ColonArgument
+ColonArgument ::= colon [LambdaStart]
+ indent (CaseClauses | Block) outdent
+LambdaStart ::= FunParams (‘=>’ | ‘?=>’)
+ | HkTypeParamClause ‘=>’
+```
+## Compatibility
+
+The proposed solution changes the meaning of the following code fragments:
+```scala
+ val x = y:
+ Int
+
+ val y = (xs.map: (Int => Int) =>
+ Int)
+```
+In the first case, we have a type ascription where the type comes after the `:`. In the second case, we have
+a type ascription in parentheses where the ascribing function type is split by a newline. Note that we have not found examples like this in the dotty codebase or in the community build. We verified this by compiling everything with success with `fewerBraces` enabled. So we conclude that incompatibilities like these would be very rare.
+If there would be code using these idioms, it can be rewritten quite simply to avoid the problem. For instance, the following fragments would be legal (among many other possible variations):
+```scala
+ val x = y
+ : Int
+
+ val y = (xs.map: (Int => Int)
+ => Int)
+```
+
+## Other concerns
+
+### Tooling
+
+Since this affects parsing, the scalameta parser and any other parser used in an IDE will also need to be updated. The necessary changes to the Scala 3 parser were made here: https://github.com/scala/scala3/pull/15273/commits. The commit that embodies the core change set is here: https://github.com/scala/scala3/pull/15273/commits/421bdd660b0456c2ff1ae386f032c41bb1e0212a.
+
+### Handling Edge Cases
+
+The design intentionally does not allow `:` to be placed after an infix operator or after a previous indented argument. This is a consequence of the following clause in the spec above:
+
+> To this purpose we introduce a new `` token that reads as
+the standard colon "`:`" but is generated instead of it where ``
+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`, "`)`", and "`]`".
+
+This was done to prevent hard-to-decypher symbol salad as in the following cases: (1)
+```scala
+a < b || : // illegal
+ val x = f(c)
+ x > 0
+```
+or (2)
+```scala
+source --> : x => // illegal
+ val y = x * x
+ println(y)
+```
+or (3)
+```scala
+xo.fold:
+ defaultValue
+: // illegal
+ x => f(x)
+```
+or (4)
+```scala
+xs.groupMapReduce: item =>
+ key(item)
+: item => // illegal
+ value(item)
+: (value1, value2) => // illegal
+ reduce(value1, value2)
+```
+
+I argue that the language already provides mechanisms to express these examples without having to resort to braces. (Aside: I don't think that resorting to braces occasionally is a bad thing, but some people argue that it is, so it's good to have alternatives). Basically, we have three options
+
+ - Use parentheses.
+ - Use an explicit `apply` method call.
+ - Use a `locally` call.
+
+Here is how the examples above can be rewritten so that they are legal but still don't use braces:
+
+For (1), use `locally`:
+```scala
+a < b || locally:
+ val x = f(c)
+ x > 0
+```
+For (2), use parentheses:
+```scala
+source --> ( x =>
+ val y = x * x
+ println(y)
+)
+```
+For (3) and (4), use `apply`:
+```scala
+xo.fold:
+ defaultValue
+.apply:
+ x => f(x)
+
+xs.groupMapReduce: item =>
+ key(item)
+.apply: item =>
+ value(item)
+.apply: (value1, value2) =>
+ reduce(value1, value2)
+```
+**Note 1:** I don't argue that this syntax is _more readable_ than braces, just that it is reasonable. The goal of this SIP is to have the nicer syntax for
+all common cases and to not be atrocious for edge cases. I think this
+goal is achieved by the presented design.
+
+**Note 2:** The Scala compiler should add a peephole optimization
+that elides an eta expansion in front of `.apply`. E.g. the `fold` example should be compiled to the same code as `xs.fold(defaultValue)(x => f(x))`.
+
+**Note 3:** To avoid a runtime footprint, the `locally` method should be an inline method. We can achieve that by shadowing the stdlib, or else we can decide on a different name. `nested` or `block` have been proposed. In any case this could be done in a separate step.
+
+### Syntactic confusion with type ascription
+
+A frequently raised concern against using `:` as an indentation marker is that it is too close to type ascription and therefore might be confusing.
+
+However, I have seen no evidence so far that this is true in practice. Of course, one can make up examples that look ambiguous. But as outlined, the community build and the dotty code base do not contain a single case where
+a type ascription is now accidentally interpreted as an argument.
+
+Also the fact that Python chose `:` for type ascription even though it was already used as an indentation marker should give us confidence.
+
+In well written future Scala code we can use visual keys that would tell us immediately which is which. Namely:
+
+> If the `:` or `=>` is at the end of a line, it's an argument, otherwise it's a type ascription.
+
+According to the current syntax, if you want a multi-line type ascription, you _cannot_ write
+```scala
+anExpr:
+ aType
+```
+It _must be_ rewritten to
+```scala
+anExpr
+ : aType
+```
+(But, as stated above, it seems nobody actually writes code like that).
+Similarly, it is _recommended_ that you put `=>` in a multi-line function type at the start of lines instead of at the end. I.e. this code does not follow the guidelines (even though it is technically legal):
+```scala
+xs.map: ((x: Int) =>
+ Int)
+```
+You should reformat it like this:
+```scala
+val y = xs.map: ((x: Int)
+ => Int)
+```
+If we propose these guidelines then the only problem that remains is that if one intentionally writes confusing layout _and_ one reads only superficially then things can be confusing. But that's really nothing out of the ordinary.
+
+
+## Open questions
+
+None directly related to the SIP. As mentioned above we should decide eventually whether we should stick with `locally` or replace it by something else. But that is unrelated to the SIP proper and can be decided independently.
+
+## Alternatives
+
+I considered two variants:
+
+The first variant would allow lambda parameters without preceding colons. E.g.
+```scala
+xs.foldLeft(z)(a, b) =>
+ a + b
+```
+We concluded that this was visually less good since it looks too much like a function call `xs.foldLeft(z)(a, b)`.
+
+The second variant would always require `(...)` around function types in ascriptions (which is in fact what the official syntax requires). That would have completely eliminated the second ambiguity above since
+```scala
+val y = (xs.map: (Int => Int) =>
+ Int)
+```
+would then not be legal anyway. But it turned out that there were several community projects that were using function types in ascriptions without enclosing parentheses, so this change was deemed to break too much code.
+
+@sjrd proposed in a [feature request](https://github.com/lampepfl/dotty-feature-requests/issues/299) that the `:` could be left out when
+followed by `case` on the next line. Example:
+```scala
+ val xs = List((1, "hello"), (true, "bar"), (false, "foo"))
+ val ys = xs.collect // note: no ':' here
+ case (b: Boolean, s) if b => s
+ println(ys)
+```
+This is a tradeoff between conciseness and consistency. In the interest of minimality, I would leave it out of the first version of the implementation. We can always add it later if we feel a need for it.
+
+## Related work
+
+ - Doc page for proposed change: https://dotty.epfl.ch/docs/reference/other-new-features/indentation.html#variant-indentation-marker--for-arguments
+
+ - Merged PR implementing the proposal under experimental flag: https://github.com/scala/scala3/pull/15273/commits/421bdd660b0456c2ff1ae386f032c41bb1e0212a
+
+ - Latest discussion on contributors (there were several before when we discussed indentation in general): https://contributors.scala-lang.org/t/make-fewerbraces-available-outside-snapshot-releases/5024/166
+
+## FAQ
+
diff --git a/_sips/sips/2012-01-21-futures-promises.md b/_sips/sips/futures-promises.md
similarity index 99%
rename from _sips/sips/2012-01-21-futures-promises.md
rename to _sips/sips/futures-promises.md
index 85da52ba91..26e067bfaa 100644
--- a/_sips/sips/2012-01-21-futures-promises.md
+++ b/_sips/sips/futures-promises.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SIP-14 - Futures and Promises
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/futures-promises.html
---
@@ -714,14 +714,14 @@ Examples:
## References
-1. [The Task-Based Asynchronous Pattern, Stephen Toub, Microsoft, April 2011][1]
+1. [The Task-Based Asynchronous Pattern, Stephen Toub, Microsoft, February 2012][1]
2. [Finagle Documentation][2]
3. [Akka Documentation: Futures][3]
4. [Scala Actors Futures][4]
5. [Scalaz Futures][5]
- [1]: https://www.microsoft.com/download/en/details.aspx?id=19957 "NETAsync"
- [2]: https://twitter.github.com/scala_school/finagle.html "Finagle"
+ [1]: https://download.microsoft.com/download/5/B/9/5B924336-AA5D-4903-95A0-56C6336E32C9/TAP.docx "NETAsync"
+ [2]: https://twitter.github.io/scala_school/finagle.html "Finagle"
[3]: https://doc.akka.io/docs/akka/current/futures.html "AkkaFutures"
[4]: https://web.archive.org/web/20140814211520/https://www.scala-lang.org/api/2.9.3/scala/actors/Future.html "SActorsFutures"
[5]: https://code.google.com/p/scalaz/ "Scalaz"
diff --git a/_sips/sips/2011-10-12-implicit-classes.md b/_sips/sips/implicit-classes.md
similarity index 91%
rename from _sips/sips/2011-10-12-implicit-classes.md
rename to _sips/sips/implicit-classes.md
index 6868d5fb34..495bcadf23 100644
--- a/_sips/sips/2011-10-12-implicit-classes.md
+++ b/_sips/sips/implicit-classes.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SIP-13 - Implicit classes
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/implicit-classes.html
---
@@ -11,7 +11,7 @@ redirect_from: /sips/pending/implicit-classes.html
This SIP is based on [this pre-draft](https://docs.google.com/document/d/1k-aGAGmbrDB-2pJ3uDPpHVKno6p-XbnkVHDc07zPrzQ/edit?hl=en_US).
-Material adapted from [https://jorgeortiz85.github.com/ImplicitClassSIP.xhtml](https://jorgeortiz85.github.com/ImplicitClassSIP.xhtml) which is Copyright © 2009, Jorge Ortiz and David Hall
+Material adapted from [https://jorgeortiz85.github.io/ImplicitClassSIP.xhtml](https://jorgeortiz85.github.io/ImplicitClassSIP.xhtml) which is Copyright © 2009, Jorge Ortiz and David Hall
## Abstract ##
diff --git a/_sips/sips/implicit-macro-conversions.md b/_sips/sips/implicit-macro-conversions.md
new file mode 100644
index 0000000000..82e7ab2ff5
--- /dev/null
+++ b/_sips/sips/implicit-macro-conversions.md
@@ -0,0 +1,7 @@
+---
+title: SIP-66 - Implicit macro conversions
+status: under-review
+pull-request-number: 86
+stage: design
+
+---
diff --git a/_sips/sips/implicit-source-locations.md b/_sips/sips/implicit-source-locations.md
new file mode 100644
index 0000000000..a51a574f5d
--- /dev/null
+++ b/_sips/sips/implicit-source-locations.md
@@ -0,0 +1,6 @@
+---
+title: SIP-19 - Implicit Source Locations
+status: rejected
+pull-request-number: 18
+
+---
diff --git a/_sips/sips/improve-strictequality-feature-for-better-compatibility-with-existing-code-bases.md b/_sips/sips/improve-strictequality-feature-for-better-compatibility-with-existing-code-bases.md
new file mode 100644
index 0000000000..29276bba12
--- /dev/null
+++ b/_sips/sips/improve-strictequality-feature-for-better-compatibility-with-existing-code-bases.md
@@ -0,0 +1,8 @@
+---
+title: SIP-67 - Improve strictEquality feature for better compatibility with existing
+ code bases
+status: waiting-for-implementation
+pull-request-number: 97
+stage: implementation
+
+---
diff --git a/_sips/sips/improved-lazy-vals-initialization.md b/_sips/sips/improved-lazy-vals-initialization.md
new file mode 100644
index 0000000000..efb891962b
--- /dev/null
+++ b/_sips/sips/improved-lazy-vals-initialization.md
@@ -0,0 +1,7 @@
+---
+title: SIP-20 - Improved Lazy Vals Initialization
+status: shipped
+pull-request-number: 19
+stage: completed
+
+---
diff --git a/_sips/sips/improving-binary-compatibility-with-stableabi.md b/_sips/sips/improving-binary-compatibility-with-stableabi.md
new file mode 100644
index 0000000000..6e48e46553
--- /dev/null
+++ b/_sips/sips/improving-binary-compatibility-with-stableabi.md
@@ -0,0 +1,6 @@
+---
+title: SIP-34 - Improving binary compatibility with @stableABI
+status: withdrawn
+pull-request-number: 30
+
+---
diff --git a/_sips/sips/inline-meta.md b/_sips/sips/inline-meta.md
new file mode 100644
index 0000000000..c27ee3530a
--- /dev/null
+++ b/_sips/sips/inline-meta.md
@@ -0,0 +1,6 @@
+---
+title: SIP-28 - Inline meta
+status: withdrawn
+pull-request-number: 28
+
+---
diff --git a/_sips/sips/2010-01-27-internals-of-scala-annotations.md b/_sips/sips/internals-of-scala-annotations.md
similarity index 74%
rename from _sips/sips/2010-01-27-internals-of-scala-annotations.md
rename to _sips/sips/internals-of-scala-annotations.md
index a21defafcc..792f7ee8ee 100644
--- a/_sips/sips/2010-01-27-internals-of-scala-annotations.md
+++ b/_sips/sips/internals-of-scala-annotations.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-5 - Internals of Scala Annotations
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/internals-of-scala-annotations.html
---
diff --git a/_sips/sips/2018-07-31-interpolation-quote-escape.md b/_sips/sips/interpolation-quote-escape.md
similarity index 93%
rename from _sips/sips/2018-07-31-interpolation-quote-escape.md
rename to _sips/sips/interpolation-quote-escape.md
index fe6615f12f..6f0398ce33 100644
--- a/_sips/sips/2018-07-31-interpolation-quote-escape.md
+++ b/_sips/sips/interpolation-quote-escape.md
@@ -1,11 +1,14 @@
---
layout: sip
-title: SIP-NN - Quote escapes for interpolations
-vote-status: pending
+title: SIP-37 - Quote escapes for interpolations
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/interpolation-quote-escape.html
---
+> This proposal has been implemented in Scala 2.13.6 and Scala 3.0.0.
+
**By: Martijn Hoekstra**
## History
@@ -35,7 +38,7 @@ escape a `"` character to represent a literal `"` withing a string.
## Motivating Example
That the `"` character can't be easily escaped in interpolations has been an
-open issue since at least 2012[^1], and how to deal with this issue is a
+open issue since at least 2012[^1], and how to deal with this issue is a
somewhat common SO question[^2][^3]
{% highlight Scala %}
@@ -126,4 +129,4 @@ proposals.
[^4]: https://github.com/scala/bug/issues/6476#issuecomment-292412577 "@retronym said: +1 to s"$"". Because it doesn't compile today, we don't risk changing the meaning of existing programs."
[^5]: https://github.com/Scala/Scala/pull/6953/files#diff-0023b3bfa053fb16603156b785efa7ad ""
[^6]: https://github.com/Scala/Scala/pull/4308 "SI-6476 Accept escaped quotes in interp strings"
-[^7]: https://github.com/lampepfl/dotty/pull/7486 "PR in dotty"
+[^7]: https://github.com/scala/scala3/pull/7486 "PR in dotty"
diff --git a/_sips/sips/match-types-spec.md b/_sips/sips/match-types-spec.md
new file mode 100644
index 0000000000..049fad9415
--- /dev/null
+++ b/_sips/sips/match-types-spec.md
@@ -0,0 +1,590 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: completed
+status: shipped
+title: SIP-56 - Proper Specification for Match Types
+---
+
+**By: Sébastien Doeraene**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Aug 11th 2023 | Initial Draft |
+
+## Summary
+
+Currently, match type reduction is not specified, and its implementation is by nature not specifiable.
+This is an issue because match type reduction spans across TASTy files (unlike, for example, type inference or GADTs), which can and will lead to old TASTy files not to be linked again in future versions of the compiler.
+
+This SIP proposes a proper specification for match types, which does not involve type inference.
+It is based on `baseType` computations and subtype tests involving only fully-defined types.
+That is future-proof, because `baseType` and subtyping are defined in the specification of the language.
+
+The proposed specification defines a subset of current match types that are considered legal.
+Legal match types use the new, specified reduction rules.
+Illegal match types are rejected, which is a breaking change, and can be recovered under `-source:3.3`.
+
+In addition, the proposal gives a specification for `provablyDisjoint` and for the reduction algorithm.
+
+## Motivation
+
+Currently, match type reduction is implementation-defined.
+The core of the logic is matching a scrutinee type `X` against a pattern `P` with captures `ts`.
+Captures are similar to captures in term-level pattern matching: in the type-level `case List[t] =>`, `t` is a (type) capture, just like in the term-level `case List(x) =>`, `x` is a (term) capture.
+Matching works as follows:
+
+1. we create new type variables for the captures `ts'` giving a pattern `P'`,
+2. we ask the compiler's `TypeComparer` (the type inference black box) to "try and make it so" that `X <:< P'`,
+3. if it manages to do so, we get constraints for `ts'`; we then have a match, and we instantiate the body of the pattern with the received constraints for `ts`.
+
+The problem with this approach is that, by essence, type inference is an unspecified black box.
+There are *guidelines* about how it should behave in common cases, but no actual guarantee.
+This is fine everywhere else in the language, because what type inference comes up with is stored once and for all in TASTy.
+When we read TASTy files, we do not have to perform the work of type inference again; we reuse what was already computed.
+When a new version of the compiler changes type inference, it does not change what was computed and stored in TASTy files by previous versions of the compiler.
+
+For match types, this is a problem, because reduction spans across TASTy files.
+Given some match type `type M[X] = X match { ... }`, two codebases may refer to `M[SomeType]`, and they must reduce it in the same way.
+If they don't, hard incompatibilities can appear, such as broken subtyping, broken overriding relationships, or `AbstractMethodError`s due to inconsistent erasure.
+
+In order to guarantee compatibility, we must ensure that, for any given match type:
+
+* if it reduces in a given way in version 1 of the compiler, it still reduces in the same way in version 2, and
+* if it does not reduce in version 1 of the compiler, it still does not reduce in version 2.
+* (it is possible for version 1 to produce an *error* while version 2 successfully reduces or does not reduce)
+
+Reduction depends on two decision produces:
+
+* *matching* a scrutinee `X` against a pattern `P` (which we mentioned above), and
+* deciding whether a scrutinee `X` is *provably disjoint* from a pattern `P`.
+
+When a scrutinee does not match a given pattern and cannot be proven disjoint from it either, the match type is "stuck" and does not reduce.
+
+If matching is delegated to the `TypeComparer` black box, then it is impossible in practice to guarantee the first compatibility property.
+
+In addition to the compatibility properties above, there is also a soundness property that we need to uphold:
+
+* if `X match { ... }` reduces to `R` and `Y <: X`, then `Y match { ... }` also reduces to `R`.
+
+This requires both that *matching* with a tighter scrutinee gives the same result, and that `provablyDisjoint(X, P)` implies `provablyDisjoint(Y, P)`.
+(Those properties must be relaxed when `Y <: Nothing`, in order not to create more problems; see Olivier Blanvillain's thesis section 4.4.2 for details.)
+With the existing implementation for `provablyDisjoint`, there are reasonable, non-contrived examples that violate this property.
+
+In order to solve these problems, this SIP provides a specification for match type reduction that is independent of the `TypeComparer` black box.
+It defines a subset of match type cases that are considered legal.
+Legal cases get a specification for when and how they should reduce for any scrutinee.
+Illegal cases are rejected as being outside of the language.
+
+For compatibility reasons, such now-illegal cases will still be accepted under `-source:3.3`; in that case, they reduce using the existing, unspecified (and prone to breakage) implementation.
+Due to practical reasons (see "Other concerns"), doing so does *not* emit any warning.
+Eventually, support for this fallback may be removed if the compiler team decides that its maintenance burden is too high.
+As usual, this SIP does not by itself provide any specific timeline.
+In particular, there is no relationship with 3.3 being an "LTS"; it just happens to be the latest "Next" as well at the time of this writing (the changes in this SIP will only ever apply to 3.4 onwards, so the LTS is not affected in any way).
+
+For legal cases, the proposed reduction specification should reduce in the same way as the current implementation for all but the most obscure cases.
+Our tests, including the entire dotty CI and its community build, did not surface any such incompatibility.
+It is however not possible to guarantee that property for *all* cases, since the existing implementation is not specified in the first place.
+
+## Proposed solution
+
+### Specification
+
+#### Preamble
+
+Some of the concepts mentioned here are defined in the existing Scala 3 specification draft.
+That draft can be found in the dotty repository at https://github.com/scala/scala3/tree/main/docs/_spec.
+It is not rendered anywhere yet, though.
+
+Here are some of the relevant concepts that are perhaps lesser-known:
+
+* Chapter 3, section "Internal types": concrete v abstract syntax of types.
+* Chapter 3, section "Base Type": the `baseType` function.
+* Chapter 3, section "Definitions": whether a type is concrete or abstract (unrelated to the concrete or abstract *syntax*).
+
+#### Syntax
+
+Syntactically, nothing changes.
+The way that a pattern is parsed and type captures identified is kept as is.
+
+Once type captures are identified, we can represent the *abstract* syntax of a pattern as follows:
+
+```
+// Top-level pattern
+MatchTypePattern ::= TypeWithoutCapture
+ | MatchTypeAppliedPattern
+
+// A type that does not contain any capture, such as `Int` or `List[String]`
+TypeWithoutCapture ::= Type // `Type` is from the "Internal types" section of the spec
+
+// Applied type pattern with at least one capture, such as `List[Seq[t]]` or `*:[Int, t]`
+MatchTypeAppliedPattern ::= TyconWithoutCapture ‘[‘ MatchTypeSubPattern { ‘,‘ MatchTypeSubPattern } ‘]‘
+
+// The type constructor of a MatchTypeAppliedPattern never contains any captures
+TyconWithoutCapture ::= Type
+
+// Type arguments can be captures, types without captures, or nested applied patterns
+MatchTypeSubPattern ::= TypeCapture
+ | TypeWithoutCapture
+ | MatchTypeAppliedPattern
+
+TypeCapture ::= NamedTypeCapture // e.g., `t`
+ | WildcardTypeCapture // `_` (with inferred bounds)
+```
+
+In the concrete syntax, `MatchTypeAppliedPattern`s can take the form of `InfixType`s.
+A common example is `case h *: t =>`, which is desugared into `case *:[h, t] =>`.
+
+The cases `MatchTypeAppliedPattern` are only chosen if they contain at least one `TypeCapture`.
+Otherwise, they are considered `TypeWithoutCapture` instead.
+Each named capture appears exactly once.
+
+#### Legal patterns
+
+A `MatchTypePattern` is legal if and only if one of the following is true:
+
+* It is a `TypeWithoutCapture`, or
+* It is a `MatchTypeAppliedPattern` with a legal `TyconWithoutCapture` and each of its arguments is either:
+ * A `TypeCapture`, or
+ * A `TypeWithoutCapture`, or
+ * The type constructor is *covariant* in that parameter, and the argument is recursively a legal `MatchTypeAppliedPattern`.
+
+A `TyconWithoutCapture` is legal 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 refined type of the form `Base { type Y = t }` where:
+ * `Base` is a `TypeWithoutCapture`,
+ * There exists a type member `Y` in `Base`, and
+ * `t` is a `TypeCapture`.
+* It is a type alias to a type lambda 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.
+
+#### Examples of legal patterns
+
+Given the following definitions:
+
+```scala
+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:
+
+```scala
+// 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:
+
+```scala
+// 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 = _`:
+ * Instantiate `ti` so that the subtype test in Step (2) above always succeeds:
+ * If `X` is of the form `_ >: L <: H`, instantiate `ti := H` (resp. `L`, `X`) if `variance = 1` (resp. `-1`, `0`).
+ * 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 `i`th 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 `i`th 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.Y` is abstract, fail as not specific.
+ * If `q.Y` is a class member:
+ * If `q` is a skolem type `∃α:X`, fail as not specific.
+ * Otherwise, compute `matchPattern(ti, q.Y, 0, scrutIsWidenedAbstract)`.
+ * Otherwise, the underlying type definition of `q.Y` is of the form `= U`:
+ * If `q` is not a skolem type `∃α:X`, compute `matchPattern(ti, U, 0, scrutIsWidenedAbstract)`.
+ * Otherwise, let `U' = dropSkolem(U)` be computed as follow:
+ * `dropSkolem(q)` is undefined.
+ * `dropSkolem(p.T) = p'.T` where `p' = dropSkolem(p)` if the latter is defined. Otherwise:
+ * If the underlying type of `p.T` is of the form `= V`, then `dropSkolem(V)`.
+ * Otherwise `dropSkolem(p.T)` is undefined.
+ * `dropSkolem(p.x) = p'.x` where `p' = dropSkolem(p)` if the latter is defined. Otherwise:
+ * If the dealiased underlying type of `p.x` is a singleton type `r.y`, then `dropSkolem(r.y)`.
+ * Otherwise `dropSkolem(p.x)` is undefined.
+ * For all other types `Y`, `dropSkolem(Y)` is the type formed by replacing each component `Z` of `Y` by `dropSkolem(Z)`.
+ * If `U'` is undefined, fail as not specific.
+ * Otherwise, compute `matchPattern(ti, U', 0, scrutIsWidenedAbstract)`.
+ * 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
+
+This proposal initially did not include a discussion of disjointness.
+After initial review, it became apparent that it should also provide a specification for the "provably disjoint" test involved in match type reduction.
+Additional study revealed that, while *specifiable*, the current algorithm is very ad hoc and severely lacks desirable properties such as preservation along subtyping (see towards the end of this section).
+
+Therefore, this proposal now also includes a proposed specification for "provably disjoint".
+To the best of our knowledge, it is strictly stronger than what is currently implemented, with one exception.
+
+The current implementation considers that `{ type A = Int }` is provably disjoint from `{ type A = Boolean }`.
+However, it is not able to prove disjointness between any of the following:
+
+* `{ type A = Int }` and `{ type A = Boolean; type B = String }` (adding another type member)
+* `{ type A = Int; type B = Int }` and `{ type B = String; type A = String }` (switching the order of type members)
+* `{ type A = Int }` and class `C` that defines a member `type A = String`.
+
+Therefore, we drop the very ad hoc case of one-to-one type member refinements.
+
+On to the specification.
+
+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 types that capture the concepts mentioned above.
+
+A "simple type" is one of:
+
+* `Nothing`
+* `AnyKind`
+* `p.C[...Xi]` a possibly parameterized class type, where `p` and `...Xi` 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 `case`s
+* `X₁ & X₂` where `X₁` and `X₂` are both simple types
+* `X₁ | X₂` where `X₁` and `X₂` are both simple types
+* `[...ai] =>> X₁` where `X₁` 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[...Ti]⌉ = ⌈Y⌉` where `Y` is the beta-reduction of `X[...Ti]` if `X` is a type lambda
+* `⌈X[...Ti]⌉ = ⌈⌈X⌉[...Ti⌉` if `X` is neither a type lambda nor a class type designator
+* `⌈X @a⌉ = ⌈X⌉`
+* `⌈X { R }⌉ = ⌈X⌉`
+* `⌈{ α => X } = ⌈X⌉⌉`
+* `⌈X₁ & X₂⌉ = ⌈X₁⌉ & ⌈X₂⌉`
+* `⌈X₁ | X₂⌉ = ⌈X₁⌉ | ⌈X₂⌉`
+* `⌈[...ai] =>> X₁⌉ = [...ai] =>> ⌈X₁⌉`
+
+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 and hidden classes of objects) 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 `class`es `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 `Ci ⋔ D` for all direct children `Ci` of `C`
+* `C ⋔ D` if `D` is `sealed` without anonymous child and `C ⋔ Di` for all direct children `Di` 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 ⋔ T1 | T2` if `S ⋔ T1` and `S ⋔ T2`
+ * `S1 | S2 ⋔ T` if `S1 ⋔ T` and `S2 ⋔ T`
+* An intersection type is disjoint from another type if at least one of its parts is disjoint from that type:
+ * `S ⋔ T1 & T2` if `S ⋔ T1` or `S ⋔ T2`
+ * `S1 & S2 ⋔ T` if `S1 ⋔ T` or `S1 ⋔ T`
+* A type lambda is disjoint from any other type that is not a type lambda with the same number of parameters:
+ * `[...ai] =>> S1 ⋔ q.D.y`
+ * `[...ai] =>> S1 ⋔ d`
+ * `[...ai] =>> S1 ⋔ q.D[...Ti]`
+ * `p.C.x ⋔ [...bi] =>> T1`
+ * `c ⋔ [...bi] =>> T1`
+ * `p.C[...Si] ⋔ [...bi] =>> T1`
+ * `[a1, ..., an] =>> S1 ⋔ [b1, ..., bm] =>> T1` if `m != n`
+* Two type lambdas with the same number of type parameters are disjoint if their result types are disjoint:
+ * `[a1, ..., an] =>> S1 ⋔ [b1, ..., bn] =>> T1` if `S1 ⋔ T1`
+* 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 != D` or `x != y`
+* Two literal types are disjoint if they are different:
+ * `c ⋔ d` if `c != 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[...Ti]` if `baseType(p.C.x, D)` is not defined
+ * `p.C[...Si] ⋔ q.D.y` if `baseType(q.D.y, C)` is not defined
+ * `c ⋔ q.D[...Ti]` if `baseType(c, D)` is not defined
+ * `p.C[...Si] ⋔ d` if `baseType(d, C)` is not defined
+* Two class types are disjoint if the classes themselves are disjoint, or if there exist a common super type with conflicting type arguments.
+ * `p.C[...Si] ⋔ q.D[...Ti]` if `C ⋔ D`
+ * `p.C[...Si] ⋔ q.D[...Ti]` if there exists a class `E` such that `baseType(p.C[...Si], E) = a.E[...Ai]` and `baseType(q.D[...Ti], E) = b.E[...Bi]` and there exists a pair `(Ai, Bi)` such that
+ * `Ai ⋔ Bi` and it is in invariant position, or
+ * `Ai ⋔ Bi` and it is in covariant position and there exists a field of that type parameter in `E`
+
+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, which does not hold at all for the current implementation of match types.
+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 final piece of the match types puzzle is to define the reduction as a whole.
+
+In addition to matching and `provablyDisjoint`, the existing algorithm relies on a `provablyEmpty` property for a single type.
+It was added a safeguard against matching an empty (`Nothing`) scrutinee.
+The problem with doing so is that an empty scrutinee will be considered *both* as matching the pattern *and* as provably disjoint from the pattern.
+This can result in the match type reducing to different cases depending on the context.
+To sidestep this issue, the current algorithm refuses to consider a scrutinee that is `provablyEmpty`.
+
+If we wanted to keep that strategy, we would also have to specify `provablyEmpty` and prove some properties about it.
+Instead, we choose a much simpler and safer strategy: we always test both matching *and* `provablyDisjoint`.
+When both apply, we deduce that the scrutinee is empty is refuse to reduce the match type.
+
+Therefore, in summary, the whole reduction algorithm works as follows.
+The result of reducing `X match { case P1 => R1; ...; case Pn => Rn }` can be a type, undefined, or a compile error.
+For `n >= 1`, it is specified as:
+
+* If `X` matches `P1` with type capture instantiations `[...ts => ts']`:
+ * If `X ⋔ P1`, do not reduce.
+ * Otherwise, reduce as `[...ts => ts']R1`.
+* Otherwise,
+ * If `X ⋔ P1`, the result of reducing `X match { case P2 => R2; ...; case Pn => Rn }` (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.
+
+#### Subtyping
+
+As is already the case in the existing system, match types tie into subtyping as follows:
+
+* `X match { ... } <: T` if `X match { ... }` reduces to `S1` and `S1 <: T`
+* `S <: X match { ... }` if `X match { ... }` reduces to `T1` and `S <: T1`
+* `X match { ... } <: T` if `X match { ... }` has the upper bound `H` and `H <: T`
+* `X match { case P1 => A1; ...; case Pn => An } <: Y match { case Q1 => B1; ...; Qn => Bn }` if `X =:= Y` and `Pi =:= Qi` for each `i` and `Ai <: Bi` for each `i`
+
+### Compatibility
+
+Compatibility is inherently tricky to evaluate for this proposal, and even to define.
+One could argue that, from a pure specification point of view, it breaks nothing since it only specifies things that were unspecified before.
+However, that is not very practical.
+In practice, this proposal definitely breaks some code that compiled before, due to making some patterns illegal.
+In exchange, it promises that all the patterns that are considered legal will keep working in the future; which is not the case with the current implementation, even for the legal subset.
+
+In order to evaluate the practical impact of this proposal, we conducted a quantitative analysis of *all* the match types found in Scala 3 libraries published on Maven Central.
+We used [Scaladex](https://index.scala-lang.org/) to list all Scala 3 libraries, [coursier](https://get-coursier.io/docs/api) to resolve their classpaths, and [tasty-query](https://github.com/scalacenter/tasty-query) to semantically analyze the patterns of all the match types they contain.
+
+Out of 4,783 libraries, 49 contained at least one match type definition.
+These 49 libraries contained a total of 779 match type `case`s.
+Of those, there were 8 `case`s that would be flagged as not legal by the current proposal.
+
+These can be categorized as follows:
+
+* 2 libraries with 1 type member extractor each where the `Base` does not contain `Y`; they are both to extract `SomeEnumClass#Value` (from Scala 2 `scala.Enumeration`-based "enums").
+ * https://github.com/iheartradio/ficus/blob/dcf39d6cd2dcde49b093ba5d1507ca478ec28dac/src/main/scala-3/net/ceedubs/ficus/util/EnumerationUtil.scala#L4-L8
+ * https://github.com/json4s/json4s/blob/5e0b92a0ca59769f3130e081d0f53089a4785130/ext/src/main/scala-3/org/json4s/ext/package.scala#L4-L8
+ * the maintainers of `json4s` already accepted a PR with a workaround at https://github.com/json4s/json4s/pull/1347
+* 1 library used to have 2 cases of the form `case HKExtractor[f] =>` with `type KHExtractor[f[_, _]] = Base { type Y[a, b] = f[a, b] }`.
+ * Those used to be at https://github.com/7mind/idealingua-v1/blob/48d35d53ce1c517f9f0d5341871e48749644c105/idealingua-v1/idealingua-v1-runtime-rpc-http4s/src/main/scala-3/izumi/idealingua/runtime/rpc/http4s/package.scala#L10-L15 but they do not exist in the latest version of the library.
+* 1 library used to have 1 `&`-type extractor (which "worked" who knows how?):
+ https://github.com/Katrix/perspective/blob/f1643ac7a4e6a0d8b43546bf7b9e6219cc680dde/dotty/derivation/src/main/scala/perspective/derivation/Helpers.scala#L15-L18
+ but the author already accepted a change with a workaround at
+ https://github.com/Katrix/perspective/pull/1
+* 1 library has 3 occurrences of using an abstract type constructor too "concretely":
+ https://github.com/kory33/s2mc-test/blob/d27c6e85ad292f8a96d7d51af7ddc87518915149/protocol-core/src/main/scala/io/github/kory33/s2mctest/core/generic/compiletime/Tuple.scala#L16
+ defined at https://github.com/kory33/s2mc-test/blob/d27c6e85ad292f8a96d7d51af7ddc87518915149/protocol-core/src/main/scala/io/github/kory33/s2mctest/core/generic/compiletime/Generic.scala#L12
+ It could be replaced by a concrete `class Lock[A](phantom: A)` instead.
+
+All the existing use cases therefore have either already disappeared or have a workaround.
+
+### Other concerns
+
+Ideally, this proposal would be first implemented as *warnings* about illegal cases, and only later made errors.
+Unfortunately, the presence of the abstract type constructor case makes that impossible.
+Indeed, because of it, a pattern that is legal at definition site may become illegal after some later substitution.
+
+Consider for example the standard library's very own `Tuple.InverseMap`:
+
+```scala
+/** Converts a tuple `(F[T1], ..., F[Tn])` to `(T1, ... Tn)` */
+type InverseMap[X <: Tuple, F[_]] <: Tuple = X match {
+ case F[x] *: t => x *: InverseMap[t, F]
+ case EmptyTuple => EmptyTuple
+}
+```
+
+If we instantiate `InverseMap` with a class type parameter, such as `InverseMap[X, List]`, the first case gets instantiated to
+```scala
+case List[x] *: t => x *: InverseMap[t, List]
+```
+which is legal.
+
+However, nothing prevents us a priori to instantiate `InverseMap` with an illegal type constructor, for example
+```scala
+type IsSeq[t <: Seq[Any]] = t
+InverseMap[X, IsSeq]
+```
+which gives
+```scala
+case IsSeq[x] *: t => x *: InverseMap[t, IsSeq]
+```
+
+These instantiatiations happen deep inside the type checker, during type computations.
+Since types are cached, shared and reused in several parts of the program, by construction, we do not have any source code position information at that point.
+That means that we cannot report *warnings*.
+
+We can in fact report *errors* by reducing to a so-called `ErrorType`, which is aggressively propagated.
+This is what we do in the proposed implementation (unless using `-source:3.3`).
+
+### Open questions
+
+None at this point.
+
+## Alternatives
+
+The specification is more complicated than we initially wanted.
+At the beginning, we were hoping that we could restrict match cases to class type constructors only.
+The quantitative study however revealed that we had to introduce support for abstract type constructors and for type member extractors.
+
+As already mentioned, the standard library itself contains an occurrence of an abstract type constructor in a pattern.
+If we made that an error, we would have a breaking change to the standard library itself.
+Some existing libraries would not be able to retypecheck again.
+Worse, it might not be possible for them to change their code in a way that preserves their own public APIs.
+
+We tried to restrict abstract type constructors to never match on their own.
+Instead, we wanted them to stay "stuck" until they could be instantiated to a concrete type constructor.
+However, that led some existing tests to fail even for match types that were declared legal, because they did not reduce anymore in some places where they reduced before.
+
+Type member extractors are our biggest pain point.
+Their specification is complicated, and the implementation as well.
+Our quantitative study showed that they were however used at least somewhat often (10 occurrences spread over 4 libraries).
+In each case, they seem to be a way to express what Scala 2 type projections (`A#T`) could express.
+While not quite as powerful as type projections (which were shown to be unsound), match types with type member extractors delay things enough for actual use cases to be meaningful.
+
+As far as we know, those use cases have no workaround if we make type member extractors illegal.
+
+## Related work
+
+Notable prior work related to this proposal includes:
+
+- [Current reference page for Scala 3 match types](https://dotty.epfl.ch/docs/reference/new-types/match-types.html)
+- [Abstractions for Type-Level Programming](https://infoscience.epfl.ch/record/294024), Olivier Blanvillain, Chapter 4 (Match Types)
+- ["Pre-Sip" discussion in the Contributors forum](https://contributors.scala-lang.org/t/pre-sip-proper-specification-for-match-types/6265) (submitted at the same time as this SIP document)
+- [PR with the proposed implementation](https://github.com/scala/scala3/pull/18262)
+
+## FAQ
+
+None at this point.
diff --git a/_sips/sips/2012-03-17-modularizing-language-features.md b/_sips/sips/modularizing-language-features.md
similarity index 86%
rename from _sips/sips/2012-03-17-modularizing-language-features.md
rename to _sips/sips/modularizing-language-features.md
index b3178ba83f..4de88d18be 100644
--- a/_sips/sips/2012-03-17-modularizing-language-features.md
+++ b/_sips/sips/modularizing-language-features.md
@@ -1,9 +1,8 @@
---
layout: sip
title: SIP-18 - Modularizing Language Features
-
-vote-status: complete
-vote-text: This SIP has already been accepted and completed. Let the record show Paul is against it.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/modularizing-language-features.html
---
diff --git a/_sips/sips/multi-source-extension-overloads.md b/_sips/sips/multi-source-extension-overloads.md
new file mode 100644
index 0000000000..fdcfd7050b
--- /dev/null
+++ b/_sips/sips/multi-source-extension-overloads.md
@@ -0,0 +1,233 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: completed
+status: shipped
+title: SIP-54 - Multi-Source Extension Overloads
+---
+
+**By: Sébastien Doeraene and Martin Odersky**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Mar 10th 2023 | Initial Draft |
+
+## Summary
+
+We propose to allow overload resolution of `extension` methods with the same name but imported from several sources.
+For example, given the following definitions:
+
+```scala
+class Foo
+class Bar
+
+object A:
+ extension (foo: Foo) def meth(): Foo = foo
+ def normalMeth(foo: Foo): Foo = foo
+
+object B:
+ extension (bar: Bar) def meth(): Bar = bar
+ def normalMeth(bar: Bar): Bar = bar
+```
+
+and the following use site:
+
+```scala
+import A.*
+import B.*
+
+val foo: Foo = ???
+foo.meth() // works with this SIP; "ambiguous import" without it
+
+// unchanged:
+meth(foo)() // always ambiguous, just like
+normalMeth(foo) // always ambiguous
+```
+
+## Motivation
+
+Extension methods are a great, straightforward way to extend external classes with additional methods.
+One classical example is to add a `/` operation to `Path`:
+
+```scala
+import java.nio.file.*
+
+object PathExtensions:
+ extension (path: Path)
+ def /(child: String): Path = path.resolve(child).nn
+
+def app1(): Unit =
+ import PathExtensions.*
+ val projectDir = Paths.get(".") / "project"
+```
+
+However, as currently specified, they do not compose, and effectively live in a single flat namespace.
+This is understandable from the spec--the *mechanism**, which says that they are just regular methods, but is problematic from an intuitive point of view--the *intent*.
+
+For example, if we also use another extension that provides `/` for `URI`s, we can use it in a separate scope as follows:
+
+```scala
+import java.net.URI
+
+object URIExtensions:
+ extension (uri: URI)
+ def /(child: String): URI = uri.resolve(child)
+
+def app2(): Unit =
+ import URIExtensions.*
+ val rootURI = new URI("https://www.example.com/")
+ val projectURI = rootURI / "project/"
+```
+
+The above does not work anymore if we need to use *both* extensions in the same scope.
+The code below does not compile:
+
+```scala
+def app(): Unit =
+ import PathExtensions.*
+ import URIExtensions.*
+
+ val projectDir = Paths.get(".") / "project"
+ val rootURI = new URI("https://www.example.com/")
+ val projectURI = rootURI / "project/"
+ println(s"$projectDir -> $projectURI")
+end app
+```
+
+*Both* attempts to use `/` result in error messages of the form
+
+```
+Reference to / is ambiguous,
+it is both imported by import PathExtensions._
+and imported subsequently by import URIExtensions._
+```
+
+### Workarounds
+
+The only workarounds that exist are unsatisfactory.
+
+We can avoid using extensions with the same name in the same scope.
+In the above example, that would be annoying enough to defeat the purpose of the extensions in the first place.
+
+Another possibility is to *define* all extension methods of the same name in the same `object` (or as top-level definitions in the same file).
+This is possible, although cumbersome, if they all come from the same library.
+However, it is impossible to combine extension methods coming from separate libraries in this way.
+
+Finally, there exists a trick with `given`s of empty refinements:
+
+```scala
+object PathExtensions:
+ given pathExtensions: {} with
+ extension (path: Path)
+ def /(child: String): Path = path.resolve(child).nn
+
+object URIExtensions:
+ given uriExtensions: {} with
+ extension (uri: URI)
+ def /(child: String): URI = uri.resolve(child)
+```
+
+The empty refinement `: {}` prevents those `given`s from polluting the actual implicit scope.
+`extension`s defined inside `given`s that are in scope can be used, so this trick allows to use `/` with the imports of `PathExtensions.*` and `URIExtensions.*`.
+The `given`s must still have different names for the trick to work.
+This workaround is however quite obscure.
+It hides intent behind a layer of magic (and an additional indirection at run-time).
+
+### Problem for migrating off of implicit classes
+
+Scala 2 implicit classes did not suffer from the above issues, because they were disambiguated by the name of the implicit class (not the name of the method).
+This means that there are libraries that cannot migrate off of implicit classes to use `extension` methods without significantly degrading their usability.
+
+## Proposed solution
+
+We propose to relax the resolution of extension methods, so that they can be resolved from multiple imported sources.
+Instead of rejecting the `/` call outright because of ambiguous imports, the compiler should try the resolution from all the imports, and keep the only one (if any) for which the receiver type matches.
+
+Practically speaking, this means that the above `app()` example would compile and behave as expected.
+
+### Non-goals
+
+It is *not* a goal of this proposal to allow resolution of arbitrary overloads of regular methods coming from multiple imports.
+Only `extension` method calls are concerned by this proposal.
+The complexity budget of relaxing *all* overloads in this way is deemed too high, whereas it is acceptable for `extension` method calls.
+
+For the same reason, we do not propose to change regular calls of methods that happen to be `extension` methods.
+
+### Specification
+
+We make two changes to the [specification of extension methods](https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html).
+
+In the section [Translation of Extension Methods](https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html#translation-of-extension-methods), we make it clearer that the "desugared" version of the call site may require an explicit qualifier.
+This is not strictly a novelty of this SIP, since it could already happen with `given`s and implicit scopes, but this SIP adds one more case where this can happen.
+
+Previously:
+
+> So, the definition of circumference above translates to the following method, and can also be invoked as such:
+>
+> ` def circumference(c: Circle): Double = c.radius * math.Pi * 2`
+>
+> `assert(circle.circumference == circumference(circle))`
+
+With this SIP:
+
+> So, the definition of circumference above translates to the following method, and can also be invoked as such:
+>
+> ` def circumference(c: Circle): Double = c.radius * math.Pi * 2`
+>
+> `assert(circle.circumference == circumference(circle))`
+>
+> or
+>
+> `assert(circle.circumference == qualifierPath.circumference(circle))`
+>
+> for some `qualifierPath` in which `circumference` is actually declared.
+> Explicit qualifiers may be required when the extension method is resolved through `given` instances, implicit scopes, or disambiguated from several imports.
+
+---
+
+In the section [Translation of Calls to Extension Methods](https://docs.scala-lang.org/scala3/reference/contextual/extension-methods.html#translation-of-calls-to-extension-methods), we amend step 1. of "The precise rules for resolving a selection to an extension method are as follows."
+
+Previously:
+
+> Assume a selection `e.m[Ts]` where `m` is not a member of `e`, where the type arguments `[Ts]` are optional, and where `T` is the expected type.
+> The following two rewritings are tried in order:
+>
+> 1. The selection is rewritten to `m[Ts](e)`.
+
+With this SIP:
+
+> 1. The selection is rewritten to `m[Ts](e)` and typechecked, using the following slight modification of the name resolution rules:
+>
+> - If `m` is imported by several imports which are all on the same nesting level, try each import as an extension method instead of failing with an ambiguity.
+> If only one import leads to an expansion that typechecks without errors, pick that expansion.
+> If there are several such imports, but only one import which is not a wildcard import, pick the expansion from that import.
+> Otherwise, report an ambiguous reference error.
+
+### Compatibility
+
+The proposal only alters situations where the previous specification would reject the program with an ambiguous import.
+Therefore, we expect it to be backward source compatible.
+
+The resolved calls could previously be spelled out by hand (with fully-qualified names), so binary compatibility and TASTy compatibility are not affected.
+
+### Other concerns
+
+With this SIP, some calls that would be reported as *ambiguous* in their "normal" form can actually be written without ambiguity if used as extensions.
+That may be confusing to some users.
+Although specific error messages are not specified and therefore outside the SIP scope, we encourage the compiler implementation to enhance the "ambiguous" error message to address this confusion.
+If some or all of the involved ambiguous targets are `extension` methods, the compiler should point out that the call might be resolved unambiguously if used as an extension.
+
+## Alternatives
+
+A number of alternatives were mentioned in [the Contributors thread](https://contributors.scala-lang.org/t/change-shadowing-mechanism-of-extension-methods-for-on-par-implicit-class-behavior/5831), but none that passed the bar of "we think this is actually implementable".
+
+## Related work
+
+- [Contributors thread acting as de facto Pre-SIP](https://contributors.scala-lang.org/t/change-shadowing-mechanism-of-extension-methods-for-on-par-implicit-class-behavior/5831)
+- [Pull Request in dotty](https://github.com/scala/scala3/pull/17050) to support it under an experimental import
+
+## FAQ
+
+This section will probably initially be empty. As discussions on the proposal progress, it is likely that some questions will come repeatedly. They should be listed here, with appropriate answers.
diff --git a/_sips/sips/multiple-assignments.md b/_sips/sips/multiple-assignments.md
new file mode 100644
index 0000000000..b55044b7d9
--- /dev/null
+++ b/_sips/sips/multiple-assignments.md
@@ -0,0 +1,331 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: implementation
+status: under-review
+presip-thread: https://contributors.scala-lang.org/t/pre-sip-multiple-assignments/6425
+title: SIP-59 - Multiple Assignments
+---
+
+**By: Dimi Racordon**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Jan 17th 2024 | Initial Draft |
+
+## Summary
+
+This proposal discusses the syntax and semantics of a construct to assign multiple variables with a single expression.
+This feature would simplify the implementation of operations expressed in terms of relationships between multiple variables, such as [`std::swap`](https://en.cppreference.com/w/cpp/algorithm/swap) in C++.
+
+## Motivation
+
+It happens that one has to assign multiple variables "at once" in an algorithm.
+For example, let's consider the Fibonacci sequence:
+
+```scala
+class FibonacciIterator() extends Iterator[Int]:
+
+ private var a: Int = 0
+ private var b: Int = 1
+
+ def hasNext = true
+ def next() =
+ val r = a
+ val n = a + b
+ a = b
+ b = n
+ r
+```
+
+The same iterator could be rewritten more concisely if we could assign multiple variables at once.
+For example, we can write the following in Swift:
+
+```swift
+struct FibonacciIterator: IteratorProtocol {
+
+ private var a: Int = 0
+ private var b: Int = 1
+ init() {}
+
+ mutating func next() -> Int? {
+ defer { (a, b) = (b, a + b) }
+ return a
+ }
+
+}
+```
+
+Though the differences may seem frivolous at first glance, they are in fact important.
+If we look at a formal definition of the Fibonacci sequence (e.g., on [Wikipedia](https://en.wikipedia.org/wiki/Fibonacci_sequence)), we might see something like:
+
+> The Fibonacci sequence is given by *F(n) = F(n-1) + F(n+1)* where *F(0) = 0* and *F(1) = 1*.
+
+Although this declarative description says nothing about an evaluation order, it becomes a concern in our Scala implementation as we must encode the relationship into multiple operational steps.
+This decomposition offers opportunities to get things wrong:
+
+```scala
+def next() =
+ val r = a
+ a = b
+ b = a + b // invalid semantics, the value of `a` changed "too early"
+ r
+```
+
+In contrast, our Swift implementation can remain closer to the formal definition and is therefore more legible and less error-prone.
+
+Multiple assignments show up in many general-purpose algorithms (e.g., insertion sort, partition, min-max element, ...).
+But perhaps the most fundamental one is `swap`, which consists of exchanging two values.
+
+We often swap values that are stored in some collection.
+In this particular case, all is well in Scala because we can ask the collection to swap elements at given positions:
+
+```scala
+extension [T](self: mutable.ArrayBuffer[T])
+ def swapAt(i: Int, j: Int) =
+ val t = self(i)
+ self(i) = self(j)
+ self(j) = t
+
+val a = mutable.ArrayBuffer(1, 2, 3)
+a.swapAt(0, 2)
+println(a) // ArrayBuffer(3, 2, 1)
+```
+
+Sadly, one can't implement a generic swap method that wouldn't rely on the ability to index a container.
+The only way to express this operation in Scala is to "inline" the pattern implemented by `swapAt` every time we need to swap two values.
+
+Having to rewrite this boilerplate is unfortunate.
+Here is an example in a realistic algorithm:
+
+```scala
+extension [T](self: Seq[T])(using Ordering[T])
+ def minMaxElements: Option[(T, T)] =
+ import math.Ordering.Implicits.infixOrderingOps
+
+ // Return None for collections smaller than 2 elements.
+ var i = self.iterator
+ if (!i.hasNext) { return None }
+ var l = i.next()
+ if (!i.hasNext) { return None }
+ var h = i.next()
+
+ // Confirm the initial bounds.
+ if (h < l) { val t = l; l = h; h = l }
+
+ // Process the remaining elements.
+ def loop(): Option[(T, T)] =
+ if (i.hasNext) {
+ val n = i.next()
+ if (n < l) { l = n } else if (n > h) { h = n }
+ loop()
+ } else {
+ Some((l, h))
+ }
+ loop()
+```
+
+*Note: implementation shamelessly copied from [swift-algorithms](https://github.com/apple/swift-algorithms/blob/main/Sources/Algorithms/MinMax.swift).*
+
+The swap occurs in the middle of the method with the sequence of expressions `val t = l; l = h; h = l`.
+To borrow from the words of Edgar Dijskstra [1, Chapter 11]:
+
+> [that] is combersome and ugly compared with the [multiple] assignment.
+
+While `swap` is a very common operation, it's only an instance of a more general class of operations that are expressed in terms of relationships between multiple variables.
+The definition of the Fibonacci sequence is another example.
+
+## Proposed solution
+
+The proposed solution is to add a language construct to assign multiple variables in a single expression.
+Using this construct, swapping two values can be written as follows:
+
+```scala
+var a = 2
+var b = 4
+(a, b) = (b, a)
+println(s"$a$b") // 42
+```
+
+The above Fibonacci iterator can be rewritten as follows:
+
+```scala
+class FibonacciIterator() extends Iterator[Int]:
+
+ private var a: Int = 0
+ private var b: Int = 1
+
+ def hasNext = true
+ def next() =
+ val r = a
+ (a, b) = (b, a + b)
+ r
+```
+
+Multiple assignments also alleviate the need for a swap method on collections, as the same idiomatic pattern can be reused to exchange elements at given indices:
+
+```scala
+val a = mutable.ArrayBuffer(1, 2, 3)
+(a(0), a(2)) = (a(2), a(0))
+println(a) // ArrayBuffer(3, 2, 1)
+```
+
+### Specification
+
+A multiple assignment is an expression of the form `AssignTarget ‘=’ Expr` where:
+
+```
+AssignTarget ::= ‘(’ AssignTargetNode {‘,’ AssignTargetNode} ‘)’
+AssignTargetNode ::= Expr | AssignTarget
+```
+
+An assignment target describes a structural pattern that can only be matched by a compatible composition of tuples.
+For example, the following program is legal.
+
+```scala
+def f: (Boolean, Int) = (true, 42)
+val a = mutable.ArrayBuffer(1, 2, 3)
+def b = a
+var x = false
+
+(x, a(0)) = (false, 1337)
+(x, a(1)) = f
+((x, a(1)), b(2)) = (f, 9000)
+(x) = Tuple1(false)
+```
+
+A mismatch between the structure of a multiple assignment's target and the result of its RHS is a type error.
+It cannot be detected during parsing because at this stage the compiler would not be able to determine the shape of an arbitrary expression's result.
+For example, all multiple assignments in the following program are ill-typed:
+
+```scala
+def f: (Boolean, Int) = (true, 42)
+val a = mutable.ArrayBuffer(1, 2, 3)
+def b = a
+var x = false
+
+(a(1), x) = f // type mismatch
+(x, a(1), b(2)) = (f, 9000) // structural mismatch
+(x) = false // structural mismatch
+(x) = (1, 2) // structural mismatch
+```
+
+Likewise, `(x) = Tuple1(false)` is _not_ equivalent to `x = Tuple1(false)`.
+The former is a multiple assignment while the latter is a regular assignment, as described by the [current grammar](https://docs.scala-lang.org/scala3/reference/syntax.html) (see `Expr1`).
+Though this distinction is subtle, multiple assignments involving unary tuples should be rare.
+
+The operational semantics of multiple assignments (aka concurrent assignments) have been studied extensively in scienific literature (e.g., [1, 2]).
+A first intuition is that the most desirable semantics can be achieved by fully evaluating the RHS of the assignment before assigning any expression in the LHS [1].
+However, additional considerations must be given w.r.t. the independence of the variables on the LHS to guarantee deterministic results.
+For example, consider the following expression:
+
+```scala
+(x, x) = (1, 2)
+```
+
+While one may conclude that such an expression should be an error [1], it is in general difficult to guarantee value independence in a language with pervasive reference semantics.
+Further, it is desirable to write expressions of the form `(a(0), a(2)) = (a(2), a(0))`, as shown in the previous section.
+Another complication is that multiple assignments should uphold the general left-to-right evaluation semantics of the Scala language.
+For example, `a.b = c` requires `a` to be evaluated _before_ `c`.
+
+Note that regular assignments desugar to function calls (e.g., `a(b) = c` is sugar for `a.update(b, c)`).
+One property of these desugarings is always the last expression being evaluated before the method performing the assignment is called.
+Given this observation, we address the abovementioned issues by defining the following algorithm:
+
+1. Traverse the LHS structure in inorder and for each leaf:
+ - Evaluate each outermost subexpression to its value
+ - Form a closure capturing these values and accepting a single argument to perform the desugared assignment
+ - Associate that closure to the leaf
+2. Compute the value of the RHS, which forms a tree
+3. Traverse the LHS and RHS structures pairwise in inorder and for each leaf:
+ - Apply the closure formerly associated to the LHS on RHS value
+
+For instance, consider the following definitions.
+
+```scala
+def f: (Boolean, Int) = (true, 42)
+val a = mutable.ArrayBuffer(1, 2, 3)
+def b = a
+var x = false
+```
+
+The evaluation of the expression `((x, a(a(0))), b(2)) = (f, 9000)` is as follows:
+
+1. form a closure `f0 = (rhs) => x_=(rhs)`
+2. evaluate `a(0)`; result is `1`
+3. form a closure `f1 = (rhs) => a.update(1, rhs)`
+4. evaluate `b`; result is `a`
+5. evaluate `2`
+6. form a closure `f2 = (rhs) => a.update(2, rhs)`
+7. evaluate `(f, 9000)`; result is `((true, 42), 9000)`
+8. evaluate `f0(true)`
+9. evaluate `f1(42)`
+10. evaluate `f2(9000)`
+
+After the assignment, `x == true` and `a == List(1, 42, 9000)`.
+
+The compiler is allowed to ignore this procedure and generate different code for optimization purposes as long as it can guarantee that such a change is not observable.
+For example, given two local variables `x` and `y`, their assignments in `(x, y) = (1, 2)` can be reordered or even performed in parallel.
+
+### Compatibility
+
+This proposal is purely additive and have no backward binary or TASTy compatibility consequences.
+The semantics of the proposed new construct is fully expressible in terms of desugaring into current syntax, interpreteted with current semantics.
+
+The proposed syntax is not currently legal Scala.
+Therefore no currently existing program could be interpreted with different semantics using a newer compiler version supporting multiple assignments.
+
+### Other concerns
+
+One understandable concern of the proposed syntax is that the semantics of multiple assignments resembles that of pattern matching, yet it has different semantics.
+For example:
+
+```scala
+val (a(x), b) = (true, "!") // 1
+
+(a(x), b) = (true, "!") // 2
+```
+
+If `a` is instance of a type with a companion extractor object, the two lines above have completely different semantics.
+The first declares two local bindings `x` and `b`, applying pattern matching to determine their value from the tuple `(true, "!")`.
+The second is assigning `a(x)` and `b` to the values `true` and `"!"`, respectively.
+
+Though possibly surprising, the difference in behavior is easy to explain.
+The first line applies pattern matching because it starts with `val`.
+The second doesn't because it involves no pattern matching introducer.
+Further, note that a similar situation can already be reproduced in current Scala:
+
+```scala
+val a(x) = true // 1
+
+a(x) = true // 2
+```
+
+## Alternatives
+
+The current proposal supports arbitrary tree structures on the LHS of the assignment.
+A simpler alternative would be to only support flat sequences, allowing the syntax to dispense with parentheses.
+
+```scala
+a, b = b, a
+```
+
+While this approach is more lightweight, the reduced expressiveness inhibits potentially interesting use cases.
+Further, consistently using tuple syntax on both sides of the equality operator clearly distinguishes regular and multiple assignments.
+
+## Related work
+
+A Pre-SIP discussion took place prior to this proposal (see [here](https://contributors.scala-lang.org/t/pre-sip-multiple-assignments/6425/1)).
+
+Multiple assignments are present in many contemporary languages.
+This proposal already illustrated them in Swift, but they are also commonly used in Python.
+Multiple assigments have also been studied extensively in scienific literature (e.g., [1, 2]).
+
+## FAQ
+
+## References
+
+1. Edsger W. Dijkstra: A Discipline of Programming. Prentice-Hall 1976, ISBN 013215871X
+2. Ralph-Johan Back, Joakim von Wright: Refinement Calculus - A Systematic Introduction. Graduate Texts in Computer Science, Springer 1998, ISBN 978-0-387-98417-9
diff --git a/_sips/sips/name-based-xml-literals.md b/_sips/sips/name-based-xml-literals.md
new file mode 100644
index 0000000000..1b3e699b01
--- /dev/null
+++ b/_sips/sips/name-based-xml-literals.md
@@ -0,0 +1,6 @@
+---
+title: SIP-40 - Name Based XML Literals
+status: rejected
+pull-request-number: 42
+
+---
diff --git a/_sips/sips/2010-01-22-named-and-default-arguments.md b/_sips/sips/named-and-default-arguments.md
similarity index 99%
rename from _sips/sips/2010-01-22-named-and-default-arguments.md
rename to _sips/sips/named-and-default-arguments.md
index 6b8fb55dd4..3d56605ad7 100644
--- a/_sips/sips/2010-01-22-named-and-default-arguments.md
+++ b/_sips/sips/named-and-default-arguments.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-1 Named and Default Arguments
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/named-and-default-arguments.html
---
diff --git a/_sips/sips/named-tuples.md b/_sips/sips/named-tuples.md
new file mode 100644
index 0000000000..431107cd14
--- /dev/null
+++ b/_sips/sips/named-tuples.md
@@ -0,0 +1,777 @@
+---
+layout: sip
+permalink: /sips/named-tuples.html
+stage: completed
+status: shipped
+presip-thread: https://contributors.scala-lang.org/t/pre-sip-named-tuples/6403/164
+title: SIP-58 - Named Tuples
+---
+
+**By: Martin Odersky**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Jan 13th 2024 | Initial Draft |
+
+## Summary
+
+We propose to add new form of tuples where the elements are named.
+Named tuples can be types, terms, or patterns. Syntax examples:
+```scala
+type Person = (name: String, age: Int)
+val Bob: Person = (name = "Bob", age = 33)
+
+Bob match
+ case (name = n, age = 22) => ...
+```
+
+We also propose to revive SIP 43 to support patterns with named fields. Named pattern fields for case classes are analogous to named patterns for tuple elements. User-defined named pattern matching is supported since named tuples can be results of extractor methods.
+
+## Motivation
+
+ 1. Named tuples are a convenient lightweight way to return multiple results from a function. But the absence of names obscures their meaning, and makes decomposition with _1, _2 ugly and hard to read. The existing alternative is to define a class instead. This does name fields, but is more heavy-weight, both in terms of notation and generated bytecode. Named tuples give the same convenience of definition as regular tuples at far better readability.
+
+ 1. Named tuples are an almost ideal substrate on which to implement relational algebra and other database oriented operations. They are a good representation of database rows and allow the definition of generic operations such as projections and joins since they can draw on Scala 3’s existing generic machinery for tuples based on match types.
+
+ 1. Named tuples make named pattern matching trivial to implement. The discussion on SIP 43 showed that without them it’s unclear how to implement named pattern matching at all.
+
+## Proposed solution
+
+The elements of a tuple can now be named. Example:
+```scala
+type Person = (name: String, age: Int)
+val Bob: Person = (name = "Bob", age = 33)
+
+Bob match
+ case (name, age) =>
+ println(s"$name is $age years old")
+
+val persons: List[Person] = ...
+val minors = persons.filter: p =>
+ p.age < 18
+```
+Named bindings in tuples are similar to function parameters and arguments. We use `name: Type` for element types and `name = value` for element values. It is illegal to mix named and unnamed elements in a tuple, or to use the same same
+name for two different elements.
+
+Fields of named tuples can be selected by their name, as in the line `p.age < 18` above.
+
+Example:
+
+~~~ scala
+// This is an @main method
+@main def foo(x: Int): Unit =
+ println(x)
+~~~
+
+### Conformance and Convertibility
+
+The order of names in a named tuple matters. For instance, the type `Person` above and the type `(age: Int, name: String)` would be different, incompatible types.
+
+Values of named tuple types can also be be defined using regular tuples. For instance:
+```scala
+val Laura: Person = ("Laura", 25)
+
+def register(person: Person) = ...
+register(person = ("Silvain", 16))
+register(("Silvain", 16))
+```
+This follows since a regular tuple `(T_1, ..., T_n)` is treated as a subtype of a named tuple `(N_1 = T_1, ..., N_n = T_n)` with the same element types.
+
+In the other direction, one can convert a named tuple to an unnamed tuple with the `toTuple` method. Example:
+```scala
+val x: (String, Int) = Bob.toTuple // ok
+```
+`toTuple` is defined as an extension method in the `NamedTuple` object.
+It returns the given tuple unchanged and simply "forgets" the names.
+
+A `.toTuple` selection is inserted implicitly by the compiler if it encounters a named tuple but the expected type is a regular tuple. So the following works as well:
+```scala
+val x: (String, Int) = Bob // works, expanded to Bob.toTuple
+```
+The difference between subtyping in one direction and automatic `.toTuple` conversions in the other is relatively minor. The main difference is that `.toTuple` conversions don't work inside type constructors. So the following is OK:
+```scala
+ val names = List("Laura", "Silvain")
+ val ages = List(25, 16)
+ val persons: List[Person] = names.zip(ages)
+```
+But the following would be illegal.
+```scala
+ val persons: List[Person] = List(Bob, Laura)
+ val pairs: List[(String, Int)] = persons // error
+```
+We would need an explicit `_.toTuple` selection to express this:
+```scala
+ val pairs: List[(String, Int)] = persons.map(_.toTuple)
+```
+Note that conformance rules for named tuples are analogous to the rules for named parameters. One can assign parameters by position to a named parameter list.
+```scala
+ def f(param: Int) = ...
+ f(param = 1) // OK
+ f(2) // Also OK
+```
+But one cannot use a name to pass an argument to an unnamed parameter:
+```scala
+ val f: Int => T
+ f(2) // OK
+ f(param = 2) // Not OK
+```
+The rules for tuples are analogous. Unnamed tuples conform to named tuple types, but the opposite requires a conversion.
+
+### Pattern Matching
+
+When pattern matching on a named tuple, the pattern may be named or unnamed.
+If the pattern is named it needs to mention only a subset of the tuple names, and these names can come in any order. So the following are all OK:
+```scala
+Bob match
+ case (name, age) => ...
+
+Bob match
+ case (name = x, age = y) => ...
+
+Bob match
+ case (age = x) => ...
+
+Bob match
+ case (age = x, name = y) => ...
+```
+
+### Expansion
+
+Named tuples are in essence just a convenient syntax for regular tuples. In the internal representation, a named tuple type is represented at compile time as a pair of two tuples. One tuple contains the names as literal constant string types, the other contains the element types. The runtime representation of a named tuples consists of just the element values, whereas the names are forgotten. This is achieved by declaring `NamedTuple`
+in package `scala` as an opaque type as follows:
+```scala
+ opaque type NamedTuple[N <: Tuple, +V <: Tuple] >: V = V
+```
+For instance, the `Person` type would be represented as the type
+```scala
+NamedTuple[("name", "age"), (String, Int)]
+```
+`NamedTuple` is an opaque type alias of its second, value parameter. The first parameter is a string constant type which determines the name of the element. Since the type is just an alias of its value part, names are erased at runtime, and named tuples and regular tuples have the same representation.
+
+A `NamedTuple[N, V]` type is publicly known to be a supertype (but not a subtype) of its value paramater `V`, which means that regular tuples can be assigned to named tuples but not _vice versa_.
+
+The `NamedTuple` object contains a number of extension methods for named tuples hat mirror the same functions in `Tuple`. Examples are
+`apply`, `head`, `tail`, `take`, `drop`, `++`, `map`, or `zip`.
+Similar to `Tuple`, the `NamedTuple` object also contains types such as `Elem`, `Head`, `Concat`
+that describe the results of these extension methods.
+
+The translation of named tuples to instances of `NamedTuple` is fixed by the specification and therefore known to the programmer. This means that:
+
+ - All tuple operations also work with named tuples "out of the box".
+ - Macro libraries can rely on this expansion.
+
+### Computed Field Names
+
+The `Selectable` trait now has a `Fields` type member that can be instantiated
+to a named tuple.
+
+```scala
+trait Selectable:
+ type Fields <: NamedTuple.AnyNamedTuple
+```
+
+If `Fields` is instantiated in a subclass of `Selectable` to some named tuple type,
+then the available fields and their types will be defined by that type. Assume `n: T`
+is an element of the `Fields` type in some class `C` that implements `Selectable`,
+that `c: C`, and that `n` is not otherwise legal as a name of a selection on `c`.
+Then `c.n` is a legal selection, which expands to `c.selectDynamic("n").asInstanceOf[T]`.
+
+It is the task of the implementation of `selectDynamic` in `C` to ensure that its
+computed result conforms to the predicted type `T`
+
+As an example, assume we have a query type `Q[T]` defined as follows:
+
+```scala
+trait Q[T] extends Selectable:
+ type Fields = NamedTuple.Map[NamedTuple.From[T], Q]
+ def selectDynamic(fieldName: String) = ...
+```
+
+Assume in the user domain:
+```scala
+case class City(zipCode: Int, name: String, population: Int)
+val city: Q[City]
+```
+Then
+```scala
+city.zipCode
+```
+has type `Q[Int]` and it expands to
+```scala
+city.selectDynamic("zipCode").asInstanceOf[Q[Int]]
+```
+
+### The NamedTuple.From Type
+
+The `NamedTuple` object contains a type definition
+```scala
+ type From[T] <: AnyNamedTuple
+```
+`From` is treated specially by the compiler. When `NamedTuple.From` is applied to
+an argument type that is an instance of a case class, the type expands to the named
+tuple consisting of all the fields of that case class.
+Here, _fields_ means: elements of the first parameter section. For instance, assuming
+```scala
+case class City(zip: Int, name: String, population: Int)
+```
+then `NamedTuple.From[City]` is the named tuple
+```scala
+(zip: Int, name: String, population: Int)
+```
+The same works for enum cases expanding to case classes, abstract types with case classes as upper bound, alias types expanding to case classes
+and singleton types with case classes as underlying type (in terms of the implementation, the `classSymbol` of a type must be a case class).
+
+`From` is also defined on named tuples. If `NT` is a named tuple type, then `From[NT] = NT`.
+
+### Pattern Matching with Named Fields in General
+
+We allow named patterns not just for named tuples but also for case classes. For instance:
+```scala
+city match
+ case c @ City(name = "London") => println(c.population)
+ case City(name = n, zip = 1026, population = pop) => println(pop)
+```
+
+Named constructor patterns are analogous to named tuple patterns. In both cases
+
+ - every name must match the name some field of the selector,
+ - names can come in any order,
+ - not all fields of the selector need to be matched.
+
+This revives SIP 43, with a much simpler desugaring than originally proposed.
+Named patterns are compatible with extensible pattern matching simply because
+`unapply` results can be named tuples.
+
+### Operations on Named Tuples
+
+The operations on named tuples are defined in object `scala.NamedTuple`. The current version of this object is listed in Appendix A.
+
+### Restrictions
+
+The following restrictions apply to named tuples and named pattern arguments:
+
+ 1. Either all elements of a tuple or constructor pattern are named or none are named. It is illegal to mix named and unnamed elements in a tuple. For instance, the following is in error:
+ ```scala
+ val illFormed1 = ("Bob", age = 33) // error
+ ```
+ 2. Each element name in a named tuple or constructor pattern must be unique. For instance, the following is in error:
+ ```scala
+ val illFormed2 = (name = "", age = 0, name = true) // error
+ ```
+ 3. Named tuples and case classes can be matched with either named or regular patterns. But regular tuples and other selector types can only be matched with regular tuple patterns. For instance, the following is in error:
+ ```scala
+ (tuple: Tuple) match
+ case (age = x) => // error
+ ```
+
+### Use Case
+
+As a a use case showing some advanced capabilities of named tuples (including computed field names and the `From` type),
+we show an implementation of embedded queries in Scala. For expressions that look like working with collections are instead
+used to directly generate a query AST that can be further optimized and mapped to a variety of query languages. The code
+is given in Appendix B.
+
+### Syntax Changes
+
+The syntax of Scala is extended as follows to support named tuples and
+named constructor arguments:
+```
+SimpleType ::= ...
+ | ‘(’ NameAndType {‘,’ NameAndType} ‘)’
+NameAndType ::= id ':' Type
+
+SimpleExpr ::= ...
+ | '(' NamedExprInParens {‘,’ NamedExprInParens} ')'
+NamedExprInParens ::= id '=' ExprInParens
+
+Patterns ::= Pattern {‘,’ Pattern}
+ | NamedPattern {‘,’ NamedPattern}
+NamedPattern ::= id '=' Pattern
+```
+
+### Compatibility
+
+Named tuple types and expressions are simply desugared to types and trees already known to Scala. The desugaring happens before the checking, so does not influence Tasty generation.
+
+Pattern matching with named fields requires some small additions to Typer and the PatternMatcher phase. It does not change the Tasty format, though.
+
+Backward source compatibility is partially preserved since additions to types and patterns come with new syntax that was not expressible before. When looking at tuple expressions, we have two instances of a source incompatibility:
+
+```scala
+var age: Int
+(age = 1)
+```
+This was an assignment in parentheses before, and is a named tuple of arity one now. It is however not idiomatic Scala code, since assignments are not usually enclosed in parentheses.
+
+Also, if we have
+```scala
+class C:
+ infix def f(age: Int)
+val c: C
+```
+then
+```scala
+c f (age = 1)
+```
+will now construct a tuple as second operand instead of passing a named parameter.
+
+These problems can be detected and diagnosed fairly straightforwardly: When faced with a unary named tuple, try to interpret it as an assignment, and if that succeeds, issue a migration error and suggest a workaround of these kinds:
+```scala
+ {age = 1} // ok
+ c.f(age = 1) // ok
+```
+
+### Open questions
+
+ 1. What is the precise set of types and operations we want to add to `NamedTuple`. This could also evolve after this SIP is completed.
+
+ 2. Should there be an implicit conversion from named tuples to ordinary tuples?
+
+## Alternatives
+
+### Structural Types
+
+We also considered to expand structural types. Structural types allow to abstract over existing classes, but require reflection or some other library-provided mechanism for element access. By contrast, named tuples have a separate representation as tuples, which can be manipulated directly. Since elements are ordered, traversals can be defined, and this allows the definition of type generic algorithms over named tuples. Structural types don’t allow such generic algorithms directly. Be could define mappings between structural types and named tuples, which could be used to implement such algorithms. These mappings would certainly become simpler if they map to/from named tuples than if they had to map to/from user-defined "HMap"s.
+
+By contrast to named tuples, structural types are unordered and have width subtyping. This comes with the price that no natural element ordering exist, and that one usually needs some kind of dictionary structure for access. We believe that the following advantages of named tuples over structural types outweigh the loss of subtyping flexibility:
+
+ - Better integration since named tuples and normal tuples share the same representation.
+ - Better efficiency, since no dictionary is needed.
+ - Natural traversal order allows the formulation of generic algorithms such as projections and joins.
+
+### Conformance
+
+A large part of Pre-SIP discussion centered around subtyping rules, whether ordinary tuples should subtype named-tuples (as in this proposal) or _vice versa_ or maybe no subtyping at all.
+
+Looking at precedent in other languages it feels like we we do want some sort of subtyping for easy convertibility and an implicit conversion in the other direction. This proposal picks _unnamed_ <: _named_ for the subtyping and _named_ -> _unnamed_ for the conversion.
+
+The discussion established that both forms of subtyping are sound. My personal opinion is that the subtyping of this proposal is both more useful and safer than the one in the other direction. There is also the problem that changing the subtyping direction would be incompatible with the current structure of `Tuple` and `NamedTuple` since for instance `zip` is already an inline method on `Tuple` so it could not be overridden in `NamedTuple`. To make this work requires a refactoring of `Tuple` to use more extension methods, and the questions whether this is feasible and whether it can be made binary backwards compatible are unknown. I personally will not work on this, if others are willing to make the effort we can discuss the alternative subtyping as well.
+
+_Addendum:_ Turning things around, adopting _named_ <: _unnamed_ for the subtyping and `_unnamed_ -> _named_ for the conversion leads to weaker typing with undetected errors. Consider:
+```scala
+type Person = (name: String, age: Int)
+val bob: Person
+bob.zip((firstName: String, agee: Int))
+```
+This should report a type error.
+But in the alternative scheme, we'd have `(firstName: String, agee: Int) <: (String, Int)` by subtyping and then
+`(String, Int) -> (name: String, age: Int)` by implicit naming conversion. This is clearly not what we want.
+
+By contrast, in the implemented scheme, we will not convert `(firstName: String, agee: Int)` to `(String, Int)` since a conversion is only attempted if the expected type is a regular tuple, and in our scenario it is a named tuple instead.
+
+My takeaway is that these designs have rather subtle consequences and any alterations would need a full implementation before they can be judged. For instance, the situation with `zip` was a surprise to me, which came up since I first implemented `_.toTuple` as a regular implicit conversion instead of a compiler adaptation.
+
+A possibly simpler design would be to drop all conformance and conversion rules. The problem with this approach is worse usability and problems with smooth migration. Migration will be an issue since right now everything is a regular tuple. If we make it hard to go from there to named tuples, everything will tend to stay a regular tuple and named tuples will be much less used than we would hope for.
+
+
+### Spread Operator
+
+An idea I was thinking of but that I did not include in this proposal highlights another potential problem with subtyping. Consider adding a _spread_ operator `*` for tuples and named tuples. if `x` is a tuple then `f(x*)` is `f` applied to all fields of `x` expanded as individual arguments. Likewise, if `y` is a named tuple, then `f(y*)` is `f` applied to all elements of `y` as named arguments.
+Now, if named tuples would be subtypes of tuples, this would actually be ambiguous since widening `y` in `y*` to a regular tuple would yield a different call. But with the subtyping direction we have, this would work fine.
+
+I believe tuple spread is a potentially useful addition that would fit in well with Scala. But it's not immediately relevant to this proposal, so is left out for now.
+
+
+## Related work
+
+This section should list prior work related to the proposal, notably:
+
+- [Pre-SIP Discussion](https://contributors.scala-lang.org/t/pre-sip-named-tuples/6403)
+
+- [SIP 43 on Pattern Matching with Named Fields](https://github.com/scala/improvement-proposals/pull/44)
+
+- [Experimental Implementation](https://github.com/scala/scala3/pull/19174)
+
+## FAQ
+
+## Appendix A: NamedTuple Definition
+
+Here is the current definition of `NamedTuple`. This is part of the library and therefore subject to future changes and additions.
+
+```scala
+package scala
+import annotation.experimental
+import compiletime.ops.boolean.*
+
+@experimental
+object NamedTuple:
+
+ opaque type AnyNamedTuple = Any
+ opaque type NamedTuple[N <: Tuple, +V <: Tuple] >: V <: AnyNamedTuple = V
+
+ def apply[N <: Tuple, V <: Tuple](x: V): NamedTuple[N, V] = x
+
+ def unapply[N <: Tuple, V <: Tuple](x: NamedTuple[N, V]): Some[V] = Some(x)
+
+ extension [V <: Tuple](x: V)
+ inline def withNames[N <: Tuple]: NamedTuple[N, V] = x
+
+ export NamedTupleDecomposition.{Names, DropNames}
+
+ extension [N <: Tuple, V <: Tuple](x: NamedTuple[N, V])
+
+ /** The underlying tuple without the names */
+ inline def toTuple: V = x
+
+ /** The number of elements in this tuple */
+ inline def size: Tuple.Size[V] = toTuple.size
+
+ // This intentionally works for empty named tuples as well. I think NnEmptyTuple is a dead end
+ // and should be reverted, justy like NonEmptyList is also appealing at first, but a bad idea
+ // in the end.
+
+ /** The value (without the name) at index `n` of this tuple */
+ inline def apply(n: Int): Tuple.Elem[V, n.type] =
+ inline toTuple match
+ case tup: NonEmptyTuple => tup(n).asInstanceOf[Tuple.Elem[V, n.type]]
+ case tup => tup.productElement(n).asInstanceOf[Tuple.Elem[V, n.type]]
+
+ /** The first element value of this tuple */
+ inline def head: Tuple.Elem[V, 0] = apply(0)
+
+ /** The tuple consisting of all elements of this tuple except the first one */
+ inline def tail: Tuple.Drop[V, 1] = toTuple.drop(1)
+
+ /** The last element value of this tuple */
+ inline def last: Tuple.Last[V] = apply(size - 1).asInstanceOf[Tuple.Last[V]]
+
+ /** The tuple consisting of all elements of this tuple except the last one */
+ inline def init: Tuple.Init[V] = toTuple.take(size - 1).asInstanceOf[Tuple.Init[V]]
+
+ /** The tuple consisting of the first `n` elements of this tuple, or all
+ * elements if `n` exceeds `size`.
+ */
+ inline def take(n: Int): NamedTuple[Tuple.Take[N, n.type], Tuple.Take[V, n.type]] =
+ toTuple.take(n)
+
+ /** The tuple consisting of all elements of this tuple except the first `n` ones,
+ * or no elements if `n` exceeds `size`.
+ */
+ inline def drop(n: Int): NamedTuple[Tuple.Drop[N, n.type], Tuple.Drop[V, n.type]] =
+ toTuple.drop(n)
+
+ /** The tuple `(x.take(n), x.drop(n))` */
+ inline def splitAt(n: Int): NamedTuple[Tuple.Split[N, n.type], Tuple.Split[V, n.type]] =
+ toTuple.splitAt(n)
+
+ /** The tuple consisting of all elements of this tuple followed by all elements
+ * of tuple `that`. The names of the two tuples must be disjoint.
+ */
+ inline def ++ [N2 <: Tuple, V2 <: Tuple](that: NamedTuple[N2, V2])(using Tuple.Disjoint[N, N2] =:= true)
+ : NamedTuple[Tuple.Concat[N, N2], Tuple.Concat[V, V2]]
+ = toTuple ++ that.toTuple
+
+ // inline def :* [L] (x: L): NamedTuple[Append[N, ???], Append[V, L] = ???
+ // inline def *: [H] (x: H): NamedTuple[??? *: N], H *: V] = ???
+
+ /** The named tuple consisting of all element values of this tuple mapped by
+ * the polymorphic mapping function `f`. The names of elements are preserved.
+ * If `x = (n1 = v1, ..., ni = vi)` then `x.map(f) = `(n1 = f(v1), ..., ni = f(vi))`.
+ */
+ inline def map[F[_]](f: [t] => t => F[t]): NamedTuple[N, Tuple.Map[V, F]] =
+ toTuple.map(f).asInstanceOf[NamedTuple[N, Tuple.Map[V, F]]]
+
+ /** The named tuple consisting of all elements of this tuple in reverse */
+ inline def reverse: NamedTuple[Tuple.Reverse[N], Tuple.Reverse[V]] =
+ toTuple.reverse
+
+ /** The named tuple consisting of all elements values of this tuple zipped
+ * with corresponding element values in named tuple `that`.
+ * If the two tuples have different sizes,
+ * the extra elements of the larger tuple will be disregarded.
+ * The names of `x` and `that` at the same index must be the same.
+ * The result tuple keeps the same names as the operand tuples.
+ */
+ inline def zip[V2 <: Tuple](that: NamedTuple[N, V2]): NamedTuple[N, Tuple.Zip[V, V2]] =
+ toTuple.zip(that.toTuple)
+
+ /** A list consisting of all element values */
+ inline def toList: List[Tuple.Union[V]] = toTuple.toList.asInstanceOf[List[Tuple.Union[V]]]
+
+ /** An array consisting of all element values */
+ inline def toArray: Array[Object] = toTuple.toArray
+
+ /** An immutable array consisting of all element values */
+ inline def toIArray: IArray[Object] = toTuple.toIArray
+
+ end extension
+
+ /** The size of a named tuple, represented as a literal constant subtype of Int */
+ type Size[X <: AnyNamedTuple] = Tuple.Size[DropNames[X]]
+
+ /** The type of the element value at position N in the named tuple X */
+ type Elem[X <: AnyNamedTuple, N <: Int] = Tuple.Elem[DropNames[X], N]
+
+ /** The type of the first element value of a named tuple */
+ type Head[X <: AnyNamedTuple] = Elem[X, 0]
+
+ /** The type of the last element value of a named tuple */
+ type Last[X <: AnyNamedTuple] = Tuple.Last[DropNames[X]]
+
+ /** The type of a named tuple consisting of all elements of named tuple X except the first one */
+ type Tail[X <: AnyNamedTuple] = Drop[X, 1]
+
+ /** The type of the initial part of a named tuple without its last element */
+ type Init[X <: AnyNamedTuple] =
+ NamedTuple[Tuple.Init[Names[X]], Tuple.Init[DropNames[X]]]
+
+ /** The type of the named tuple consisting of the first `N` elements of `X`,
+ * or all elements if `N` exceeds `Size[X]`.
+ */
+ type Take[X <: AnyNamedTuple, N <: Int] =
+ NamedTuple[Tuple.Take[Names[X], N], Tuple.Take[DropNames[X], N]]
+
+ /** The type of the named tuple consisting of all elements of `X` except the first `N` ones,
+ * or no elements if `N` exceeds `Size[X]`.
+ */
+ type Drop[X <: AnyNamedTuple, N <: Int] =
+ NamedTuple[Tuple.Drop[Names[X], N], Tuple.Drop[DropNames[X], N]]
+
+ /** The pair type `(Take(X, N), Drop[X, N]). */
+ type Split[X <: AnyNamedTuple, N <: Int] = (Take[X, N], Drop[X, N])
+
+ /** Type of the concatenation of two tuples `X` and `Y` */
+ type Concat[X <: AnyNamedTuple, Y <: AnyNamedTuple] =
+ NamedTuple[Tuple.Concat[Names[X], Names[Y]], Tuple.Concat[DropNames[X], DropNames[Y]]]
+
+ /** The type of the named tuple `X` mapped with the type-level function `F`.
+ * If `X = (n1 : T1, ..., ni : Ti)` then `Map[X, F] = `(n1 : F[T1], ..., ni : F[Ti])`.
+ */
+ type Map[X <: AnyNamedTuple, F[_ <: Tuple.Union[DropNames[X]]]] =
+ NamedTuple[Names[X], Tuple.Map[DropNames[X], F]]
+
+ /** A named tuple with the elements of tuple `X` in reversed order */
+ type Reverse[X <: AnyNamedTuple] =
+ NamedTuple[Tuple.Reverse[Names[X]], Tuple.Reverse[DropNames[X]]]
+
+ /** The type of the named tuple consisting of all element values of
+ * named tuple `X` zipped with corresponding element values of
+ * named tuple `Y`. If the two tuples have different sizes,
+ * the extra elements of the larger tuple will be disregarded.
+ * The names of `X` and `Y` at the same index must be the same.
+ * The result tuple keeps the same names as the operand tuples.
+ * For example, if
+ * ```
+ * X = (n1 : S1, ..., ni : Si)
+ * Y = (n1 : T1, ..., nj : Tj) where j >= i
+ * ```
+ * then
+ * ```
+ * Zip[X, Y] = (n1 : (S1, T1), ..., ni: (Si, Ti))
+ * ```
+ * @syntax markdown
+ */
+ type Zip[X <: AnyNamedTuple, Y <: AnyNamedTuple] =
+ Tuple.Conforms[Names[X], Names[Y]] match
+ case true =>
+ NamedTuple[Names[X], Tuple.Zip[DropNames[X], DropNames[Y]]]
+
+ type From[T] <: AnyNamedTuple
+
+end NamedTuple
+
+/** Separate from NamedTuple object so that we can match on the opaque type NamedTuple. */
+@experimental
+object NamedTupleDecomposition:
+ import NamedTuple.*
+
+ /** The names of a named tuple, represented as a tuple of literal string values. */
+ type Names[X <: AnyNamedTuple] <: Tuple = X match
+ case NamedTuple[n, _] => n
+
+ /** The value types of a named tuple represented as a regular tuple. */
+ type DropNames[NT <: AnyNamedTuple] <: Tuple = NT match
+ case NamedTuple[_, x] => x
+```
+
+## Appendix B: Embedded Queries Case Study
+
+```scala
+import language.experimental.namedTuples
+import NamedTuple.{NamedTuple, AnyNamedTuple}
+
+/* This is a demonstrator that shows how to map regular for expressions to
+ * internal data that can be optimized by a query engine. It needs NamedTuples
+ * and type classes but no macros. It's so far very provisional and experimental,
+ * intended as a basis for further exploration.
+ */
+
+/** The type of expressions in the query language */
+trait Expr[Result] extends Selectable:
+
+ /** This type is used to support selection with any of the field names
+ * defined by Fields.
+ */
+ type Fields = NamedTuple.Map[NamedTuple.From[Result], Expr]
+
+ /** A selection of a field name defined by Fields is implemented by `selectDynamic`.
+ * The implementation will add a cast to the right Expr type corresponding
+ * to the field type.
+ */
+ def selectDynamic(fieldName: String) = Expr.Select(this, fieldName)
+
+ /** Member methods to implement universal equality on Expr level. */
+ def == (other: Expr[?]): Expr[Boolean] = Expr.Eq(this, other)
+ def != (other: Expr[?]): Expr[Boolean] = Expr.Ne(this, other)
+
+object Expr:
+
+ /** Sample extension methods for individual types */
+ extension (x: Expr[Int])
+ def > (y: Expr[Int]): Expr[Boolean] = Gt(x, y)
+ def > (y: Int): Expr[Boolean] = Gt(x, IntLit(y))
+ extension (x: Expr[Boolean])
+ def &&(y: Expr[Boolean]): Expr[Boolean] = And(x, y)
+ def || (y: Expr[Boolean]): Expr[Boolean] = Or(x, y)
+
+ // Note: All field names of constructors in the query language are prefixed with `$`
+ // so that we don't accidentally pick a field name of a constructor class where we want
+ // a name in the domain model instead.
+
+ // Some sample constructors for Exprs
+ case class Gt($x: Expr[Int], $y: Expr[Int]) extends Expr[Boolean]
+ case class Plus(x: Expr[Int], y: Expr[Int]) extends Expr[Int]
+ case class And($x: Expr[Boolean], $y: Expr[Boolean]) extends Expr[Boolean]
+ case class Or($x: Expr[Boolean], $y: Expr[Boolean]) extends Expr[Boolean]
+
+ // So far Select is weakly typed, so `selectDynamic` is easy to implement.
+ // Todo: Make it strongly typed like the other cases
+ case class Select[A]($x: Expr[A], $name: String) extends Expr
+
+ case class Single[S <: String, A]($x: Expr[A])
+ extends Expr[NamedTuple[S *: EmptyTuple, A *: EmptyTuple]]
+
+ case class Concat[A <: AnyNamedTuple, B <: AnyNamedTuple]($x: Expr[A], $y: Expr[B])
+ extends Expr[NamedTuple.Concat[A, B]]
+
+ case class Join[A <: AnyNamedTuple](a: A)
+ extends Expr[NamedTuple.Map[A, StripExpr]]
+
+ type StripExpr[E] = E match
+ case Expr[b] => b
+
+ // Also weakly typed in the arguents since these two classes model universal equality */
+ case class Eq($x: Expr[?], $y: Expr[?]) extends Expr[Boolean]
+ case class Ne($x: Expr[?], $y: Expr[?]) extends Expr[Boolean]
+
+ /** References are placeholders for parameters */
+ private var refCount = 0
+
+ case class Ref[A]($name: String = "") extends Expr[A]:
+ val id = refCount
+ refCount += 1
+ override def toString = s"ref$id(${$name})"
+
+ /** Literals are type-specific, tailored to the types that the DB supports */
+ case class IntLit($value: Int) extends Expr[Int]
+
+ /** Scala values can be lifted into literals by conversions */
+ given Conversion[Int, IntLit] = IntLit(_)
+
+ /** The internal representation of a function `A => B`
+ * Query languages are ususally first-order, so Fun is not an Expr
+ */
+ case class Fun[A, B](param: Ref[A], f: B)
+
+ type Pred[A] = Fun[A, Expr[Boolean]]
+
+ /** Explicit conversion from
+ * (name_1: Expr[T_1], ..., name_n: Expr[T_n])
+ * to
+ * Expr[(name_1: T_1, ..., name_n: T_n)]
+ */
+ extension [A <: AnyNamedTuple](x: A) def toRow: Join[A] = Join(x)
+
+ /** Same as _.toRow, as an implicit conversion */
+ given [A <: AnyNamedTuple]: Conversion[A, Expr.Join[A]] = Expr.Join(_)
+
+end Expr
+
+/** The type of database queries. So far, we have queries
+ * that represent whole DB tables and queries that reify
+ * for-expressions as data.
+ */
+trait Query[A]
+
+object Query:
+ import Expr.{Pred, Fun, Ref}
+
+ case class Filter[A]($q: Query[A], $p: Pred[A]) extends Query[A]
+ case class Map[A, B]($q: Query[A], $f: Fun[A, Expr[B]]) extends Query[B]
+ case class FlatMap[A, B]($q: Query[A], $f: Fun[A, Query[B]]) extends Query[B]
+
+ // Extension methods to support for-expression syntax for queries
+ extension [R](x: Query[R])
+
+ def withFilter(p: Ref[R] => Expr[Boolean]): Query[R] =
+ val ref = Ref[R]()
+ Filter(x, Fun(ref, p(ref)))
+
+ def map[B](f: Ref[R] => Expr[B]): Query[B] =
+ val ref = Ref[R]()
+ Map(x, Fun(ref, f(ref)))
+
+ def flatMap[B](f: Ref[R] => Query[B]): Query[B] =
+ val ref = Ref[R]()
+ FlatMap(x, Fun(ref, f(ref)))
+end Query
+
+/** The type of query references to database tables */
+case class Table[R]($name: String) extends Query[R]
+
+// Everything below is code using the model -----------------------------
+
+// Some sample types
+case class City(zipCode: Int, name: String, population: Int)
+type Address = (city: City, street: String, number: Int)
+type Person = (name: String, age: Int, addr: Address)
+
+@main def Test =
+
+ val cities = Table[City]("cities")
+
+ val q1 = cities.map: c =>
+ c.zipCode
+ val q2 = cities.withFilter: city =>
+ city.population > 10_000
+ .map: city =>
+ city.name
+
+ val q3 =
+ for
+ city <- cities
+ if city.population > 10_000
+ yield city.name
+
+ val q4 =
+ for
+ city <- cities
+ alt <- cities
+ if city.name == alt.name && city.zipCode != alt.zipCode
+ yield
+ city
+
+ val addresses = Table[Address]("addresses")
+ val q5 =
+ for
+ city <- cities
+ addr <- addresses
+ if addr.street == city.name
+ yield
+ (name = city.name, num = addr.number)
+
+ val q6 =
+ cities.map: city =>
+ (name = city.name, zipCode = city.zipCode)
+
+ def run[T](q: Query[T]): Iterator[T] = ???
+
+ def x1: Iterator[Int] = run(q1)
+ def x2: Iterator[String] = run(q2)
+ def x3: Iterator[String] = run(q3)
+ def x4: Iterator[City] = run(q4)
+ def x5: Iterator[(name: String, num: Int)] = run(q5)
+ def x6: Iterator[(name: String, zipCode: Int)] = run(q6)
+```
diff --git a/_sips/sips/2010-07-20-new-collection-classes.md b/_sips/sips/new-collection-classes.md
similarity index 73%
rename from _sips/sips/2010-07-20-new-collection-classes.md
rename to _sips/sips/new-collection-classes.md
index ea7371be48..d8bb9b8047 100644
--- a/_sips/sips/2010-07-20-new-collection-classes.md
+++ b/_sips/sips/new-collection-classes.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-3 - New Collection classes
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/new-collection-classes.html
---
diff --git a/_sips/sips/2017-09-20-opaque-types.md b/_sips/sips/opaque-types.md
similarity index 98%
rename from _sips/sips/2017-09-20-opaque-types.md
rename to _sips/sips/opaque-types.md
index 8580764b31..a33083181d 100644
--- a/_sips/sips/2017-09-20-opaque-types.md
+++ b/_sips/sips/opaque-types.md
@@ -1,12 +1,14 @@
---
layout: sip
title: SIP-35 - Opaque types
-
-vote-status: accepted
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/opaque-types.html
---
+> This proposal has been implemented with some changes in Scala 3.0.0.
+
**Authors: Erik Osheim and Jorge Vicente Cantero**
**Supervisor and advisor: Sébastien Doeraene**
@@ -50,11 +52,8 @@ For a definition of boxing and previous state-of-the-art, we recommend reading [
### Implementation note
-The proposal is currently in an early stage.
-[It’s being implemented](https://github.com/scalacenter/scala/tree/opaque-type),
-but the proposed implementation strategy is not detailed enough to be able
-to predict with certainty that it will work as specified. Consequently,
-details of the proposal might change driven by implementation concerns.
+Opaque types have been implemented in Scala 3.0.0 with
+[some changes compared to this proposal]({{ site.scala3ref }}/other-new-features/opaques-details.html#relationship-to-sip-35).
## Opaque types
@@ -122,7 +121,7 @@ signature of `apply` is redefined as `def apply(x: Double): Double`
and that `val x: Logarithm = Logarithm(1e7)` is instead `val x: Double
= Logarithm.apply(1e7)`.
-Value classes can rewrite many instances `Logarithm` in terms of
+Value classes can rewrite many instances of `Logarithm` in terms of
`Double`, including local variables, method parameters, return types,
and most fields. SIP-15 lays out the exact circumstances when these
rules occur, and extension methods ensure that boxing and unboxing
@@ -293,7 +292,7 @@ package object usesites {
}
```
-Note that the rational for this encoding is to allow users to convert from the opaque type
+Note that the rationale for this encoding is to allow users to convert from the opaque type
and the underlying type in constant time. Users have to be able to tag complex type structures
without having to reallocate, iterate over or inspect it.
@@ -670,8 +669,8 @@ package object groups {
opaque type Unordered[A] = A
object Unordered extends Wrapper[Unordered] {
- def wraps[G[_], A](ga: G[A]): G[Reversed[A]] = ga
- def unwrap[G[_], A](gfa: G[Reversed[A]]): G[A] = gfa
+ def wraps[G[_], A](ga: G[A]): G[Unordered[A]] = ga
+ def unwrap[G[_], A](gfa: G[Unordered[A]]): G[A] = gfa
implicit def unorderedOrdering[A]: Ordering[Unordered[A]] =
Ordering.by(_ => ())
}
@@ -693,7 +692,7 @@ example `Int`).
### Probability interval
Here's an example that demonstrates how opaque types can limit the
-underlying type's range of values in a way that minimizes the require
+underlying type's range of values in a way that minimizes the required
error-checking:
```scala
diff --git a/_sips/sips/pattern-matching-with-named-fields.md b/_sips/sips/pattern-matching-with-named-fields.md
new file mode 100644
index 0000000000..c1c304a61f
--- /dev/null
+++ b/_sips/sips/pattern-matching-with-named-fields.md
@@ -0,0 +1,6 @@
+---
+title: SIP-43 - Pattern matching with named fields
+status: withdrawn
+pull-request-number: 44
+
+---
diff --git a/_sips/sips/2010-06-01-picked-signatures.md b/_sips/sips/picked-signatures.md
similarity index 75%
rename from _sips/sips/2010-06-01-picked-signatures.md
rename to _sips/sips/picked-signatures.md
index 974dfdbd34..12f205a4e1 100644
--- a/_sips/sips/2010-06-01-picked-signatures.md
+++ b/_sips/sips/picked-signatures.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-10 - Storage of pickled Scala signatures in class files
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/picked-signatures.html
---
diff --git a/_sips/sips/polymorphic-eta-expansion.md b/_sips/sips/polymorphic-eta-expansion.md
new file mode 100644
index 0000000000..4099e05cc8
--- /dev/null
+++ b/_sips/sips/polymorphic-eta-expansion.md
@@ -0,0 +1,429 @@
+---
+layout: sip
+title: SIP-49 - Polymorphic Eta-Expansion
+stage: implementation
+status: waiting-for-implementation
+permalink: /sips/:title.html
+---
+
+**By: Quentin Bernet and Guillaume Martres**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Sep 23th 2022 | Initial Draft |
+
+## Summary
+
+
+
+We propose to extend eta-expansion to polymorphic methods.
+This means automatically transforming polymorphic methods into corresponding polymorphic functions when required, for example:
+
+~~~ scala
+def f1[A](x: A): A = ???
+val v1_1: [B] => B => B = f1 // f1 becomes [B'] => (y: B') => f1[B'](y)
+~~~
+
+Returning readers, for a quick glance at a wide array of examples illustrated like the above, go to [High-level overview](#high-level-overview).
+
+In the following, "Note" never introduces new concepts, it points out a non-obvious consequence, and/or reminds the reader of a pertinent fact about Scala.
+
+## Motivation
+
+
+
+Regular eta-expansion is so ubiquitous that most users are not aware of it, for them it is intuitive and obvious that methods can be passed where functions are expected.
+
+When manipulating polymorphic methods, we wager that most users find it confusing not to be able to do the same.
+This is the main motivation of this proposal.
+
+It however remains to be demonstrated that such cases appear often enough for time and maintenance to be devoted to fixing it.
+To this end, the remainder of this section will show a manufactured example with tuples, as well as real-world examples taken from the [Shapeless-3](https://index.scala-lang.org/typelevel/shapeless-3) and [kittens](https://index.scala-lang.org/typelevel/kittens) libraries.
+
+
+#### Tuples
+
+~~~ scala
+List(1, 2, 3).map(Some.apply) // works
+
+("Hello", 2, 'u').map(Some.apply) // error:
+// Found: Any => Some[Any], Required: [t] => (t) => Nothing
+~~~
+
+As tuples are becoming a powerful part of metaprogramming through `Mirror` instances, we expect these kinds of cases to become more and more frequent.
+
+#### Shapeless ([source](https://github.com/typelevel/shapeless-3/blob/8b1bbc651618e77e0bd7c2433b79e46adafa4506/modules/deriving/src/test/scala/shapeless3/deriving/type-classes.scala#L651-L665))
+
+
+In the shapeless library, polymorphic functions are used relatively often, but they are usually small and unique, making them not very suitable for refactoring.
+There is however the following case, where a function is very large:
+
+~~~ scala
+...
+ def readElems(s: String): Option[(T, String)] = {
+ type Acc = (String, Seq[String], Boolean)
+ inst.unfold[Acc]((s, labelling.elemLabels, true))(
+ [t] => (acc: Acc, rt: Read[t]) => {
+ val (s, labels, first) = acc
+ (for {
+ (_, tl0) <- if(first) Some(("", s)) else head(s, "(,)(.*)".r)
+ (_, tl1) <- head(tl0, s"(${labels.head}):(.*)".r)
+ (t, tl2) <- rt.read(tl1)
+ } yield (t, tl2)) match {
+ case Some(t, tl2) => ((tl2, labels.tail, false), Some(t))
+ case None => ((s, labels, first), None)
+ }
+ }
+ ) match {
+ case (s, None) => None
+ case (acc, Some(t)) => Some((t, acc._1))
+ }
+ }
+~~~
+
+By factoring out the function, it is possible to make the code more readable:
+
+~~~ scala
+...
+ def readElems(s: String): Option[(T, String)] = {
+ type Acc = (String, Seq[String], Boolean)
+ val unfolder = [t] => (acc: Acc, rt: Read[t]) => {
+ val (s, labels, first) = acc
+ (for {
+ (_, tl0) <- if(first) Some(("", s)) else head(s, "(,)(.*)".r)
+ (_, tl1) <- head(tl0, s"(${labels.head}):(.*)".r)
+ (t, tl2) <- rt.read(tl1)
+ } yield (t, tl2)) match {
+ case Some(t, tl2) => ((tl2, labels.tail, false), Some(t))
+ case None => ((s, labels, first), None)
+ }
+ }
+ inst.unfold[Acc]((s, labelling.elemLabels, true))(unfolder) match {
+ case (s, None) => None
+ case (acc, Some(t)) => Some((t, acc._1))
+ }
+ }
+~~~
+
+It is natural at this point to want to transform the function into a method, as the syntax for the latter is more familiar, and more readable:
+
+~~~ scala
+...
+ def readElems(s: String): Option[(T, String)] = {
+ type Acc = (String, Seq[String], Boolean)
+ def unfolder[T](acc: Acc, rt: Read[T]): Acc = {
+ val (s, labels, first) = acc
+ (for {
+ (_, tl0) <- if(first) Some(("", s)) else head(s, "(,)(.*)".r)
+ (_, tl1) <- head(tl0, s"(${labels.head}):(.*)".r)
+ (t, tl2) <- rt.read(tl1)
+ } yield (t, tl2)) match {
+ case Some(t, tl2) => ((tl2, labels.tail, false), Some(t))
+ case None => ((s, labels, first), None)
+ }
+ }
+ inst.unfold[Acc]((s, labelling.elemLabels, true))(unfolder) match {
+ case (s, None) => None
+ case (acc, Some(t)) => Some((t, acc._1))
+ }
+ }
+~~~
+
+However, this does not compile.
+Only monomorphic eta-expansion is applied, leading to the same issue as with our previous `Tuple.map` example.
+
+#### Kittens ([source](https://github.com/typelevel/kittens/blob/e10a03455ac3dd52096a1edf0fe6d4196a8e2cad/core/src/main/scala-3/cats/derived/DerivedTraverse.scala#L44-L48))
+
+In `Kittens`, there is a case of particularly obvious eta-expansion done by hand (comments by me):
+
+~~~ scala
+...
+ final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B])
+ (using G: Applicative[G]): G[F[B]] =
+ val pure = [a] => (x: a) => G.pure(x) // eta-expansion
+ val map = [a, b] => (ga: G[a], f: a => b) => G.map(ga)(f) // ~eta-expansion
+ val ap = [a, b] => (gf: G[a => b], ga: G[a]) => G.ap(gf)(ga) // ~eta-expansion
+ inst.traverse[A, G, B](fa)(map)(pure)(ap)([f[_]] => (tf: T[f], fa: f[A]) => tf.traverse(fa)(f))
+
+~~~
+
+Sadly since `map` and `ap` are curried, assuming this proposal, only `pure` can be eliminated:
+
+~~~ scala
+...
+ final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B])
+ (using G: Applicative[G]): G[F[B]] =
+ val map = [a, b] => (ga: G[a], f: a => b) => G.map(ga)(f)
+ val ap = [a, b] => (gf: G[a => b], ga: G[a]) => G.ap(gf)(ga)
+ inst.traverse[A, G, B](fa)(map)(G.pure)(ap)([f[_]] => (tf: T[f], fa: f[A]) => tf.traverse(fa)(f))
+
+~~~
+
+This already helps with readability, but we can postulate that given cases like this, an uncurried variant of `map` and `ap` would be implemented, allowing us to write:
+
+~~~ scala
+...
+ final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B])
+ (using G: Applicative[G]): G[F[B]] =
+ inst.traverse[A, G, B](fa)(G.map)(G.pure)(G.ap)([f[_]] => (tf: T[f], fa: f[A]) => tf.traverse(fa)(f))
+~~~
+
+If wanted, we can then factor the function into a method:
+
+~~~ scala
+...
+ final override def traverse[G[_], A, B](fa: F[A])(f: A => G[B])
+ (using G: Applicative[G]): G[F[B]] =
+ def traverser[F[_]](tf: T[F], fa: F[A]) = tf.traverse(fa)(f)
+ inst.traverse[A, G, B](fa)(G.map)(G.pure)(G.ap)(traverser)
+~~~
+
+## Proposed solution
+
+
+
+### High-level overview
+
+As the previous section already describes how polymorphic eta-expansion affects the examples, we will use this section to give quantity of small, illustrative, examples, that should cover most of the range of this proposal.
+
+In the following `id'` means a copy of `id` with a fresh name, and `//reminder:` sections are unchanged by this proposal.
+#### Explicit parameters:
+~~~ scala
+def f1[A](x: A): A = ???
+val v1_1: [B] => B => B = f1 // f1 becomes [B'] => (y: B') => f1[B'](y)
+
+def f2[A]: A => A = ???
+val v2_1: [B] => B => B = f2 // f2 becomes [B'] => (y: B') => f2[B'](y)
+
+type F[C] = C => C
+def f3[A]: F[A] = ???
+val v3_1: [B] => B => B = f3 // f3 becomes [B'] => (y: B') => f3[B'](y)
+
+//reminder:
+val vErr: [B] => B = ??? // error: polymorphic function types must have a value parameter
+~~~
+
+#### Extension/Interleaved method:
+~~~ scala
+extension (x: Int)
+ def extf1[A](x: A): A = ???
+
+val extv1_1: [B] => B => B = extf1(4) // extf1(4) becomes [B'] => (y: B') => extf1(4)[B'](y)
+
+val extv1_3: Int => [B] => B => B = extf1 // extf1 becomes (i: Int) => [B'] => (y: B') => extf1(i)[B'](y)
+
+// See https://docs.scala-lang.org/sips/clause-interleaving.html
+def interleaved(key: Key)[V >: key.Value](default: V): V = ???
+val someKey: Key = ???
+val interleaved_1: [A >: someKey.Value] => A => A = interleaved(someKey)
+// interleaved(someKey) becomes [A' >: someKey.Value] => (default: A') => interleaved(someKey)[A'](default)
+~~~
+
+#### Implicit parameters:
+~~~ scala
+def uf1[A](using x: A): A = ???
+val vuf1_1: [B] => B ?=> B = uf1 // uf1 becomes [B'] => (y: B') ?=> uf1[B']
+
+
+def uf2[A]: A = ???
+val vuf2: [B] => B ?=> B = uf2 // uf2 becomes [B'] => (y: B') ?=> uf2[B']
+
+//reminder:
+val get: (String) ?=> Int = 22 // 22 becomes (s: String) ?=> 22
+val err: () ?=> Int = ?? // error: context functions require at least one parameter
+~~~
+
+### Specification
+
+
+
+Before we go on, it is important to clarify what we mean by "polymorphic method", we do not mean, as one would expect, "a method taking at least one type parameter clause", but rather "a (potentially partially applied) method whose next clause is a type clause", here is an example to illustrate:
+
+~~~ scala
+extension (x: Int)
+ def poly[T](x: T): T = x
+// signature: (Int)[T](T): T
+
+poly(4) // polymorphic method: takes a [T]
+poly // monomorphic method: takes an (Int)
+~~~
+
+Note: Since typechecking is recursive, eta-expansion of a monomorphic method like `poly` can still trigger polymorphic eta-expansion, for example:
+
+~~~ scala
+val voly: Int => [T] => T => T = poly
+// poly expands to: (x: Int) => [T] => (y: T) => poly(x)[T](y)
+~~~
+
+As this feature only provides a shortcut to express already definable objects, the only impacted area is the type system.
+
+When typing a polymorphic method `m` there are two cases to consider:
+
+#### Polymorphic expected type
+If the expected type is a polymorphic function taking `[T_1 <: U_1 >: L_1, ..., T_n <: U_n >: L_n]` as type parameters, `(A_1, ..., A_k)` as term parameters and returning `R`, we proceed as follows:
+
+Note: Polymorphic functions always take term parameters (but `k` can equal zero if the clause is explicit: `[T] => () => T`).
+
+1. Copies of `T_i`s are created, and replaced in `U_i`s, `L_i`s, `A_i`s and `R`, noted respectively `T'_i`, `U'_i`, `L'_i`, `A'_i` and `R'`.
+
+2. Is the expected type a polymorphic context function ?
+* 1. If yes then `m` is replaced by the following:
+~~~ scala
+[T'_1 <: U'_1 >: L'_1, ... , T'_n <: U'_n >: L'_n]
+ => (a_1: A'_1 ..., a_k: A'_k)
+ ?=> m[T'_1, ..., T'_n]
+~~~
+* 2. If no then `m` is replaced by the following:
+~~~ scala
+[T'_1 <: U'_1 >: L'_1, ... , T'_n <: U'_n >: L'_n]
+ => (a_1: A'_1 ..., a_k: A'_k)
+ => m[T'_1, ..., T'_n](a_1, ..., a_k)
+~~~
+
+3. the application of `m` is type-checked with expected type `R'`
+* 1. If it succeeds, the above is the created tree.
+* 2. If it fails, go to Default.
+
+At 3.ii. if the cause of the error is such that [Non-polymorphic expected type](#non-polymorphic-expected-type) will never succeed, we might return that error directly, this is at the discretion of the implementation, to make errors as clear as possible.
+
+Note: Type checking will be in charge of overloading resolution, as well as term inference, so the following will work:
+~~~ scala
+def f[A](using Int)(x: A)(using String): A
+def f[B](x: B, y: B): B
+
+given i: Int = ???
+given s: String = ???
+val v: [T] => T => T = f
+// f expands to: [T'] => (t: T') => f[T'](t)
+// and then to: [T'] => (t: T') => f[T'](using i)(t)(using s)
+
+def g[C](using C): C
+val vg: [T] => T ?=> T = g
+// g expands to: [T'] => (t: T') ?=> g[T']
+// and then to: [T'] => (t: T') ?=> g[T'](using t)
+~~~
+
+Note: Type checking at 3. will have to recursively typecheck `m[T'_1, ..., T'_n](a_1, ..., a_k)` with expected type `R`, this can lead to further eta-expansion:
+~~~ scala
+extension [A](x: A)
+ def foo[B](y: B) = (x, y)
+
+val voo: [T] => T => [U] => U => (T, U) = foo
+// foo expands to:
+// [T'] => (t: T') => ( foo[T'](t) with expected type [U] => U => (T', U) )
+// [T'] => (t: T') => [U'] => (u: U') => foo[T'](t)[U'](u)
+~~~
+
+#### Non-polymorphic expected type
+
+No polymorphic eta-expansion is performed, this corresponds to the old behaviour, written here as a reminder:
+
+Fresh variables are applied to `m`, typing constraints are generated, and typing continues, for example:
+
+~~~ scala
+def ident[T](x: T): T = x
+
+val idInt: Int => Int = ident
+// ident becomes:
+// ident[X] with expected type Int => Int
+// (x: X) => ident[X](x) of type X => X with expected type Int => Int
+// therefore X := Int
+// (x: Int) => ident[Int](x)
+~~~
+
+### Compatibility
+
+
+
+#### Binary and TASTy
+
+As this proposal never generates code that couldn't have been written by hand before, these changes are binary and TASTy compatible.
+
+#### Source
+
+This proposal conserves source compatibility when a non-polymorphic expected type is present, or when there is no expected type, since by definition the behaviour is the same.
+
+In the case the expected type is polymorphic, either the code did not compile before, or there was an implicit conversion from the inferred monomorphic function to the expected polymorphic function. In the latter case, source compatibility is broken, since polymorphic eta-expansion will apply before search for implicit conversions, for example:
+
+```scala
+import scala.language.implicitConversions
+
+given conv: Conversion[Any => Any, [T] => T => T] = f => ([T] => (x: T) => x)
+
+def method[T](x: T): T = x
+
+val function: [T] => T => T = method
+// before: method is eta-expanded to Any => Any, and then converted using conv to [T] => T => T
+// now: method is eta-expanded to [T] => T => T (conv is not called)
+```
+
+### Restrictions
+
+Not included in this proposal are:
+
+* Applying polymorphic eta-expansion when there is no return type
+* Expanding `[T] => T => T` to `[T] => T => Id[T]` to make `tuple.map(identity)` work (might work out of the box anyways, but not guaranteed)
+* Expanding `x => x` to `[T] => (x: T) => x` if necessary (and generalizations)
+* Expanding `_` to `[T] => (x: T) => x` if necessary (and generalizations)
+* Polymorphic SAM conversion
+* Polymorphic functions from wildcard: `foo[_](_)`
+
+While all of the above could be argued to be valuable, we deem they are out of the scope of this proposal.
+
+We encourage the creation of follow-up proposals to motivate their inclusion.
+
+
+
+### Open questions
+
+
+
+
+
+
+## Related work
+
+
+
+* Pre-SIP: https://contributors.scala-lang.org/t/polymorphic-eta-expansion/5516
+* A naive implementation can be found at https://github.com/scala/scala3/pull/14015 (it is more general than this proposal and thus breaks compatibility)
+* A compatibility-preserving implementation is in development.
+
+
+## FAQ
+
+
diff --git a/_sips/sips/precise-type-modifier.md b/_sips/sips/precise-type-modifier.md
new file mode 100644
index 0000000000..9c316bbd8c
--- /dev/null
+++ b/_sips/sips/precise-type-modifier.md
@@ -0,0 +1,6 @@
+---
+title: SIP-48 - Precise Type Modifier
+status: withdrawn
+pull-request-number: 48
+
+---
diff --git a/_sips/sips/2017-02-07-priority-based-infix-type-precedence.md b/_sips/sips/priority-based-infix-type-precedence.md
similarity index 94%
rename from _sips/sips/2017-02-07-priority-based-infix-type-precedence.md
rename to _sips/sips/priority-based-infix-type-precedence.md
index 295f047dec..a67d84dbb5 100644
--- a/_sips/sips/2017-02-07-priority-based-infix-type-precedence.md
+++ b/_sips/sips/priority-based-infix-type-precedence.md
@@ -1,7 +1,8 @@
---
layout: sip
title: SIP-33 - Priority-based infix type precedence
-vote-status: complete
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/priority-based-infix-type-precedence.html
---
@@ -17,7 +18,7 @@ redirect_from: /sips/pending/priority-based-infix-type-precedence.html
| Feb 10th 2017 | Updates from feedback |
| Aug 8th 2017 | Numbered SIP, improve view, fixed example, and added related issues |
| Oct 20th 2017 | Added implementation link |
-| Oct 25th 2017 | Moved prefix types to [another SIP](https://docs.scala-lang.org/sips/adding-prefix-types.html), changed title and PR |
+| Oct 25th 2017 | Moved prefix types to [another SIP](https://github.com/scala/improvement-proposals/pull/35), changed title and PR |
| Nov 29th 2017 | Updated SIP according to feedback in the PR |
@@ -120,9 +121,9 @@ A PR for this SIP is available at: [https://github.com/scala/scala/pull/6147](ht
### Interactions with other language features
-#### Star `*` infix type interaction with repeated parameters
-The [repeated argument symbol `*`](https://www.scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#repeated-parameters) may create confusion with the infix type `*`.
-Please note that this feature interaction already exists within the current specification.
+#### Star `*` infix type interaction with repeated parameters
+The [repeated argument symbol `*`](https://www.scala-lang.org/files/archive/spec/2.12/04-basic-declarations-and-definitions.html#repeated-parameters) may create confusion with the infix type `*`.
+Please note that this feature interaction already exists within the current specification.
```scala
trait +[N1, N2]
@@ -136,11 +137,11 @@ However, it is very unlikely that such interaction would occur.
**Related Issues**
-* [Dotty Issue #1961](https://github.com/lampepfl/dotty/issues/1961)
+* [Dotty Issue #1961](https://github.com/scala/scala3/issues/1961)
## Backward Compatibility
-Changing infix type associativity and precedence affects code that uses type operations and conforms to the current specification.
+Changing infix type associativity and precedence affects code that uses type operations and conforms to the current specification.
Note: changing the infix precedence didn't fail any scalac test.
diff --git a/_sips/sips/quote-pattern-type-variable-syntax.md b/_sips/sips/quote-pattern-type-variable-syntax.md
new file mode 100644
index 0000000000..64f58fafb8
--- /dev/null
+++ b/_sips/sips/quote-pattern-type-variable-syntax.md
@@ -0,0 +1,145 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: completed
+status: shipped
+title: SIP-53 - Quote pattern explicit type variable syntax
+---
+
+**By: Nicolas Stucki**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Feb 28th 2022 | Initial Draft |
+| Oct 6th 2022 | [Stabilize implementation](https://github.com/scala/scala3/pull/18574) |
+| Feb 29th 2023 | Available in [Scala 3.4.0](https://www.scala-lang.org/blog/2024/02/29/scala-3.4.0-and-3.3.3-released.html) |
+
+## Summary
+
+This SIP proposes additions to the syntax of type variable definitions to bring quoted type matching to par with quoted expression matching.
+Specifically, the ability to declare type variables explicitly and define them with bounds.
+
+It also proposes some enhancements to make the use of type variables simpler.
+The idea is to reduce the number of cases where we need to write backticks around type variable name references.
+Namely when using explicit type variable definitions.
+
+## Motivation
+
+### Background
+
+* [Reference Documentation](http://dotty.epfl.ch/docs/reference/metaprogramming/macros.html#type-variables)
+
+Quoted expressions support two ways of defining type variables: explicit and nested.
+
+##### Explicit type variables
+The initial `type` declarations in the pattern with a type variable name (lowercase names as with normal pattern type variables) are type variable definitions. Type variable references need to be in backticks. Otherwise, we assume they are nested type variables and emit an error. These definitions can have bounds defined on them.
+```scala
+case '{ type t; $x: `t` } => f[t](x: Expr[t])
+case '{ type u; ($ls: List[`u`]).map($f: `u` => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int])
+case '{ type tail <: Tuple; $x: *:[Int, `tail`] } => h[tail](x: Expr[*:[Int, tail])
+```
+
+##### Nested type variable
+Types with a type variable name introduce a new type variable. These cannot be references with a backticked reference due to their scope. We cannot add explicit bounds to them, but in certain cases we can infer their some bounds. These variables become explicit type variables in the internal representation after typing.
+```scala
+case '{ $x: t } => f[t](x: Expr[t])
+```
+
+
+##### Type Patterns
+Quoted type patterns only support nested type variable definitions. Explicit type variables are not supported in the source due to an oversight. These variables become explicit type variables in the internal representation after typing. The bounds of the type variable are `Any` and `Nothing`.
+```scala
+case '[ t ] => f[t]
+case '[ List[t] ] => g[t]
+```
+
+### Support type bounds in quoted type patterns
+
+We want to be able to set the bounds of type variables to be able to match against type constructors that have type bounds. For example, the tuple `*:` type.
+```scala
+case '[ head *: tail ] => h[tail]
+```
+See [https://github.com/scala/scala3/issues/11738](https://github.com/scala/scala3/issues/11738).
+
+### Support matching on any kind of type
+We want to match against higher-kinded (or `AnyKind`) types. This is not possible due to the default upper bound of `Any`.
+See [https://github.com/scala/scala3/issues/10864](https://github.com/scala/scala3/issues/10864).
+
+### Support multiple references to the same type in quoted type patterns
+We want to be able to match using several references to the same type variable.
+```scala
+case '[ (t, t, t) ] => f[t] // t is going to match the glb of the tuple T1, T2, T3
+```
+
+### Simplify the use of explicit type variables
+It is inconsistent to need to use backticks for references to explicit type variables in the quote but not outside.
+We want to be able to refer to the variable by its non-backticked name uniformly.
+```diff
+- case '{ type u; ($ls: List[`u`]).map($f: `u` => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int])
++ case '{ type u; ($ls: List[u]).map($f: u => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int])
+```
+
+## Proposed solution
+
+### High-level overview
+
+We first want to introduce syntax for explicit type variable definitions in quoted type patterns that aligns with expression quoted patterns. We can use the syntax described in [explicit type variables](#explicit-type-variables).
+
+```scala
+case '[ type t; List[`t`] ] => f[t]
+case '[ type tail <: Tuple; *:[Int, `tail`] ] => g[tail]
+```
+
+Second, we want the remove the need for backticks for references to explicit type variable definitions. If we have an explicit type variable definition and a type variable with the same name, we can syntactically assume these are the same and not introduce a new nested type variable.
+```scala
+case '{ type t; $x: t } => f[t](x: Expr[t])
+case '{ type u; ($ls: List[u]).map($f: u => Int) } => g[u](ls: Expr[List[u]], f: Expr[u => Int])
+case '{ type tail <: Tuple; $x: *:[Int, tail] } => h[tail](x: Expr[*:[Int, tail])
+```
+```scala
+case '[ type t; List[t] ] => f[t]
+case '[ type tail <: Tuple; *:[Int, tail] ] => g[tail]
+```
+
+### Specification
+
+Adding the explicit type variable definition to quoted type patterns is relatively straightforward as nested type variables become explicit ones internally. We would only need to update the parser to accept a new kind of type in the syntax. This type would only be used in the quote type pattern syntax, which is self-contained in the language's grammar.
+
+```diff
+Quoted ::= ‘'’ ‘{’ Block ‘}’
+- | ‘'’ ‘[’ Type ‘]’
++ | ‘'’ ‘[’ TypeBlock ‘]’
++TypeBlock ::= {TypeBlockStat semi} Type
++TypeBlockStat ::= ‘type’ {nl} TypeDcl
+```
+
+Allowing non-backticked references to explicit type variable definitions would not create any conflict, as these would currently cause a double definition error. The grammar would not need to change. This would only interact with the process of typing quoted patterns.
+
+### Compatibility
+
+There are no compatibility issues because the parser or typer rejected all these cases.
+
+TASTy only contains explicit type variable definitions, and this encoding would not change. Note that TASTy supports _type blocks_ using the regular `Block` AST. These contain type declaration in their statements and a type instead of the expression.
+
+### Other concerns
+
+* Tools that parse Scala code must be updated with this new grammar.
+* Tools that use TASTy would not be affected.
+
+
+
+## Alternatives
+
+* We could find a different syntax for explicit type variables in quoted type patterns. The drawback is that we need to specify and explain a secondary syntax.
+* Don't include the backticks improvements.
+
+## Related work
+
+* Proof of concept of type variable syntax: [https://github.com/scala/scala3/pull/16910](https://github.com/scala/scala3/pull/16910)
+* Proof of concept of backticks (only interested in the first bullet point): [https://github.com/scala/scala3/pull/16935](https://github.com/scala/scala3/pull/16935)
+* Implementation: [https://github.com/scala/scala3/pull/17362](https://github.com/scala/scala3/pull/17362)
+* Stabilized implementation: [https://github.com/scala/scala3/pull/18574](https://github.com/scala/scala3/pull/18574)
+
+
diff --git a/_sips/sips/repeated-by-name-parameters.md b/_sips/sips/repeated-by-name-parameters.md
new file mode 100644
index 0000000000..6949fcf87c
--- /dev/null
+++ b/_sips/sips/repeated-by-name-parameters.md
@@ -0,0 +1,6 @@
+---
+title: SIP-24 - Repeated By Name Parameters
+status: withdrawn
+pull-request-number: 23
+
+---
diff --git a/_sips/sips/replace-nonsensical-unchecked-annotation.md b/_sips/sips/replace-nonsensical-unchecked-annotation.md
new file mode 100644
index 0000000000..3bb8609940
--- /dev/null
+++ b/_sips/sips/replace-nonsensical-unchecked-annotation.md
@@ -0,0 +1,260 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: implementation
+status: under-review
+presip-thread: https://contributors.scala-lang.org/t/pre-sip-replace-non-sensical-unchecked-annotations/6342
+title: SIP-57 - Replace non-sensical @unchecked annotations
+---
+
+**By: Martin Odersky and Jamie Thompson**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Dec 8th 2023 | Initial Draft |
+| Jan 19th 2024 | Clarification about current @unchecked behavior |
+
+## Summary
+
+We propose to replace the mechanism to silence warnings for "unchecked" patterns, in the cases where silencing the warning will still result in the pattern being checked at runtime.
+
+Currently, a user can silence warnings that a scrutinee may not be matched by a pattern, by annotating the scrutinee with the `@unchecked` annotation. This SIP proposes to use a new annotation `@RuntimeCheck` to replace `@unchecked` for this purpose. For convenience, an extension method will be added to `Predef` that marks the receiver with the annotation (used as follows: `foo.runtimeCheck`). Functionally it behaves the same as the old annotation, but improves readability at the callsite.
+
+## Motivation
+
+As described in [Scala 3 Reference: Pattern Bindings](https://docs.scala-lang.org/scala3/reference/changed-features/pattern-bindings.html), under `-source:future` it is an error for a pattern definition to be refutable. For instance, consider:
+```scala
+def xs: List[Any] = ???
+val y :: ys = xs
+```
+
+This compiled without warning in 3.0, became a warning in 3.2, and we would like to make it an error by default in a future 3.x version.
+As an escape hatch we recommend to use `@unchecked`:
+```
+-- Warning: ../../new/test.scala:6:16 ------------------------------------------
+6 | val y :: ys = xs
+ | ^^
+ |pattern's type ::[Any] is more specialized than the right hand side expression's type List[Any]
+ |
+ |If the narrowing is intentional, this can be communicated by adding `: @unchecked` after the expression,
+ |which may result in a MatchError at runtime.
+```
+Similarly for non-exhaustive `match` expressions, where we also recommend to put `@unchecked` on the scrutinee.
+
+But `@unchecked` has several problems. First, it is ergonomically bad. For instance to fix the exhaustivity warning in
+```scala
+xs match
+ case y :: ys => ...
+```
+we'd have to write
+```
+(xs: @unchecked) match
+ case y :: ys => ...
+```
+Having to wrap the `@unchecked` in parentheses requires editing in two places, and arguably harms readability: both due to the churn in extra symbols, and because in this use case the `@unchecked` annotation poorly communicates intent.
+
+Nominally, the purpose of the annotation is to silence warnings (_from the [API docs](https://www.scala-lang.org/api/3.3.1/scala/unchecked.html#)_):
+> An annotation to designate that the annotated entity should not be considered for additional compiler checks.
+
+_The exact meaning of this description is open to interpretation, leading to differences between Scala 2.13 and Scala 3.x. See the [misinterpretation](#misinterpretation-of-unchecked) annex for more._
+
+
+In the following code however, the word `unchecked` is a misnomer, so could be confused for another meaning by an inexperienced user:
+
+```scala
+def xs: List[Any] = ???
+val y :: ys = xs: @unchecked
+```
+ After all, the pattern `y :: ys` _is_ checked, but it is done at runtime (by looking at the runtime class), rather than statically.
+
+As a direct contradiction, in the following usage of `unchecked`, the meaning is the opposite:
+```scala
+xs match
+ case ints: List[Int @unchecked] =>
+```
+Here, `@unchecked` means that the `Int` parameter will _not_ be checked at runtime: The compiler instead trusts the user that `ints` is a `List[Int]`. This could lead to a `ClassCastException` in an unrelated piece of code that uses `ints`, possibly without leaving a clear breadcrumb trail of where the faulty cast originally occurred.
+
+## Proposed solution
+
+### High-level overview
+
+This SIP proposes to fix the ergnomics and readability of `@unchecked` in the usage where it means "checked at runtime", by instead adding a new annotation `scala.internal.RuntimeCheck`.
+
+```scala
+package scala.annotation.internal
+
+final class RuntimeCheck extends Annotation
+```
+
+In all usages where the compiler looks for `@unchecked` for this purpose, we instead change to look for `@RuntimeCheck`.
+
+By placing the annotation in the `internal` package, we communicate that the user is not meant to directly use the annotation.
+
+Instead, for convenience, we provide an extension method `Predef.runtimeCheck`, which can be applied to any expression.
+
+The new usage to assert that a pattern is checked at runtime then becomes as follows:
+```scala
+def xs: List[Any] = ???
+val y :: ys = xs.runtimeCheck
+```
+
+We also make `runtimeCheck` a transparent inline method. This ensures that the elaboration of the method defines its semantics. (i.e. `runtimeCheck` is not meaningful because it is immediately inlined at type-checking).
+
+### Specification
+
+The addition of a new `scala.Predef` method:
+
+```scala
+package scala
+
+import scala.annotation.internal.RuntimeCheck
+
+object Predef:
+ extension [T](x: T)
+ transparent inline def runtimeCheck: x.type =
+ x: @RuntimeCheck
+```
+
+### Compatibility
+
+This change carries the usual backward binary and TASTy compatibility concerns as any other standard library addition to the Scala 3 only library.
+
+Considering backwards source compatibility, the following situation will change:
+
+```scala
+// source A.scala
+package example
+
+extension (predef: scala.Predef.type)
+ transparent inline def runtimeCheck[T](x: T): x.type =
+ println("fake runtimeCheck")
+ x
+```
+```scala
+// source B.scala
+package example
+
+@main def Test =
+ val xs = List[Any](1,2,3)
+ val y :: ys = Predef.runtimeCheck(xs)
+ assert(ys == List(2, 3))
+```
+
+Previously this code would print `fake runtimeCheck`, however with the proposed change then recompiling this code will _succeed_ and no longer will print.
+
+Potentially we could mitigate this if necessary with a migration warning when the new method is resolved (`@experimental` annotation would be a start)
+
+
+In general however, the new `runtimeCheck` method will not change any previously linking method without causing an ambiguity compilation error.
+
+### Other concerns
+
+In 3.3 we already require the user to put `@unchecked` to avoid warnings, there is likely a significant amount of existing code that will need to migrate to the new mechanism. (We can leverage already exisiting mechanisms help migrate code automatically).
+
+### Open questions
+
+1) A large question was should the method or annotation carry semantic weight in the language. In this proposal we weigh towards the annotation being the significant element.
+The new method elaborates to an annotated expression before the associated pattern exhaustivity checks occur.
+2) Another point, where should the helper method go? In Predef it requires no import, but another possible location was the `compiletime` package. Requiring the extra import could discourage usage without consideration - however if the method remains in `Predef` the name itself (and documentation) should signal danger, like with `asInstanceOf`.
+
+3) Should the `RuntimeCheck` annotation be in the `scala.annotation.internal` package?
+
+### Misinterpretation of unchecked
+
+We would further like to highlight that the `unchecked` annotation is unspecified except for its imprecise API documentation. This leads to a crucial difference in its behavior between Scala 2.13 and the latest Scala 3.3.1 release.
+
+#### Scala 3 semantics
+
+Say you have the following:
+```scala
+val xs = List(1: Any)
+```
+
+The following expression in Scala 3.3.1 yields two warnings:
+```scala
+xs match {
+ case is: ::[Int] => is.head
+}
+```
+
+```scala
+2 warnings found
+-- [E029] Pattern Match Exhaustivity Warning: ----------------------------------
+1 |xs match {
+ |^^
+ |match may not be exhaustive.
+ |
+ |It would fail on pattern case: List(_, _*), Nil
+ |
+ | longer explanation available when compiling with `-explain`
+val res0: Int = 1
+-- Unchecked Warning: ----------------------------------------------------------
+2 | case is: ::[Int] => is.head
+ | ^
+ |the type test for ::[Int] cannot be checked at runtime because its type arguments can't be determined from List[Any]
+```
+
+using `@unchecked` on `xs` has the effect of silencing any warnings that depend on checking `xs`, so no warnings will be emitted for the following change:
+
+```scala
+(xs: @unchecked) match {
+ case is: ::[Int] => is.head
+}
+```
+
+#### Scala 2.13 semantics
+
+However, in Scala 2.13, this will only silence the `match may not be exhaustive` warning, and the user will still see the `type test for ::[Int] cannot be checked at runtime` warning:
+
+```scala
+scala> (xs: @unchecked) match {
+ | case is: ::[Int] => is.head
+ | } ^
+On line 2: warning: non-variable type argument Int in type pattern scala.collection.immutable.::[Int] (the underlying of ::[Int]) is unchecked since it is eliminated by erasure
+val res2: Int = 1
+```
+
+#### Aligning to Scala 2.13 semantics with runtimeCheck
+
+with `xs.runtimeCheck` we should still produce an unchecked warning for `case is: ::[Int] =>`
+```scala
+scala> xs.runtimeChecked match {
+ | case is: ::[Int] => is.head
+ | }
+1 warning found
+-- Unchecked Warning: ----------------------------------------------------------
+2 | case is: ::[Int] => is.head
+ | ^
+ |the type test for ::[Int] cannot be checked at runtime because its type arguments can't be determined from List[Any]
+val res13: Int = 1
+```
+This is because `xs.runtimeChecked` means trust the user as long as the pattern can be checked at runtime.
+
+To fully avoid warnings, the `@unchecked` will be put on the type argument:
+```scala
+scala> xs.runtimeChecked match {
+ | case is: ::[Int @unchecked] => is.head
+ | }
+val res14: Int = 1
+```
+This has a small extra migration cost because if the scrutinee changes from `(xs: @unchecked)` to `xs.runtimeCheck` now some individual cases might need to add `@unchecked` on type arguments to avoid creating new warnings - however this cost is offset by perhaps revealing unsafe patterns previously unaccounted for.
+
+Once again `@nowarn` can be used to fully restore any old behavior
+
+## Alternatives
+
+1) make `runtimeCheck` a method on `Any` that returns the receiver (not inline). The compiler would check for presence of a call to this method when deciding to perform static checking of pattern exhaustivity. This idea was criticised for being brittle with respect to refactoring, or automatic code transformations via macro.
+
+2) `runtimeCheck` should elaborate to code that matches the expected type, e.g. to heal `t: Any` to `Int` when the expected type is `Int`. The problem is that this is not useful for patterns that can not be runtime checked by type alone. Also, it implies a greater change to the spec, because now `runtimeCheck` would have to be specially treated.
+
+## Related work
+
+- [Pre SIP thread](https://contributors.scala-lang.org/t/pre-sip-replace-non-sensical-unchecked-annotations/6342)
+- [Scala 3 Reference: Pattern Bindings](https://docs.scala-lang.org/scala3/reference/changed-features/pattern-bindings.html),
+- None of OCaml, Rust, Swift, or Java offer explicit escape hatches for non-exhaustive pattern matches (Haskell does not even warn by default). Instead the user must add a default case, (making it exhaustive) or use the equivalent of `@nowarn` when they exist.
+
+## FAQ
+
+N/A so far.
diff --git a/_sips/sips/2017-07-12-right-associative-by-name-operators.md b/_sips/sips/right-associative-by-name-operators.md
similarity index 96%
rename from _sips/sips/2017-07-12-right-associative-by-name-operators.md
rename to _sips/sips/right-associative-by-name-operators.md
index 6b9ae3d0a6..3d247af33d 100644
--- a/_sips/sips/2017-07-12-right-associative-by-name-operators.md
+++ b/_sips/sips/right-associative-by-name-operators.md
@@ -1,11 +1,14 @@
---
layout: sip
-title: SIP-34 - Right-Associative By-Name Operators
-vote-status: accepted
+title: SIP-39 - Right-Associative By-Name Operators
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/right-associative-by-name-operators.html
---
+> This proposal has been implemented in Scala 2.13.0 and Scala 3.0.0.
+
**By: Stefan Zeiger**
## History
diff --git a/_sips/sips/2010-01-22-scala-2-8-arrays.md b/_sips/sips/scala-2-8-arrays.md
similarity index 99%
rename from _sips/sips/2010-01-22-scala-2-8-arrays.md
rename to _sips/sips/scala-2-8-arrays.md
index f733a6de60..7f5999d651 100644
--- a/_sips/sips/2010-01-22-scala-2-8-arrays.md
+++ b/_sips/sips/scala-2-8-arrays.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-7 - Scala 2.8 Arrays
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/scala-2-8-arrays.html
---
diff --git a/_sips/sips/scala-3-macro-annotations.md b/_sips/sips/scala-3-macro-annotations.md
new file mode 100644
index 0000000000..497a56896e
--- /dev/null
+++ b/_sips/sips/scala-3-macro-annotations.md
@@ -0,0 +1,7 @@
+---
+title: SIP-63 - Scala 3 Macro Annotations
+status: under-review
+pull-request-number: 80
+stage: design
+
+---
diff --git a/_sips/sips/scala-cli.md b/_sips/sips/scala-cli.md
new file mode 100644
index 0000000000..de9aaece39
--- /dev/null
+++ b/_sips/sips/scala-cli.md
@@ -0,0 +1,681 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: completed
+status: shipped
+title: SIP-46 - Scala CLI as default Scala command
+---
+
+**By: Krzysztof Romanowski and Scala CLI team**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| July 15th 2022 | Initial Draft |
+
+## Summary
+
+We propose to replace current script that is installed as `scala` with Scala CLI - a batteries included tool to interact with Scala. Scala CLI brings all the features that the commands above provide and expand them with incremental compilation, dependency management, packaging and much more.
+
+Even though Scala CLI could replace `scaladoc` and `scalac` commands as well for now, we do not propose to replace them.
+
+
+## Motivation
+
+The current default `scala` script is quite limited since it can only start repl or run pre-compile Scala code.
+
+The current script are lacking basic features such as support for resolving dependencies, incremental compilation or support for outputs other than JVM. This forces any user that wants to do anything more than just basic things to learn and use SBT, Mill or an other build tool and that adds to the complexity of learning Scala.
+
+We observe that the current state of tooling in Scala is limiting creativity, with quite a high cost to create e.g. an application or a script with some dependencies that target Node.js. Many Scala developers are not choosing Scala for their personal projects, scripts, or small applications and we believe that the complexity of setting up a build tool is one of the reasons.
+
+With this proposal our main goal is to turn Scala into a language with "batteries included" that will also respect the community-first aspect of our ecosystem.
+
+### Why decided to work on Scala CLI rather then improve existing tools like sbt or Mill?
+
+Firstly, Scala CLI is in no way an actual replacement for SBT or Mill - nor was it ever meant to be. We do not call it a build tool, even though it does share some similarities with build tools. It doesn't aim at supporting multi-module
+projects, nor to be extended via a task system. The main advantages of SBT and Mill: multi-module support and plugin ecosystem in the use cases for Scala CLI and scala command can often be disadvantages as it affects performance: configuration needs to be compiled, plugins resolved etc.
+
+Mill and SBT uses turing complete configuration for build so the complexity of build scripts in theory is unlimited. Scala CLI is configuration-only and that limits the complexity what put a hard cap how complex Scala CLI builds can be.
+
+`scala` command should be first and foremost a command line tool. Requirements for a certain project structure or presence configuration files limit SBT and Mill usability certain use cases related to command line.
+
+One of the main requirements for the new `scala` commands was speed, flexibility and focus on command-line use cases. Initially, we were considering improving SBT or Mill as well as building Scala CLI on top one. We have quickly realized that getting Mill or SBT to reply within Milliseconds (for cases where no hard work like compilation is require) would be pretty much out of reach. Mill and SBT's codebases are too big to compile them to native image using GraalVM, not to mention problems with dynamic loading and reflection. Adding flexibility when in comes to input sources (e.g. support for Gists) and making the tool that can accept most of the configuration using simple command-line parameters would involve writhing a lot of glue code. That is why we decided to build the tool from scratch based on existing components like coursier, bloop or scalafmt.
+
+## Proposed solution
+
+We propose to gradually replace the current `scala`, `scalac` and `scaladoc` commands by single `scala` command that under the hood will be `scala-cli`. We could also add wrapper scripts for `scalac` and `scaladoc` that will mimic the functionality that will use `scala-cli` under the hood.
+
+The complete set of `scala-cli` features can be found in [its documentation](https://scala-cli.virtuslab.org/docs/overview).
+
+Scala CLI brings many features like testing, packaging, exporting to sbt / Mill or upcoming support for publishing micro-libraries. Initially, we propose to limit the set of features available in the `scala` command by default. Scala CLI is a relatively new project and we should battle-proof some of its features before we commit to support them as part of the official `scala` command.
+
+Scala CLI offers [multiple native ways to be installed](https://scala-cli.virtuslab.org/install#advanced-installation) so most users should find a suitable method. We propose that these packages to become the default `scala` package in most repositories, often replacing existing `scala` packages but the fact how new `scala` command would be installed is not intended to be a part of this SIP.
+
+### High-level overview
+
+Let us show a few examples where adopting Scala CLI as `scala` command would be a significant improvement over current scripts. For this, we have assumed a minimal set of features (described as MUST have and SHOULD have). Each additional Scala CLI feature included in the future, such as `package`, would add more and more use cases.
+
+**Using REPL with a 3rd-party dependency**
+
+Currently, to start a Scala REPL with a dependency on the class path, users need to resolve this dependency with all its transitive dependencies (coursier can help here) and pass those to the `scala` command using the `--cp` option. Alternatively, one can create an sbt project including a single dependency and use the `sbt console` task. Ammonite gives a better experience with its magic imports.
+
+With Scala CLI, starting a REPL with a given dependency is as simple as running:
+
+```
+scala-cli repl --dep com.lihaoyi::os-lib:0.7.8
+```
+
+Compared to Ammonite, default Scala REPLs provided by Scala 2 and 3 - that Scala CLI uses by default - are somewhat limited. However, Scala CLI also offers to start Ammonite instead of the default Scala REPL, by passing `--ammonite` (or `--amm`) option to `scala-cli repl` but we do not propose to include `--ammonite` to the `scala` command not to commit to its maintenance.
+
+Additionally, `scala-cli repl` can also put code from given files / directories / snippets on the class path by just providing their locations as arguments. Running `scala-cli repl foo.scala baz` will compile code from `foo.scala` and the `baz` directory, and put their classes on the REPL class path (including their dependencies, scalac options etc. defined within those files).
+
+Compilation (and running scaladoc as well) benefit in a similar way from the ability to manage dependencies.
+
+** Providing reproductions of bugs **
+
+Currently, when reporting a bug in the compiler (or any other Scala-related) repository, users need to provide dependencies, compiler options etc. in comments, create a repository containing a projet with a Mill / sbt configuration to reproduce. In general, testing the reproduction or working on further minimization is not straightforward.
+
+"Using directives", provided by Scala CLI give the ability to include the whole configuration in single file, for example:
+
+```scala
+//> using platform "native"
+//> using "com.lihaoyi::os-lib:0.7.8"
+//> using options "-Xfatal-warnings"
+
+def foo = println("")
+```
+
+The snippet above when run with Scala CLI without any configuration provided will use Scala Native, resolve and include `os-lib` and provide `-Xfatal-warnings` to the compiler. Even things such as the runtime JVM version can be configured with using directives.
+
+Moreover, Scala CLI provides the ability to run GitHub gists (including multi-file ones), and more.
+
+** Watch mode **
+
+When working on a piece of code, it is often useful to have it compiled/run every time the file is changed, and build tools offer a watch mode for that. This is how most people are using watch mode through a build tool. Scala CLI offers a watch mode for most of its commands (by using `--watch` / `-w` flags).
+
+
+### Specification
+
+ In order to be able to expand the functionality of Scala CLI and yet use the same core to power the `scala` command, we propose to include both `scala` and `scala-cli` commands in the installation package. Scala CLI already has a feature to limit accessible sub-commands based the binary name (all sub-commands in `scala-cli`, and a curated list in `scala`). On later date, more features from `scala-cli` could be included into `scala` command by additional SIPs or similar processes.
+
+These sub-commands MUST be included in the the specification of the new `scala` command:
+
+ - compile: Compile Scala code
+ - doc: Generate Scaladoc documentation
+ - repl: Fire-up a Scala REPL
+ - run: Compile and run Scala code.
+ - shebang: Like `run`, but more handy from shebang scripts
+
+These sub-commands SHOULD be included in the the specification of the new `scala` command:
+
+ - fmt: Format Scala code
+ - test: Compile and test Scala code
+ - version: Print `scala-cli` version
+
+
+The subcommand that MAY be included in the specification of the new `scala` command. Those sub-commands are specific to implementation of Scala CLI and provide important, user-facing features like integration with IDE or cleaning up incremental compilation state:
+
+ - about: Print details about this application
+ - bsp: Start BSP server
+ - clean: Clean the workspace
+ - doctor: Print details about this application
+ - help: Print help message
+ - install-completions: Installs completions into your shell
+ - install-home: Install `scala-cli` in a sub-directory of the home directory
+ - setup-ide: Generate a BSP file that you can import into your IDE
+ - uninstall: Uninstall scala-cli - only works when installed by the installation script
+ - uninstall-completions: Uninstalls completions from your shell
+ - update: Update scala-cli - only works when installed by the installation script
+
+Last section of this proposal is the list of options that each sub-command MUST HAVE and SHOULD HAVE for each sub-commands that MUST or SHOULD be included in the specification of the new `scala` command. The options that are specific to the implementation (MAY have) as well as options for implementation specific sub-commands (MAY have) are included in [full specification](https://romanowski.github.io/scala-cli/docs/reference/scala-command/runner-specification).
+
+Scala CLI can also be configured with ["using directives"](https://scala-cli.virtuslab.org/docs/guides/introduction/using-directives) - a comment-based configuration syntax that should be placed at the top of Scala files. This allows for self-containing examples within one file since most of the configuration can be provided either from the command line or via using directives (command line has precedence). This is a game changer for use cases like scripting, reproduction, or within the academic scope.
+
+We have described the motivation, syntax and implementation basis in the [dedicated pre-SIP](https://contributors.scala-lang.org/t/pre-sip-using-directives/5700). Currently, we recommend to write using directives as comments, so making them part of the language specification is not necessary at this stage. Moreover, the new `scala` command could ignore using directives in the initial version, however we strongly suggest to include comment-based using directives from the start.
+
+Last section of this proposal contains a sumamry of Using Directives syntax as well as list of directives that MUST and SHOULD be supported.
+
+### Compatibility
+
+Adopting Scala CLI as the new `scala` command, as is, will change some of the behavior of today's scripts. Some examples:
+
+- Scala CLI recognizes tests based on the extension used (`*.test.scala`) so running `scala compile a.scala a.test.scala` will only compile `a.scala`
+- Scala CLI has its own versioning scheme, that is not related to the Scala compiler. Default version used may dynamically change when new Scala version is released. Similarly to Scala 3, we intend for Scala CLI to be backward compatible and this should help mitigate this risk.
+- By default, Scala CLI manages its own dependencies (e.g. scalac, zinc, Bloop) and resolves them lazily. This means that the first run of Scala CLI resolves quite some dependencies. Moreover, Scala CLI periodically checks for updates, new defaults accessing online resources (but it is not required to work, so Scala CLI can work in offline environment once setup)
+- Scala CLI can also be configured via using directives. Command line options have precedence over using directives, however using directives override defaults. Compiling a file starting with `//> using scala 2.13.8`, without providing a Scala version on the command line, will result in using `2.13.8` rather than the default Scala version. We consider this a feature. However, technically, this is a breaking change.
+
+### Other concerns
+
+Scala CLI brings [using directives](https://scala-cli.virtuslab.org/docs/guides/introduction/using-directives) and [conventions to mark the test files](https://scala-cli.virtuslab.org/docs/commands/test#test-sources). We suggest to accept both accepted as a part of this SIP but we are ready to open dedicated SIPs for both (we have opened a [pre-SIP for using directives](https://contributors.scala-lang.org/t/pre-sip-using-directives/5700/15))
+
+Scala CLI is an ambitious project and may seem hard to maintain in the long-run.
+
+
+### Open questions
+
+The release cadence: should the new `scala` command follow the current release cadence for Scala CLI (every 2 weeks) or stick to Scala one (every 6 weeks)?
+
+## Alternatives
+
+Scala CLI has many alternatives. The most obvious ones are sbt, Mill, or other build tools. However, these are more complicated than Scala CLI, and what is more important they are not designed as command-line first tools. Ammonite, is another alternative, however it covers only part of the Scala CLI features (REPL and scripting), and lacks many of the Scala CLI features (incremental compilation, Scala version selection, support for Scala.js and Scala Native, just to name a few).
+
+## Related work
+
+- [Scala CLI website](https://scala-cli.virtuslab.org/) and [road map](https://github.com/VirtusLab/scala-cli/discussions/1101)
+- [Pre-SIP](https://contributors.scala-lang.org/t/pre-sip-scala-cli-as-new-scala-command/5628/22)
+- [leiningen](https://leiningen.org/) - a similar tool from Closure, but more configuration-oriented
+
+## FAQ
+
+This section will probably initially be empty. As discussions on the proposal progress, it is likely that some questions will come repeatedly. They should be listed here, with appropriate answers.
+
+# Scala Runner Specification
+
+This section describes proposed Scala Runner specification and was generated from Scala CLI documentation. It contains `MUST` have and `SHOULD` have commands (each with complete list of MUST have and SHOULD have options) followed by a list of using directives.
+
+## Scalac options
+
+Scala Runner MUST support following options from Scala Compiler directly:
+ - `-encoding`
+ - `-release`
+ - `-color`
+ - `-nowarn`
+ - `-feature`
+ - `-deprecation`
+
+
+ Additionally, all options that start with:
+- `-g`
+- `-language`
+- `-opt`
+- `-P`
+- `-target`
+- `-V`
+- `-W`
+- `-X`
+- `-Y`
+
+SHOULD be treated as be Scala compiler options and be propagated to Scala Compiler. This applies to all commands that uses compiler directly or indirectly.
+
+# MUST have commands
+
+## `compile` command
+
+Compile Scala code
+
+### MUST have options
+
+- `--dependency`, `--dep`: Add dependencies
+- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies
+- `--scala-version`, `--scala`, `-S`: Set the Scala version
+- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version
+- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path
+- `--resource-dirs`, `--resource-dir`: Add a resource directory
+- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path
+### SHOULD have options
+
+- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js`
+- `--js-version`: The Scala.js version
+- `--js-mode`: The Scala.js mode, either `dev` or `release`
+- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none
+- `--js-check-ir`:
+- `--js-emit-source-maps`: Emit source maps
+- `--js-source-maps-path`: Set the destination path of source maps
+- `--js-dom`: Enable jsdom
+- `--js-header`: A header that will be added at the top of generated .js files
+- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021
+- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native`
+- `--native-version`: Set the Scala Native version
+- `--native-mode`: Set Scala Native compilation mode
+- `--native-gc`: Set the Scala Native garbage collector
+- `--native-linking`: Extra options passed to `clang` verbatim during linking
+- `--native-compile`: List of compile options
+- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API)
+- `--repository`, `--repo`, `-r`: Add repositories
+- `--debug`: Turn debugging on
+- `--debug-port`: Debug port (5005 by default)
+- `--debug-mode`: Debug mode (attach by default)
+- `--java-home`: Set the Java home directory
+- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
+- `--javac-plugin`: Javac plugin dependencies or files
+- `--javac-option`, `--javac-opt`: Javac options
+- `--script-snippet`: Allows to execute a passed string as a Scala script
+- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
+- `--scala-snippet`: Allows to execute a passed string as Scala code
+- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
+- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs
+- `--platform`: Specify platform
+- `--semantic-db`: Generate SemanticDBs
+- `--watch`, `-w`: Watch source files for changes
+- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed
+- `--test`: Compile test scope
+---
+
+## `doc` command
+
+Generate Scaladoc documentation
+
+### MUST have options
+
+- `--dependency`, `--dep`: Add dependencies
+- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies
+- `--scala-version`, `--scala`, `-S`: Set the Scala version
+- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version
+- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path
+- `--resource-dirs`, `--resource-dir`: Add a resource directory
+- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path
+- `--output`, `-o`: Set the destination path
+- `--force`, `-f`: Overwrite the destination directory, if it exists
+### SHOULD have options
+
+- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js`
+- `--js-version`: The Scala.js version
+- `--js-mode`: The Scala.js mode, either `dev` or `release`
+- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none
+- `--js-check-ir`:
+- `--js-emit-source-maps`: Emit source maps
+- `--js-source-maps-path`: Set the destination path of source maps
+- `--js-dom`: Enable jsdom
+- `--js-header`: A header that will be added at the top of generated .js files
+- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021
+- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native`
+- `--native-version`: Set the Scala Native version
+- `--native-mode`: Set Scala Native compilation mode
+- `--native-gc`: Set the Scala Native garbage collector
+- `--native-linking`: Extra options passed to `clang` verbatim during linking
+- `--native-compile`: List of compile options
+- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API)
+- `--repository`, `--repo`, `-r`: Add repositories
+- `--debug`: Turn debugging on
+- `--debug-port`: Debug port (5005 by default)
+- `--debug-mode`: Debug mode (attach by default)
+- `--java-home`: Set the Java home directory
+- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
+- `--javac-plugin`: Javac plugin dependencies or files
+- `--javac-option`, `--javac-opt`: Javac options
+- `--script-snippet`: Allows to execute a passed string as a Scala script
+- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
+- `--scala-snippet`: Allows to execute a passed string as Scala code
+- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
+- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs
+- `--platform`: Specify platform
+- `--semantic-db`: Generate SemanticDBs
+- `--default-scaladoc-options`, `--default-scaladoc-opts`: Control if scala CLI should use default options for scaladoc, true by default. Use `--default-scaladoc-opts:false` to not include default options.
+---
+
+## `repl` command
+
+Aliases: `console`
+
+Fire-up a Scala REPL
+
+### MUST have options
+
+- `--dependency`, `--dep`: Add dependencies
+- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies
+- `--scala-version`, `--scala`, `-S`: Set the Scala version
+- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version
+- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path
+- `--resource-dirs`, `--resource-dir`: Add a resource directory
+- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path
+- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g`
+- `--java-prop`: Set Java properties
+
+### SHOULD have options
+
+- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js`
+- `--js-version`: The Scala.js version
+- `--js-mode`: The Scala.js mode, either `dev` or `release`
+- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none
+- `--js-check-ir`:
+- `--js-emit-source-maps`: Emit source maps
+- `--js-source-maps-path`: Set the destination path of source maps
+- `--js-dom`: Enable jsdom
+- `--js-header`: A header that will be added at the top of generated .js files
+- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021
+- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native`
+- `--native-version`: Set the Scala Native version
+- `--native-mode`: Set Scala Native compilation mode
+- `--native-gc`: Set the Scala Native garbage collector
+- `--native-linking`: Extra options passed to `clang` verbatim during linking
+- `--native-compile`: List of compile options
+- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API)
+- `--repository`, `--repo`, `-r`: Add repositories
+- `--debug`: Turn debugging on
+- `--debug-port`: Debug port (5005 by default)
+- `--debug-mode`: Debug mode (attach by default)
+- `--java-home`: Set the Java home directory
+- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
+- `--javac-plugin`: Javac plugin dependencies or files
+- `--javac-option`, `--javac-opt`: Javac options
+- `--script-snippet`: Allows to execute a passed string as a Scala script
+- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
+- `--scala-snippet`: Allows to execute a passed string as Scala code
+- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
+- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs
+- `--platform`: Specify platform
+- `--semantic-db`: Generate SemanticDBs
+- `--watch`, `-w`: Watch source files for changes
+- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed
+
+---
+
+## `run` command
+
+Compile and run Scala code.
+
+To pass arguments to the application, just add them after `--`, like:
+
+```sh
+scala-cli MyApp.scala -- first-arg second-arg
+```
+
+### MUST have options
+
+- `--dependency`, `--dep`: Add dependencies
+- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies
+- `--scala-version`, `--scala`, `-S`: Set the Scala version
+- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version
+- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path
+- `--resource-dirs`, `--resource-dir`: Add a resource directory
+- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path
+- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g`
+- `--java-prop`: Set Java properties
+- `--main-class`, `-M`: Specify which main class to run
+
+### SHOULD have options
+
+- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js`
+- `--js-version`: The Scala.js version
+- `--js-mode`: The Scala.js mode, either `dev` or `release`
+- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none
+- `--js-check-ir`:
+- `--js-emit-source-maps`: Emit source maps
+- `--js-source-maps-path`: Set the destination path of source maps
+- `--js-dom`: Enable jsdom
+- `--js-header`: A header that will be added at the top of generated .js files
+- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021
+- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native`
+- `--native-version`: Set the Scala Native version
+- `--native-mode`: Set Scala Native compilation mode
+- `--native-gc`: Set the Scala Native garbage collector
+- `--native-linking`: Extra options passed to `clang` verbatim during linking
+- `--native-compile`: List of compile options
+- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API)
+- `--repository`, `--repo`, `-r`: Add repositories
+- `--debug`: Turn debugging on
+- `--debug-port`: Debug port (5005 by default)
+- `--debug-mode`: Debug mode (attach by default)
+- `--java-home`: Set the Java home directory
+- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
+- `--javac-plugin`: Javac plugin dependencies or files
+- `--javac-option`, `--javac-opt`: Javac options
+- `--script-snippet`: Allows to execute a passed string as a Scala script
+- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
+- `--scala-snippet`: Allows to execute a passed string as Scala code
+- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
+- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs
+- `--platform`: Specify platform
+- `--semantic-db`: Generate SemanticDBs
+- `--watch`, `-w`: Watch source files for changes
+- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed
+- `--main-class-ls`, `--main-class-list`, `--list-main-class`, `--list-main-classes`: List main classes available in the current context
+- `--command`: Print the command that would have been run (one argument per line), rather than running it
+
+---
+
+## `shebang` command
+
+Like `run`, but more handy from shebang scripts
+
+This command is equivalent to `run`, but it changes the way
+`scala-cli` parses its command-line arguments in order to be compatible
+with shebang scripts.
+
+Normally, inputs and scala-cli options can be mixed. Program have to be specified after `--`
+
+```sh
+scala-cli [command] [scala_cli_options | input]... -- [program_arguments]...
+```
+
+Contrary, for shebang command, only a single input file can be set, all scala-cli options
+have to be set before the input file, and program arguments after the input file
+```sh
+scala-cli shebang [scala_cli_options]... input [program_arguments]...
+```
+
+Using this, it is possible to conveniently set up Unix shebang scripts. For example:
+```sh
+#!/usr/bin/env -S scala-cli shebang --scala-version 2.13
+println("Hello, world)
+```
+
+### MUST have options
+
+- `--dependency`, `--dep`: Add dependencies
+- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies
+- `--scala-version`, `--scala`, `-S`: Set the Scala version
+- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version
+- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path
+- `--resource-dirs`, `--resource-dir`: Add a resource directory
+- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path
+- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g`
+- `--java-prop`: Set Java properties
+- `--main-class`, `-M`: Specify which main class to run
+
+### SHOULD have options
+
+- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js`
+- `--js-version`: The Scala.js version
+- `--js-mode`: The Scala.js mode, either `dev` or `release`
+- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none
+- `--js-check-ir`:
+- `--js-emit-source-maps`: Emit source maps
+- `--js-source-maps-path`: Set the destination path of source maps
+- `--js-dom`: Enable jsdom
+- `--js-header`: A header that will be added at the top of generated .js files
+- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021
+- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native`
+- `--native-version`: Set the Scala Native version
+- `--native-mode`: Set Scala Native compilation mode
+- `--native-gc`: Set the Scala Native garbage collector
+- `--native-linking`: Extra options passed to `clang` verbatim during linking
+- `--native-compile`: List of compile options
+- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API)
+- `--repository`, `--repo`, `-r`: Add repositories
+- `--debug`: Turn debugging on
+- `--debug-port`: Debug port (5005 by default)
+- `--debug-mode`: Debug mode (attach by default)
+- `--java-home`: Set the Java home directory
+- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
+- `--javac-plugin`: Javac plugin dependencies or files
+- `--javac-option`, `--javac-opt`: Javac options
+- `--script-snippet`: Allows to execute a passed string as a Scala script
+- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
+- `--scala-snippet`: Allows to execute a passed string as Scala code
+- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
+- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs
+- `--platform`: Specify platform
+- `--semantic-db`: Generate SemanticDBs
+- `--watch`, `-w`: Watch source files for changes
+- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed
+- `--main-class-ls`, `--main-class-list`, `--list-main-class`, `--list-main-classes`: List main classes available in the current context
+- `--command`: Print the command that would have been run (one argument per line), rather than running it
+
+---
+
+# SHOULD have commands
+
+## `fmt` command
+
+Aliases: `format`, `scalafmt`
+
+Format Scala code
+
+### MUST have options
+
+- `--dependency`, `--dep`: Add dependencies
+- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies
+- `--scala-version`, `--scala`, `-S`: Set the Scala version
+- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version
+- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path
+- `--resource-dirs`, `--resource-dir`: Add a resource directory
+- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path
+### SHOULD have options
+
+- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js`
+- `--js-version`: The Scala.js version
+- `--js-mode`: The Scala.js mode, either `dev` or `release`
+- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none
+- `--js-check-ir`:
+- `--js-emit-source-maps`: Emit source maps
+- `--js-source-maps-path`: Set the destination path of source maps
+- `--js-dom`: Enable jsdom
+- `--js-header`: A header that will be added at the top of generated .js files
+- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021
+- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native`
+- `--native-version`: Set the Scala Native version
+- `--native-mode`: Set Scala Native compilation mode
+- `--native-gc`: Set the Scala Native garbage collector
+- `--native-linking`: Extra options passed to `clang` verbatim during linking
+- `--native-compile`: List of compile options
+- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API)
+- `--repository`, `--repo`, `-r`: Add repositories
+- `--debug`: Turn debugging on
+- `--debug-port`: Debug port (5005 by default)
+- `--debug-mode`: Debug mode (attach by default)
+- `--java-home`: Set the Java home directory
+- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
+- `--javac-plugin`: Javac plugin dependencies or files
+- `--javac-option`, `--javac-opt`: Javac options
+- `--script-snippet`: Allows to execute a passed string as a Scala script
+- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
+- `--scala-snippet`: Allows to execute a passed string as Scala code
+- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
+- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs
+- `--platform`: Specify platform
+- `--semantic-db`: Generate SemanticDBs
+- `--check`: Check if sources are well formatted
+
+---
+
+## `test` command
+
+Compile and test Scala code
+
+### MUST have options
+
+- `--dependency`, `--dep`: Add dependencies
+- `--compiler-plugin`, `-P`, `--plugin`: Add compiler plugin dependencies
+- `--scala-version`, `--scala`, `-S`: Set the Scala version
+- `--scala-binary-version`, `--scala-binary`, `--scala-bin`, `-B`: Set the Scala binary version
+- `--extra-jars`, `--jar`, `--jars`, `--extra-jar`, `--class`, `--extra-class`, `--classes`, `--extra-classes`, `-classpath`, `-cp`, `--classpath`, `--class-path`, `--extra-class-path`: Add extra JARs and compiled classes to the class path
+- `--resource-dirs`, `--resource-dir`: Add a resource directory
+- `--compilation-output`, `--output-directory`, `-d`, `--destination`, `--compile-output`, `--compile-out`: Copy compilation results to output directory using either relative or absolute path
+- `--java-opt`, `-J`: Set Java options, such as `-Xmx1g`
+- `--java-prop`: Set Java properties
+### SHOULD have options
+
+- `--js`: Enable Scala.js. To show more options for Scala.js pass `--help-js`
+- `--js-version`: The Scala.js version
+- `--js-mode`: The Scala.js mode, either `dev` or `release`
+- `--js-module-kind`: The Scala.js module kind: commonjs/common, esmodule/es, nomodule/none
+- `--js-check-ir`:
+- `--js-emit-source-maps`: Emit source maps
+- `--js-source-maps-path`: Set the destination path of source maps
+- `--js-dom`: Enable jsdom
+- `--js-header`: A header that will be added at the top of generated .js files
+- `--js-es-version`: The Scala.js ECMA Script version: es5_1, es2015, es2016, es2017, es2018, es2019, es2020, es2021
+- `--native`: Enable Scala Native. To show more options for Scala Native pass `--help-native`
+- `--native-version`: Set the Scala Native version
+- `--native-mode`: Set Scala Native compilation mode
+- `--native-gc`: Set the Scala Native garbage collector
+- `--native-linking`: Extra options passed to `clang` verbatim during linking
+- `--native-compile`: List of compile options
+- `--embed-resources`: Embed resources into the Scala Native binary (can be read with the Java resources API)
+- `--repository`, `--repo`, `-r`: Add repositories
+- `--debug`: Turn debugging on
+- `--debug-port`: Debug port (5005 by default)
+- `--debug-mode`: Debug mode (attach by default)
+- `--java-home`: Set the Java home directory
+- `--jvm`, `-j`: Use a specific JVM, such as `14`, `adopt:11`, or `graalvm:21`, or `system`
+- `--javac-plugin`: Javac plugin dependencies or files
+- `--javac-option`, `--javac-opt`: Javac options
+- `--script-snippet`: Allows to execute a passed string as a Scala script
+- `--execute-script`, `--execute-scala-script`, `--execute-sc`, `-e`: A synonym to --script-snippet, which defaults the sub-command to `run` when no sub-command is passed explicitly
+- `--scala-snippet`: Allows to execute a passed string as Scala code
+- `--extra-compile-only-jars`, `--compile-only-jar`, `--compile-only-jars`, `--extra-compile-only-jar`: Add extra JARs in the compilaion class path. Mainly using to run code in managed environments like Spark not to include certain depenencies on runtime ClassPath.
+- `--extra-source-jars`, `--source-jar`, `--source-jars`, `--extra-source-jar`: Add extra source JARs
+- `--platform`: Specify platform
+- `--semantic-db`: Generate SemanticDBs
+- `--watch`, `-w`: Watch source files for changes
+- `--restart`, `--revolver`: Run your application in background and automatically restart if sources have been changed
+- `--test-framework`: Name of the test framework's runner class to use while running tests
+- `--require-tests`: Fail if no test suites were run
+---
+
+# Using Directives
+
+
+As a part of this SIP we propose to introduce Using Directives, a special comments containing configuration. Withing Scala CLI and by extension `scala` command, the command line arguments takes precedence over using directives.
+
+Using directives can be place on only top of the file (above imports, package definition etx.) and can be proceed only by plain comments (e.g. to comment out an using directive)
+
+Comments containing directives needs to start by `//>`, for example:
+
+```
+//> using scala 3
+//> using platform scala-js
+//> using options -Xasync
+```
+
+We propose following sytax for Using Directives (within special comments described above):
+
+```
+UsingDirective ::= "using" Setting
+Setting ::= Ident ( Value | Values )
+Ident ::= ScalaIdent { "." ScalaIdent }
+Values ::= Value { " " [","] Values }
+Value ::= Ident | stringLiteral | numericLiteral | true | false
+```
+
+Where:
+
+- Ident is the standard Scala identifier or list of identifiers separated by dots:
+
+```
+foo
+
+foo.bar
+
+`foo-bar`.bazz
+```
+
+- String literals and numeric literals are similar to Scala.
+- No value after the identifier is treated as true value: `using scalaSettings.fatalWarnings`
+- Specifying a setting with the same path more than once and specifying the same setting with a list of values are equivalent
+
+The list of proposed directives split into MUST have and SHOULD have groups:
+
+## MUST have directives:
+
+ - `option`, `options`: Add Scala compiler options
+ - `plugin`, `plugins`: Adds compiler plugins
+ - `lib`, `libs`: Add dependencies
+ - `javaOpt`, `javaOptions`, `java-opt`, `java-options`: Add Java options which will be passed when running an application.
+ - `javaProp`: Add Java properties
+ - `main-class`, `mainClass`: Specify default main class
+ - `scala`: Set the default Scala version
+## SHOULD have directives:
+
+ - `jar`, `jars`: Manually add JAR(s) to the class path
+ - `file`, `files`: Manually add sources to the Scala CLI project
+ - `java-home`, `javaHome`: Sets Java home used to run your application or tests
+ - `javacOpt`, `javacOptions`, `javac-opt`, `javac-options`: Add Javac options which will be passed when compiling sources.
+ - `platform`, `platforms`: Set the default platform to Scala.js or Scala Native
+ - `repository`, `repositories`: Add a repository for dependency resolution
+ - `resourceDir`, `resourceDirs`: Manually add a resource directory to the class path
+ - `native-gc`, `native-mode`, `native-version`, `native-compile`, `native-linking`, `native-clang`, `native-clang-pp`, `native-no-embed`, `nativeGc`, `nativeMode`, `nativeVersion`, `nativeCompile`, `nativeLinking`, `nativeClang`, `nativeClangPP`, `nativeEmbedResources`: Add Scala Native options
+ - `jsVersion`, `jsMode`, `jsModuleKind`, `jsCheckIr`, `jsEmitSourceMaps`, `jsSmallModuleForPackage`, `jsDom`, `jsHeader`, `jsAllowBigIntsForLongs`, `jsAvoidClasses`, `jsAvoidLetsAndConsts`, `jsModuleSplitStyleStr`, `jsEsVersionStr`: Add Scala.js options
+ - `test-framework`, `testFramework`: Set the test framework
diff --git a/_sips/sips/2009-05-28-scala-compiler-phase-plugin-in.md b/_sips/sips/scala-compiler-phase-plugin-in.md
similarity index 76%
rename from _sips/sips/2009-05-28-scala-compiler-phase-plugin-in.md
rename to _sips/sips/scala-compiler-phase-plugin-in.md
index 8d854921c3..24f0330e91 100644
--- a/_sips/sips/2009-05-28-scala-compiler-phase-plugin-in.md
+++ b/_sips/sips/scala-compiler-phase-plugin-in.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-2 Scala Compiler Phase and Plug-In Initialization for Scala 2.8
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/scala-compiler-phase-plugin-in.html
---
diff --git a/_sips/sips/2010-05-06-scala-specialization.md b/_sips/sips/scala-specialization.md
similarity index 72%
rename from _sips/sips/2010-05-06-scala-specialization.md
rename to _sips/sips/scala-specialization.md
index dc3afd5caf..d9bd06e36e 100644
--- a/_sips/sips/2010-05-06-scala-specialization.md
+++ b/_sips/sips/scala-specialization.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-9 - Scala Specialization
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/scala-specialization.html
---
diff --git a/_sips/sips/2009-11-02-scala-swing-overview.md b/_sips/sips/scala-swing-overview.md
similarity index 72%
rename from _sips/sips/2009-11-02-scala-swing-overview.md
rename to _sips/sips/scala-swing-overview.md
index 497ae502e6..a539dc352c 100644
--- a/_sips/sips/2009-11-02-scala-swing-overview.md
+++ b/_sips/sips/scala-swing-overview.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-8 - Scala Swing Overview
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/scala-swing-overview.html
---
diff --git a/_sips/sips/sealed-types.md b/_sips/sips/sealed-types.md
new file mode 100644
index 0000000000..04754c6be7
--- /dev/null
+++ b/_sips/sips/sealed-types.md
@@ -0,0 +1,6 @@
+---
+title: SIP-41 - Sealed Types
+status: withdrawn
+pull-request-number: 43
+
+---
diff --git a/_sips/sips/self-cleaning-macros.md b/_sips/sips/self-cleaning-macros.md
new file mode 100644
index 0000000000..056a674a38
--- /dev/null
+++ b/_sips/sips/self-cleaning-macros.md
@@ -0,0 +1,6 @@
+---
+title: SIP-16 - Self-cleaning Macros
+status: rejected
+pull-request-number: 15
+
+---
diff --git a/_sips/sips/spores.md b/_sips/sips/spores.md
new file mode 100644
index 0000000000..2b9c51d5a3
--- /dev/null
+++ b/_sips/sips/spores.md
@@ -0,0 +1,6 @@
+---
+title: SIP-21 - Spores
+status: withdrawn
+pull-request-number: 20
+
+---
diff --git a/_sips/sips/2016-01-11-static-members.md b/_sips/sips/static-members.md
similarity index 98%
rename from _sips/sips/2016-01-11-static-members.md
rename to _sips/sips/static-members.md
index f36cc89d7d..1c0df79d75 100644
--- a/_sips/sips/2016-01-11-static-members.md
+++ b/_sips/sips/static-members.md
@@ -1,13 +1,15 @@
---
layout: sip
title: SIP-30 - @static fields and methods in Scala objects (SI-4581)
-vote-status: "under-review"
-vote-text: Authors need to update the proposal before the next review.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/static-members.html
---
-__Dmitry Petrashko, Sébastien Doeraene and Martin Odersky__
+> This proposal has been implemented in Scala 3.0.0
+
+**Authors: Dmitry Petrashko, Sébastien Doeraene and Martin Odersky**
__first submitted 11 January 2016__
diff --git a/_sips/sips/2011-10-13-string-interpolation.md b/_sips/sips/string-interpolation.md
similarity index 69%
rename from _sips/sips/2011-10-13-string-interpolation.md
rename to _sips/sips/string-interpolation.md
index 69b807a6da..f1343fdb22 100644
--- a/_sips/sips/2011-10-13-string-interpolation.md
+++ b/_sips/sips/string-interpolation.md
@@ -1,9 +1,9 @@
---
layout: sip
title: SIP-11 - String Interpolation
-
+stage: completed
+status: shipped
vote-status: complete
-vote-text: This SIP has already been accepted and completed. We expect a SIP for 2.11 that will allow the desugared form of interpolated strings in the pattern matcher to become valid syntax. This SIP only allows the sugared interpolated strings to work.
permalink: /sips/:title.html
redirect_from: /sips/pending/string-interpolation.html
---
diff --git a/_sips/sips/struct-classes.md b/_sips/sips/struct-classes.md
new file mode 100644
index 0000000000..a9109fd45b
--- /dev/null
+++ b/_sips/sips/struct-classes.md
@@ -0,0 +1,6 @@
+---
+title: SIP-50 - Struct Classes
+status: withdrawn
+pull-request-number: 50
+
+---
diff --git a/_sips/sips/2016-06-25-trailing-commas.md b/_sips/sips/trailing-commas.md
similarity index 97%
rename from _sips/sips/2016-06-25-trailing-commas.md
rename to _sips/sips/trailing-commas.md
index 1116621487..7eef93dd03 100644
--- a/_sips/sips/2016-06-25-trailing-commas.md
+++ b/_sips/sips/trailing-commas.md
@@ -1,12 +1,14 @@
---
-layout: inner-page-no-masthead
+layout: sip
title: SIP-27 - Trailing Commas
-vote-status: complete
-vote-text: This SIP has already been accepted and completed, and is a part of Scala 2.12.2.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/trailing-commas.html
---
+> This proposal has been shipped in Scala 2.12.2.
+
**By: Dale Wijnand**
## History
diff --git a/_sips/sips/2015-6-18-trait-parameters.md b/_sips/sips/trait-parameters.md
similarity index 94%
rename from _sips/sips/2015-6-18-trait-parameters.md
rename to _sips/sips/trait-parameters.md
index 6abef5c4b8..633f0c0b73 100644
--- a/_sips/sips/2015-6-18-trait-parameters.md
+++ b/_sips/sips/trait-parameters.md
@@ -1,12 +1,14 @@
---
layout: sip
title: SIP-25 - Trait Parameters
-vote-status: accepted
-vote-text: Trait parameters are implemented in Scala 3.0.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/trait-parameters.html
---
+> This proposal has been implemented in Scala 3.0.
+
__Martin Odersky__
__first submitted 18 June 2015__
@@ -67,4 +69,4 @@ the evaluation order would be `e1`, initializer of `T`, `e2`, initializer of `V`
## See Also ##
-[Dotty Issue #640](https://github.com/lampepfl/dotty/issues/640)
+[Dotty Issue #640](https://github.com/scala/scala3/issues/640)
diff --git a/_sips/sips/2012-03-13-type-dynamic.md b/_sips/sips/type-dynamic.md
similarity index 85%
rename from _sips/sips/2012-03-13-type-dynamic.md
rename to _sips/sips/type-dynamic.md
index 37385c3c02..c359ec0627 100644
--- a/_sips/sips/2012-03-13-type-dynamic.md
+++ b/_sips/sips/type-dynamic.md
@@ -1,9 +1,8 @@
---
layout: sip
title: SIP-17 - Type Dynamic
-
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/type-dynamic.html
---
diff --git a/_sips/sips/typeclasses-syntax.md b/_sips/sips/typeclasses-syntax.md
new file mode 100644
index 0000000000..38dcba9293
--- /dev/null
+++ b/_sips/sips/typeclasses-syntax.md
@@ -0,0 +1,685 @@
+---
+layout: sip
+stage: completed
+status: shipped
+presip-thread: https://contributors.scala-lang.org/t/pre-sip-improve-syntax-for-context-bounds-and-givens/6576/97
+title: SIP-64 - Improve Syntax for Context Bounds and Givens
+---
+
+**By: Martin Odersky**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| March 11, 2024| Initial Draft |
+| July 18, 2024 | Revised Draft |
+
+## Summary
+
+We propose some syntactic improvements that make context bounds and given clauses more
+expressive and easier to read. The proposed additions and changes comprise:
+
+ - naming context bounds, as in `A: Monoid as a`,
+ - a new syntax for multiple context bounds, as in `A: {Monoid, Ord}`,
+ - context bounds for type members,
+ - replacing abstract givens with a more powerful and convenient mechanism,
+ - a cleaner syntax for given definitions that eliminates some syntactic warts.
+
+## Motivation
+
+This SIP is part of an effort to get state-of-the art typeclasses and generic in Scala. It fixes several existing pain points:
+
+ - The inability to name context bounds causes awkward and obscure workarounds in practice.
+ - The syntax for multiple context bounds is not very clear or readable.
+ - The existing syntax for givens is unfortunate, which hinders learning and adoption.
+ - Abstract givens are hard to specify and implement and their syntax is easily confused
+ with simple concrete givens.
+
+These pain points are worth fixing on their own, independently of any other proposed improvements to typeclass support. What's more, the changes
+are time sensitive since they affect existing syntax that was introduced in 3.0, so it's better to make the change at a time when not that much code using the new syntax is written yet.
+
+## Proposed Solution
+
+### 1. Naming Context Bounds
+
+Context bounds are a convenient and legible abbreviation. A problem so far is that they are always anonymous, one cannot name the implicit parameter to which a context bound expands. For instance, consider the classical pair of type classes
+```scala
+ trait SemiGroup[A]:
+ extension (x: A) def combine(y: A): A
+
+ trait Monoid[A] extends SemiGroup[A]:
+ def unit: A
+```
+and a `reduce` method defined like this:
+```scala
+def reduce[A : Monoid](xs: List[A]): A = ???
+```
+Since we don't have a name for the `Monoid` instance of `A`, we need to resort to `summon` in the body of `reduce`:
+```scala
+def reduce[A : Monoid](xs: List[A]): A =
+ xs.foldLeft(summon[Monoid[A]].unit)(_ `combine` _)
+```
+That's generally considered too painful to write and read, hence people usually adopt one of two alternatives. Either, eschew context bounds and switch to using clauses:
+```scala
+def reduce[A](xs: List[A])(using m: Monoid[A]): A =
+ xs.foldLeft(m.unit)(_ `combine` _)
+```
+Or, plan ahead and define a "trampoline" method in `Monoid`'s companion object:
+```scala
+ trait Monoid[A] extends SemiGroup[A]:
+ def unit: A
+ object Monoid:
+ def unit[A](using m: Monoid[A]): A = m.unit
+ ...
+ def reduce[A : Monoid](xs: List[A]): A =
+ xs.foldLeft(Monoid.unit)(_ `combine` _)
+```
+This is all accidental complexity which can be avoided by the following proposal.
+
+**Proposal:** Allow to name a context bound, like this:
+```scala
+ def reduce[A : Monoid as m](xs: List[A]): A =
+ xs.foldLeft(m.unit)(_ `combine` _)
+```
+
+We use `as x` after the type to bind the instance to `x`. This is analogous to import renaming, which also introduces a new name for something that comes before.
+
+**Benefits:** The new syntax is simple and clear. It avoids the awkward choice between concise context bounds that can't be named and verbose using clauses that can.
+
+### 2. New Syntax for Aggregate Context Bounds
+
+Aggregate context bounds like `A : X : Y` are not obvious to read, and it becomes worse when we add names, e.g. `A : X as x : Y as y`.
+
+**Proposal:** Allow to combine several context bounds inside `{...}`, analogous
+to import clauses. Example:
+
+```scala
+ trait A:
+ def showMax[X : {Ordering, Show}](x: X, y: X): String
+ class B extends A:
+ def showMax[X : {Ordering as ordering, Show as show}](x: X, y: X): String =
+ show.asString(ordering.max(x, y))
+```
+
+The old syntax with multiple `:` should be phased out over time. There's more about migration at the end of this SIP.
+
+
+### 3. Expansion of Context Bounds
+
+With named context bounds, we need a revision to how the witness parameters of such bounds are added. Context bounds are currently translated to implicit parameters in the last parameter list of a method or class. This is a problem if a context bound is mentioned in one of the preceding parameter types. For example, consider a type class of parsers with associated type members `Input` and `Result` describing the input type on which the parsers operate and the type of results they produce:
+```scala
+trait Parser[P]:
+ type Input
+ type Result
+```
+Here is a method `run` that runs a parser on an input of the required type:
+```scala
+def run[P : Parser as p](in: p.Input): p.Result
+```
+With the current translation this does not work since it would be expanded to:
+```scala
+ def run[P](x: p.Input)(using p: Parser[P]): p.Result
+```
+Note that the `p` in `p.Input` refers to the `p` introduced in the using clause, which comes later. So this is ill-formed.
+
+This problem would be fixed by changing the translation of context bounds so that they expand to using clauses immediately after the type parameter. But such a change is infeasible, for two reasons:
+
+ 1. It would be a source- and binary-incompatible change. We cannot simply change the expansion of existing using clauses because
+ then clients that pass explicit using arguments would no longer work.
+ 2. Putting using clauses earlier can impair type inference. A type in
+ a using clause can be constrained by term arguments coming before that
+ clause. Moving the using clause first would miss those constraints, which could cause ambiguities in implicit search.
+
+But there is an alternative which is feasible:
+
+**Proposal:** Map the context bounds of a method or class as follows:
+
+ 1. If one of the bounds is referred to by its term name in a subsequent parameter clause, the context bounds are mapped to a using clause immediately preceding the first such parameter clause.
+ 2. Otherwise, if the last parameter clause is a using (or implicit) clause, merge all parameters arising from context bounds in front of that clause, creating a single using clause.
+ 3. Otherwise, let the parameters arising from context bounds form a new using clause at the end.
+
+Rules (2) and (3) are the status quo, and match Scala 2's rules. Rule (1) is new but since context bounds so far could not be referred to, it does not apply to legacy code. Therefore, binary compatibility is maintained.
+
+**Discussion** More refined rules could be envisaged where context bounds are spread over different using clauses so that each comes as late as possible. But it would make matters more complicated and the gain in expressiveness is not clear to me.
+
+
+### 4. Context Bounds for Type Members, Deferred Givens
+
+It's not very orthogonal to allow subtype bounds for both type parameters and abstract type members, but context bounds only for type parameters. What's more, we don't even have the fallback of an explicit using clause for type members. The only alternative is to also introduce a set of abstract givens that get implemented in each subclass. This is extremely heavyweight and opaque to newcomers.
+
+**Proposal**: Allow context bounds for type members. Example:
+
+```scala
+ class Collection:
+ type Element : Ord
+```
+
+The question is how these bounds are expanded. Context bounds on type parameters
+are expanded into using clauses. But for type members this does not work, since we cannot refer to a member type of a class in a parameter type of that class. What we are after is an equivalent of using parameter clauses but represented as class members.
+
+**Proposal:**
+Introduce a new way to implement a given definition in a trait like this:
+```scala
+given T = deferred
+```
+`deferred` is a new method in the `scala.compiletime` package, which can appear only as the right hand side of a given defined in a trait. Any class implementing that trait will provide an implementation of this given. If a definition is not provided explicitly, it will be synthesized by searching for a given of type `T` in the scope of the inheriting class. Specifically, the scope in which this given will be searched is the environment of that class augmented by its parameters but not containing its members (since that would lead to recursive resolutions). If an implementation _is_ provided explicitly, it counts as an override of a concrete definition and needs an `override` modifier.
+
+Deferred givens allow a clean implementation of context bounds in traits,
+as in the following example:
+```scala
+trait Sorted:
+ type Element : Ord
+
+class SortedSet[A : Ord] extends Sorted:
+ type Element = A
+```
+The compiler expands this to the following implementation.
+```scala
+trait Sorted:
+ type Element
+ given Ord[Element] = compiletime.deferred
+
+class SortedSet[A](using evidence$0: Ord[A]) extends Sorted:
+ type Element = A
+ override given Ord[Element] = evidence$0
+```
+
+The using clause in class `SortedSet` provides an implementation for the deferred given in trait `Sorted`.
+
+**Benefits:**
+
+ - Better orthogonality, type parameters and abstract type members now accept the same kinds of bounds.
+ - Better ergonomics, since deferred givens get naturally implemented in inheriting classes, no need for boilerplate to fill in definitions of abstract givens.
+
+**Alternative:** It was suggested that we use a modifier for a deferred given instead of a `= deferred`. Something like `deferred given C[T]`. But a modifier does not suggest the concept that a deferred given will be implemented automatically in subclasses unless an explicit definition is written. In a sense, we can see `= deferred` as the invocation of a magic macro that is provided by the compiler. So from a user's point of view a given with `deferred` right hand side is not abstract.
+It is a concrete definition where the compiler will provide the correct implementation. And if users want to provide their own overriding
+implementations, they will need an explicit `override` modifier.
+
+### 5. Abolish Abstract Givens
+
+With `deferred` givens there is no need anymore to also define abstract givens. The two mechanisms are very similar, but the user experience for
+deferred givens is generally more ergonomic. Abstract givens also are uncomfortably close to concrete class instances. Their syntax clashes
+with the quite common case where we want to establish a given without any nested definitions. For instance, consider a given that constructs a type tag:
+```scala
+class Tag[T]
+```
+Then this works:
+```scala
+given Tag[String]()
+given Tag[String] with {}
+```
+But the following more natural syntax fails:
+```scala
+given Tag[String]
+```
+The last line gives a rather cryptic error:
+```
+1 |given Tag[String]
+ | ^
+ | anonymous given cannot be abstract
+```
+The underlying problem is that abstract givens are very rare (and should become completely unnecessary once deferred givens are introduced), yet occupy a syntax that looks very close to the more common case of concrete
+typeclasses without nested definitions.
+
+**Proposal:** In the future, let the `= deferred` mechanism be the only way to deliver the functionality of abstract givens. Deprecate the current version of abstract givens, and remove them in a future Scala version.
+
+**Benefits:**
+
+ - Simplification of the language since a feature is dropped
+ - Eliminate non-obvious and misleading syntax.
+
+The only downside is that deferred givens are restricted to be used in traits, whereas abstract givens are also allowed in abstract classes. But I would be surprised if actual code relied on that difference, and such code could in any case be easily rewritten to accommodate the restriction.
+
+
+### 6. Context Bounds for Polymorphic Functions
+
+Currently, context bounds can be used in methods, but not in function types or function literals. It would be nice propose to drop this irregularity and allow context bounds also in these places. Example:
+
+```scala
+type Comparer = [X: Ord] => (x: X, y: X) => Boolean
+val less: Comparer = [X: Ord as ord] => (x: X, y: X) =>
+ ord.compare(x, y) < 0
+```
+
+The expansion of such context bounds is analogous to the expansion in method types, except that instead of adding a using clause in a method, we insert a context function type.
+
+For instance, the `type` and `val` definitions above would expand to
+```scala
+type Comparer = [X] => (x: X, y: X) => Ord[X] ?=> Boolean
+val less: Comparer = [X] => (x: X, y: X) => (ord: Ord[X]) ?=>
+ ord.compare(x, y) < 0
+```
+
+The expansion of using clauses does look inside alias types. For instance,
+here is a variation of the previous example that uses a parameterized type alias:
+```scala
+type Cmp[X] = (x: X, y: X) => Ord[X] ?=> Boolean
+type Comparer2 = [X: Ord] => Cmp[X]
+```
+The expansion of the right hand side of `Comparer2` expands the `Cmp[X]` alias
+and then inserts the context function at the same place as what's done for `Comparer`.
+
+### 7. Cleanup of Given Syntax
+
+A good language syntax is like a Bach fugue: A small set of motifs is combined in a multitude of harmonic ways. Dissonances and irregularities should be avoided.
+
+When designing Scala 3, I believe that, by and large, we achieved that goal, except in one area, which is the syntax of givens. There _are_ some glaring dissonances, as seen in this code for defining an ordering on lists:
+```scala
+given [A](using Ord[A]): Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+```
+The `:` feels utterly foreign in this position. It's definitely not a type ascription, so what is its role? Just as bad is the trailing `with`. Everywhere else we use braces or trailing `:` to start a scope of nested definitions, so the need of `with` sticks out like a sore thumb.
+
+Sometimes unconventional syntax grows on you and becomes natural after a while. But here it was unfortunately the opposite. The longer I used given definitions in this style the more awkward they felt, in particular since the rest of the language seemed so much better put together by comparison. And I believe many others agree with me on this. Since the current syntax is unnatural and esoteric, this means it's difficult to discover and very foreign even after that. This makes it much harder to learn and apply givens than it need be.
+
+The previous conditional given syntax was inspired by method definitions. If we add the optional name to the previous example, we obtain something akin to an implicit method in Scala 2:
+```scala
+given listOrd[A](using Ord[A]): Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+```
+The anonymous syntax was then obtained by simply dropping the name.
+But without a name, the syntax looks weird and inconsistent.
+
+This is a problem since at least for typeclasses, anonymous givens should be the norm.
+Givens are like extends clauses. We state a _fact_, that a
+type implements a type class, or that a value can be used implicitly. We don't need a name for that fact. It's analogous to extends clauses, where we state that a class is a subclass of some other class or trait. We would not think it useful to name an extends clause, it's simply a fact that is stated.
+It's also telling that every other language that defines type classes uses anonymous syntax. Somehow, nobody ever found it necessary to name these instances.
+
+A more intuitive and in my opinion cleaner alternative is to decree that a given should always look like it _implements a type_. Conditional givens should look like they implement function types. The `Ord` typeclass instances for `Int` and `List` would then look like this:
+```scala
+given Ord[String]:
+ def compare(x: String, y: String) = ...
+
+given [A : Ord] => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+```
+The second, conditional instance looks like it implements the function type
+```scala
+[A : Ord] => Ord[List[A]]
+```
+Another way to see this is as an implication:
+If `A` is a type that is `Ord`, then `List[A]` is `Ord` (and the rest of the given clause gives the implementation that makes it so).
+Equivalently, `A` is `Ord` _implies_ `List[A]` is `Ord`, hence the `=>`.
+
+Yet another related meaning is that the given clause establishes a _context function_ of type `[A: Ord] ?=> Ord[List[A]]` that is automatically applied to evidence arguments of type `Ord[A]` and that yields instances of type `Ord[List[A]]`. Since givens are in any case applied automatically to all their arguments, we don't need to specify that separately with `?=>`, a simple `=>` arrow is sufficiently clear and is easier to read.
+
+All these viewpoints are equivalent, in a deep sense. This is exactly the Curry Howard isomorphism, which equates function types and implications.
+
+**Proposal:** Change the syntax for given clauses so that a `given` clause consists of the following elements:
+
+ - An optional name binding `id :`
+ - Zero or more _conditions_, which introduce type or value parameters. Each precondition ends in a `=>`.
+ - the implemented _type_,
+ - an implementation which consists of either an `=` and an expression,
+ or a template body.
+
+**Examples:**
+
+Here is an enumeration of common forms of given definitions in the new syntax. We show the following use cases:
+
+ 1. A simple typeclass instance, such as `Ord[Int]`.
+ 2. A parameterized type class instance, such as `Ord` for lists.
+ 3. A type class instance with an explicit context parameter.
+ 4. A type class instance with a named eexplicit context parameter.
+ 4. A simple given alias.
+ 5. A parameterized given alias
+ 6. A given alias with an explicit context parameter.
+ 8. An abstract or deferred given
+ 9. A by-name given, e.g. if we have a given alias of a mutable variable, and we
+ want to make sure that it gets re-evaluated on each access.
+```scala
+ // Simple typeclass
+ given Ord[Int]:
+ def compare(x: Int, y: Int) = ...
+
+ // Parameterized typeclass with context bound
+ given [A: Ord] => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with context parameter
+ given [A] => Ord[A] => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with named context parameter
+ given [A] => (ord: Ord[A]) => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Simple alias
+ given Ord[Int] = IntOrd()
+
+ // Parameterized alias with context bound
+ given [A: Ord] => Ord[List[A]] =
+ ListOrd[A]
+
+ // Parameterized alias with context parameter
+ given [A] => Ord[A] => Ord[List[A]] =
+ ListOrd[A]
+
+ // Abstract or deferred given
+ given Context = deferred
+
+ // By-name given
+ given () => Context = curCtx
+```
+Here are the same examples, with optional names provided:
+```scala
+ // Simple typeclass
+ given intOrd: Ord[Int]:
+ def compare(x: Int, y: Int) = ...
+
+ // Parameterized typeclass with context bound
+ given listOrd: [A: Ord] => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with context parameter
+ given listOrd: [A] => Ord[A] => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with named context parameter
+ given listOrd: [A] => (ord: Ord[A]) => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Simple alias
+ given intOrd: Ord[Int] = IntOrd()
+
+ // Parameterized alias with context bound
+ given listOrd: [A: Ord] => Ord[List[A]] =
+ ListOrd[A]
+
+ // Parameterized alias with context parameter
+ given listOrd: [A] => Ord[A] => Ord[List[A]] =
+ ListOrd[A]
+
+ // Abstract or deferred given
+ given context: Context = deferred
+
+ // By-name given
+ given context: () => Context = curCtx
+```
+
+**By Name Givens**
+
+We sometimes find it necessary that a given alias is re-evaluated each time it is called. For instance, say we have a mutable variable `curCtx` and we want to define a given that returns the current value of that variable. A normal given alias will not do since by default given aliases are mapped to
+lazy vals.
+
+In general, we want to avoid re-evaluation of the given. But there are situations like the one above where we want to specify _by-name_ evaluation instead. The proposed new syntax for this is shown in the last clause above. This is arguably the a natural way to express by-name givens. We want to use a conditional given, since these map to methods, but the set of preconditions is empty, hence the `()` parameter. Equivalently, under the context function viewpoint, we are defining a context function of the form `() ?=> T`, and these are equivalent to by-name parameters.
+
+Compare with the current best way to do achieve this, which is to use a dummy type parameter.
+```scala
+ given [DummySoThatItsByName]: Context = curCtx
+```
+This has the same effect, but feels more like a hack than a clean solution.
+
+**Dropping `with`**
+
+In the new syntax, all typeclass instances introduce definitions like normal
+class bodies, enclosed in braces `{...}` or following a `:`. The irregular
+requirement to use `with` is dropped. In retrospect, the main reason to introduce `with` was since a definition like
+
+```scala
+given [A](using Ord[A]): Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+```
+was deemed to be too cryptic, with the double meaning of colons. But since that syntax is gone, we don't need `with` anymore. There's still a double meaning of colons, e.g. in
+```scala
+given intOrd: Ord[Int]:
+ ...
+```
+but since now both uses of `:` are very familiar (type ascription _vs_ start of nested definitions), it's manageable. Besides, the problem occurs only for named typeclass instances, which should be the exceptional case anyway.
+
+
+**Possible ambiguities**
+
+If one wants to define a given for an a actual function type (which is probably not advisable in practice), one needs to enclose the function type in parentheses, i.e. `given ([A] => F[A])`. This is true in the currently implemented syntax and stays true for all discussed change proposals.
+
+The double meaning of : with optional prefix names is resolved as usual. A : at the end of a line starts a nested definition block. If for some obscure reason one wants to define a named given on multiple lines, one has to format it as follows:
+```scala
+ given intOrd
+ : Ord = ...
+```
+**Comparison with Status Quo**
+
+To facilitate a systematic comparison, here is the listing of all 9x2 cases discussed previously with the current syntax.
+
+Unnamed:
+```scala
+ // Simple typeclass
+ given Ord[Int] with
+ def compare(x: Int, y: Int) = ...
+
+ // Parameterized typeclass with context bound
+ given [A: Ord]: Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with context parameter
+ given [A](using Ord[A]): Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with named context parameter
+ given [A](using ord: Ord[A]): Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Simple alias
+ given Ord[Int] = IntOrd()
+
+ // Parameterized alias with context bound
+ given [A: Ord]: Ord[List[A]] =
+ ListOrd[A]
+
+ // Parameterized alias with context parameter
+ given [A](using Ord[A]): Ord[List[A]] =
+ ListOrd[A]
+
+ // Abstract or deferred given: no unnamed form possible
+
+ // By-name given
+ given [DummySoItsByName]: Context = curCtx
+```
+Named:
+```scala
+ // Simple typeclass
+ given intOrd: Ord[Int] with
+ def compare(x: Int, y: Int) = ...
+
+ // Parameterized typeclass with context bound
+ given listOrd[A: Ord]: Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with context parameter
+ given listOrd[A](using Ord[A]): Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Parameterized typeclass with named context parameter
+ given listOrd[A](using ord: Ord[A]): Ord[List[A]] with
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Simple alias
+ given intOrd: Ord[Int] = IntOrd()
+
+ // Parameterized alias with context bound
+ given listOrd[A: Ord]: Ord[List[A]] =
+ ListOrd[A]
+
+ // Parameterized alias with context parameter
+ given listOrd[A](using Ord[A]): Ord[List[A]] =
+ ListOrd[A]
+
+ // Abstract or deferred given
+ given context: Context
+
+ // By-name given
+ given context[DummySoItsByName]: Context = curCtx
+```
+
+**Summary**
+
+This will be a fairly significant change to the given syntax. I believe there's still a possibility to do this. Not so much code has migrated to new style givens yet, and code that was written can be changed fairly easily. Specifically, there are about a 900K definitions of `implicit def`s
+in Scala code on Github and about 10K definitions of `given ... with`. So about 1% of all code uses the Scala 3 syntax, which would have to be changed again.
+
+Changing something introduced just recently in Scala 3 is not fun,
+but I believe these adjustments are preferable to let bad syntax
+sit there and fester. The cost of changing should be amortized by improved developer experience over time, and better syntax would also help in migrating Scala 2 style implicits to Scala 3. But we should do it quickly before a lot more code
+starts migrating.
+
+Migration to the new syntax is straightforward, and can be supported by automatic rewrites. For a transition period we can support both the old and the new syntax. It would be a good idea to backport the new given syntax to the LTS version of Scala so that code written in this version can already use it. The current LTS would then support old and new-style givens indefinitely, whereas new Scala 3.x versions would phase out the old syntax over time.
+
+
+## Summary of Syntax Changes
+
+Here is the complete context-free syntax for all proposed features.
+```
+TmplDef ::= 'given' GivenDef
+GivenDef ::= [id ':'] GivenSig
+GivenSig ::= GivenImpl
+ | '(' ')' '=>' GivenImpl
+ | GivenConditional '=>' GivenSig
+GivenImpl ::= GivenType ([‘=’ Expr] | TemplateBody)
+ | ConstrApps TemplateBody
+GivenConditional ::= DefTypeParamClause
+ | DefTermParamClause
+ | '(' FunArgTypes ')'
+ | GivenType
+GivenType ::= AnnotType1 {id [nl] AnnotType1}
+
+TypeDef ::= id [TypeParamClause] TypeAndCtxBounds
+TypeParamBounds ::= TypeAndCtxBounds
+TypeAndCtxBounds ::= TypeBounds [‘:’ ContextBounds]
+ContextBounds ::= ContextBound | '{' ContextBound {',' ContextBound} '}'
+ContextBound ::= Type ['as' id]
+
+FunType ::= FunTypeArgs (‘=>’ | ‘?=>’) Type
+ | DefTypeParamClause '=>' Type
+FunExpr ::= FunParams (‘=>’ | ‘?=>’) Expr
+ | DefTypeParamClause ‘=>’ Expr
+```
+
+## Compatibility
+
+All additions are fully compatible with existing Scala 3. The prototype implementation contains a parser that accepts both old and new idioms. That said, we would
+want to deprecate and remove over time the following existing syntax:
+
+ 1. Multiple context bounds of the form `X : A : B : C`.
+ 2. The previous syntax for given clauses which required a `:` in front of the implemented type and a `with` after it.
+ 3. Abstract givens
+
+The changes under (1) and (2) can be automated using existing rewrite technology in the compiler or Scalafix. The changes in (3) are more global in nature but are still straightforward.
+
+## Alternatives
+
+One alternative put forward in the Pre-SIP was to deprecate context bounds altogether and only promote using clauses. This would still be a workable system and arguably lead to a smaller language. On the other hand, dropping context bounds for using clauses worsens
+some of the ergonomics of expressing type classes. First, it is longer. Second, it separates the introduction of a type name and the constraints on that type name. Typically, there can be many normal parameters between a type parameter and the using clause that characterized it. By contrast, context bounds follow the
+general principle that an entity should be declared together with its type, and in a very concrete sense context bounds define types of types. So I think context bounds are here to stay, and improvements to the ergonomics of context bounds will be appreciated.
+
+The Pre-SIP also contained a proposal for a default naming convention of context bounds. If no explicit `as` clause is given, the name of the witness for
+`X : C` would be `X`, instead of a synthesized name as is the case now. This led to extensive discussions how to accommodate multiple context bounds.
+I believe that a default naming convention for witnesses will be very beneficial in the long run, but as of today there are several possible candidate solutions, including:
+
+ 1. Use default naming for single bounds only.
+ 2. If there are multiple bounds, as in `X: {A, B, C}` create a synthetic companion object `X` where selections `X.m` translate into
+ witness selections `A.m`, `B.m`, or `C.m`. Disallow any references to the companion that remain after that expansion.
+ 3. Like (2), but use the synthetic companion approach also for single bounds.
+ 4. Create real aggregate given objects that represent multiple bounds.
+
+Since it is at present not clear what the best solution would be, I decided to defer the question of default names to a later SIP.
+
+This SIP proposed originally a different syntax for givens that made use
+of postfix `as name` for optional names and still followed method syntax in some elements. The 9x2 variants of the original proposal are as follows.
+
+```scala
+ // Simple typeclass
+ given Ord[Int]:
+ def compare(x: Int, y: Int) = ...
+
+ // Parameterized typeclass
+ given [A: Ord] => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Typeclass with context parameter
+ given [A](using Ord[A]) => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Typeclass with named context parameter
+ given [A](using ord: Ord[A]) => Ord[List[A]]:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Simple alias
+ given Ord[Int] = IntOrd()
+
+ // Parameterized alias
+ given [A: Ord] => Ord[List[A]] =
+ ListOrd[A]
+
+ // Alias with explicit context parameter
+ given [A](using Ord[A]) => Ord[List[A]] =
+ ListOrd[A]
+
+ // Abstract or deferred given
+ given Context = deferred
+
+ // By-name given
+ given => Context = curCtx
+```
+Named:
+
+```scala
+ // Simple typeclass
+ given Ord[Int] as intOrd:
+ def compare(x: Int, y: Int) = ...
+
+ // Parameterized typeclass
+ given [A: Ord] => Ord[List[A]] as listOrd:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Typeclass with context parameter
+ given [A](using Ord[A]) => Ord[List[A]] as listOrd:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Typeclass with named context parameter
+ given [A](using ord: Ord[A]) => Ord[List[A]] as listOrd:
+ def compare(x: List[A], y: List[A]) = ...
+
+ // Simple alias
+ given Ord[Int] as intOrd = IntOrd()
+
+ // Parameterized alias
+ given [A: Ord] => Ord[List[A]] as listOrd =
+ ListOrd[A]
+
+ // Alias with using clause
+ given [A](using Ord[A]) => Ord[List[A]] as listOrd =
+ ListOrd[A]
+
+ // Abstract or deferred given
+ given Context as context = deferred
+
+ // By-name given
+ given => Context as context = curCtx
+```
+
+The discussion on contributors raised some concerns with that original proposal. One concern was that changing to postfix `as` for optional names
+would be too much of a change, in particular for simple given aliases. Another concern was that the `=>` felt unfamiliar in this place since it resembled a function type yet other syntactic elements followed method syntax. The revised proposal given here addresses these points by
+going back to the usual `name:` syntax for optional names and doubling down
+on function syntax to reinforce the intuition that givens implement types.
+
+
+## Summary
+
+The proposed set of changes removes awkward syntax and makes dealing with context bounds and givens a lot more regular and pleasant. In summary, the main proposed changes are:
+
+ 1. Allow to name context bounds with `as` clauses.
+ 2. Introduce a less cryptic syntax for multiple context bounds.
+ 3. Refine the rules how context bounds are expanded to account for explicit names.
+ 4. Allow context bounds on type members which expand to deferred givens.
+ 5. Drop abstract givens since they are largely redundant with deferred givens.
+ 6. Allow context bounds for polymorphic functions.
+ 7. Introduce a more regular and clearer syntax for givens.
+
+These changes were implemented under the experimental language import
+```scala
+import language.experimental.modularity
+```
+which also covers some other prospective changes slated to be proposed future SIPs. The new system has proven to work well and to address several fundamental issues people were having with
+existing implementation techniques for type classes.
+
+The changes proposed in this SIP are time-sensitive since we would like to correct some awkward syntax choices in Scala 3 before more code migrates to the new constructs (so far, it seems most code still uses Scala 2 style implicits, which will eventually be phased out). It is easy to migrate to the new syntax and to support both old and new for a transition period.
diff --git a/_sips/sips/uncluttering-abuse-of-match.md b/_sips/sips/uncluttering-abuse-of-match.md
new file mode 100644
index 0000000000..49f004f812
--- /dev/null
+++ b/_sips/sips/uncluttering-abuse-of-match.md
@@ -0,0 +1,6 @@
+---
+title: SIP-39 - Uncluttering Abuse of Match
+status: rejected
+pull-request-number: 37
+
+---
diff --git a/_sips/sips/uncluttering-scalas-syntax-for-control-structures.md b/_sips/sips/uncluttering-scalas-syntax-for-control-structures.md
new file mode 100644
index 0000000000..a4c9d95a95
--- /dev/null
+++ b/_sips/sips/uncluttering-scalas-syntax-for-control-structures.md
@@ -0,0 +1,6 @@
+---
+title: SIP-12 - Uncluttering Scala’s syntax for control structures.
+status: rejected
+pull-request-number: 12
+
+---
diff --git a/_sips/sips/unroll-default-arguments.md b/_sips/sips/unroll-default-arguments.md
new file mode 100644
index 0000000000..6d90188b57
--- /dev/null
+++ b/_sips/sips/unroll-default-arguments.md
@@ -0,0 +1,934 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: implementation
+status: under-review
+title: SIP-61 - Unroll Default Arguments for Binary Compatibility
+---
+
+**By: Li Haoyi**
+
+## History
+
+| Date | Version |
+|---------------|--------------------|
+| Feb 14th 2024 | Initial Draft |
+
+## Summary
+
+This SIP proposes an `@unroll` annotation lets you add additional parameters
+to method `def`s,`class` construtors, or `case class`es, without breaking binary
+compatibility. `@unroll` works by generating "unrolled" or "telescoping" forwarders:
+
+```scala
+// Original
+def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l
+
+// Generated
+def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0)
+def foo(s: String, n: Int) = foo(s, n, true, 0)
+```
+
+In contrast to most existing or proposed alternatives that require you to contort your
+code to become binary compatible (see [Major Alternatives](#major-alternatives)),
+`@unroll` allows you to write Scala with vanilla `def`s/`class`es/`case class`es, add
+a single annotation, and your code will maintain binary compatibility as new default
+parameters and fields are added over time.
+
+`@unroll`'s only constraints are that:
+
+1. New parameters need to have a default value
+2. New parameters can only be added on the right
+3. The `@unroll`ed methods must be abstract or final
+
+These are both existing industry-wide standard when dealing with data and schema evolution
+(e.g. [Schema evolution in Avro, Protocol Buffers and Thrift — Martin Kleppmann’s blog](https://martin.kleppmann.com/2012/12/05/schema-evolution-in-avro-protocol-buffers-thrift.html)),
+and are also the way the new parameters interact with _source compatibility_ in
+the Scala language. Thus these constraints should be immediately familiar to any
+experienced programmers, and would be easy to follow without confusion.
+
+Prior Discussion can be found [here](https://contributors.scala-lang.org/t/can-we-make-adding-a-parameter-with-a-default-value-binary-compatible/6132)
+
+## Motivation
+
+Maintaining binary compatibility of Scala libraries as they evolve over time is
+difficult. Although tools like https://github.com/lightbend/mima help _surface_
+issues, actually _resolving_ those issues is a different challenge.
+
+Some kinds of library changes are fundamentally impossible to make compatible,
+e.g. removing methods or classes. But there is one big class of binary compatibility
+issues that are "spurious": adding default parameters to methods, `class` constructors,
+or `case class`es.
+
+Adding a default parameter is source-compatible, but not binary compatible: a user
+downstream of a library that adds a default parameter does not need to make any
+changes to their code, but _does_ need to re-compile it. This is "spurious" because
+there is no _fundamental_ incompatibility here: semantically, a new default parameter
+is meant to be optional! Old code invoking that method without a new default parameter
+is exactly the user intent, and works just fine if the downstream code is re-compiled.
+
+Other languages, such as Python, have the same default parameter language feature but face
+no such compatibility issues with their use. Even Scala codebases compiled from source
+do not suffer these restrictions: adding a default parameter to the right side of a parameter
+list is for all intents and purposes backwards compatible in a mono-repo setup.
+The fact that such addition is binary incompatible is purely an implementation restriction
+of Scala's binary artifact format and distribution strategy.
+
+**Binary compatibility is generally more important than Source compatibility**. When
+you hit a source compatibility issue, you can always change the source code you are
+compiling, whether manually or via your build tool. In contrast, when you hit binary
+compatibility issues, it can come in the form of diamond dependencies that would require
+_re-compiling all of your transitive dependencies_, a task that is far more difficult and
+often impractical.
+
+There are many approaches to resolving these "spurious" binary compatibility issues,
+but most of them involve either tremendous amounts of boilerplate writing
+binary-compatibility forwarders, giving up on core language features like Case Classes
+or Default Parameters, or both. Consider the following code snippet
+([link](https://github.com/com-lihaoyi/mainargs/blob/1d04a6bd19aaca401d11fe26da31615a8bc9213c/mainargs/src/Parser.scala))
+from the [com-lihaoyi/mainargs](https://github.com/com-lihaoyi/mainargs) library, which
+duplicates the parameters of `def constructEither` no less than five times in
+order to maintain binary compatibility as the library evolves and more default
+parameters are added to `def constructEither`:
+
+```scala
+ def constructEither(
+ args: Seq[String],
+ allowPositional: Boolean,
+ allowRepeats: Boolean,
+ totalWidth: Int,
+ printHelpOnExit: Boolean,
+ docsOnNewLine: Boolean,
+ autoPrintHelpAndExit: Option[(Int, PrintStream)],
+ customName: String,
+ customDoc: String,
+ sorted: Boolean,
+ ): Either[String, T] = constructEither(
+ args,
+ allowPositional,
+ allowRepeats,
+ totalWidth,
+ printHelpOnExit,
+ docsOnNewLine,
+ autoPrintHelpAndExit,
+ customName,
+ customDoc,
+ sorted,
+ )
+
+ def constructEither(
+ args: Seq[String],
+ allowPositional: Boolean = false,
+ allowRepeats: Boolean = false,
+ totalWidth: Int = 100,
+ printHelpOnExit: Boolean = true,
+ docsOnNewLine: Boolean = false,
+ autoPrintHelpAndExit: Option[(Int, PrintStream)] = Some((0, System.out)),
+ customName: String = null,
+ customDoc: String = null,
+ sorted: Boolean = true,
+ nameMapper: String => Option[String] = Util.kebabCaseNameMapper
+ ): Either[String, T] = ???
+
+ /** binary compatibility shim. */
+ private[mainargs] def constructEither(
+ args: Seq[String],
+ allowPositional: Boolean,
+ allowRepeats: Boolean,
+ totalWidth: Int,
+ printHelpOnExit: Boolean,
+ docsOnNewLine: Boolean,
+ autoPrintHelpAndExit: Option[(Int, PrintStream)],
+ customName: String,
+ customDoc: String,
+ nameMapper: String => Option[String]
+ ): Either[String, T] = constructEither(
+ args,
+ allowPositional,
+ allowRepeats,
+ totalWidth,
+ printHelpOnExit,
+ docsOnNewLine,
+ autoPrintHelpAndExit,
+ customName,
+ customDoc,
+ sorted = true,
+ nameMapper = nameMapper
+ )
+```
+
+Apart from being extremely verbose and full of boilerplate, like any boilerplate this is
+also extremely error-prone. Bugs like [com-lihaoyi/mainargs#106](https://github.com/com-lihaoyi/mainargs/issues/106)
+slip through when a mistake is made in that boilerplate. These bugs are impossible to catch
+using a normal test suite, as they only appear in the presence of version skew. The above code
+snippet actually _does_ have such a bug, that the test suite _did not_ catch. See if you can
+spot it!
+
+Sebastien Doraene's talk [Designing Libraries for Source and Binary Compatibility](https://www.youtube.com/watch?v=2wkEX6MCxJs)
+explores some of the challenges, and discusses the workarounds.
+
+
+## Requirements
+
+### Backwards Compatibility
+
+Given:
+
+* Two libraries, **Upstream** and **Downstream**, where **Downstream** depends on **Upstream**
+
+* If we use a _newer_ version of **Upstream** which contains an added
+ default parameter together with an _older_ version of **Downstream** compiled
+ against an _older_ version of **Upstream** before that default parameter was added
+
+* The behavior should be binary compatible and semantically indistinguishable from using
+ a verion of **Downstream** compiled against the _newer_ version of **Upstream**
+
+**Note:** we do not aim for _Forwards_ compatibility. Using an _older_
+version of **Upstream** with a _newer_ version of **Downstream** compiled against a
+_newer_ version of **Upstream** is not a use case we want to support. The vast majority
+of OSS software does not promise forwards compatibility, including software such as
+the JVM, so we should just follow suite
+
+### All Overrides Are Equivalent
+
+All versions of an `@unroll`ed method `def foo` should have the same semantics when called
+with the same parameters. We must be careful to ensure:
+
+1. All our different method overrides point at the same underlying implementation
+2. Abstract methods are properly implemented, and no method would fail with an
+ `AbstractMethodError` when called
+3. We properly forward the necessary argument and default parameter values when
+ calling the respective implementation.
+
+## Proposed solution
+
+
+The proposed solution is to provide a `scala.annotation.unroll` annotation, that
+can be applied to methods `def`s, `class` constructors, or `case class`es to generate
+"unrolled" or "telescoping" versions of a method that forward to the primary implementation:
+
+```scala
+ def constructEither(
+ args: Seq[String],
+ allowPositional: Boolean = false,
+ allowRepeats: Boolean = false,
+ totalWidth: Int = 100,
+ printHelpOnExit: Boolean = true,
+ docsOnNewLine: Boolean = false,
+ autoPrintHelpAndExit: Option[(Int, PrintStream)] = Some((0, System.out)),
+ customName: String = null,
+ customDoc: String = null,
+ @unroll sorted: Boolean = true,
+ @unroll nameMapper: String => Option[String] = Util.kebabCaseNameMapper
+ ): Either[String, T] = ???
+```
+
+This allows the developer to write the minimal amount of code they _want_ to write,
+and add a single annotation to allow binary compatibility to old versions. In this
+case, we annotated `sorted` and `nameMapper` with `@unroll`, which generates forwarders that make
+`def constructEither` binary compatible with older versions that have fewer parameters,
+up to a version before `sorted` or `nameMapper` was added. Any existing method `def`, `class`, or
+`case class` can be evolved in this way, by addition of `@unroll` the first time
+a default argument is added to their signature after its initial definition.
+
+### Unrolling `def`s
+
+Consider a library that is written as follows:
+
+```scala
+object Unrolled{
+ def foo(s: String, n: Int = 1) = s + n + b + l
+}
+```
+
+If over time a new default parameter is added:
+
+```scala
+object Unrolled{
+ def foo(s: String, n: Int = 1, b: Boolean = true) = s + n + b + l
+}
+```
+
+And another
+
+```scala
+object Unrolled{
+ def foo(s: String, n: Int = 1, b: Boolean = true, l: Long = 0) = s + n + b + l
+}
+```
+
+This is a source-compatible change, but not binary-compatible: JVM bytecode compiled against an
+earlier version of the library would be expecting to call `def foo(String, Int)`, but will fail
+because the signature is now `def foo(String, Int, Boolean)` or `def foo(String, Int, Boolean, Long)`.
+On the JVM this will result in a `MethodNotFoundError` at runtime, a common experience for anyone
+who upgrading the versions of their dependencies. Similar concerns are present with Scala.js and
+Scala-Native, albeit the failure happens at link-time rather than run-time
+
+`@unroll` is an annotation that can be applied as follows, to the first "additional" default
+parameter that was added in each published version of the library (in this case,
+`b: Boolean = true` and `l: Long = 0`)
+
+
+```scala
+import scala.annotation.unroll
+
+object Unrolled{
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l
+}
+```
+
+The `@unroll` annotation takes `def foo` and generates synthetic forwarders for the purpose
+of maintaining binary compatibility for old callers who may be expecting the previous signature.
+These forwarders do nothing but forward the call to the current implementation, using the
+given default parameter values:
+
+```scala
+object Unrolled{
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l
+
+ def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0)
+ def foo(s: String, n: Int) = foo(s, n, true, 0)
+}
+```
+
+As a result, old callers who expect `def foo(String, Int, Boolean)` or `def foo(String, Int, Boolean, Long)`
+can continue to work, even as new parameters are added to `def foo`. The only restriction is that
+new parameters can only be added on the right, and they must be provided with a default value.
+
+If multiple default parameters are added at once (e.g. `b` and `l` below) you can also
+choose to only `@unroll` the first default parameter of each batch, to avoid generating
+unnecessary forwarders:
+
+```scala
+object Unrolled{
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, l: Long = 0) = s + n + b + l
+
+ def foo(s: String, n: Int) = foo(s, n, true, 0)
+}
+```
+
+If there are multiple parameter lists (e.g. for curried methods or methods taking implicits) only one
+parameter list can be unrolled (though it does not need to be the first one). e.g. this works:
+
+```scala
+object Unrolled{
+ def foo(s: String,
+ n: Int = 1,
+ @unroll b: Boolean = true,
+ @unroll l: Long = 0)
+ (implicit blah: Blah) = s + n + b + l
+}
+```
+
+As does this
+
+```scala
+object Unrolled{
+ def foo(blah: Blah)
+ (s: String,
+ n: Int = 1,
+ @unroll b: Boolean = true,
+ @unroll l: Long = 0) = s + n + b + l
+}
+```
+
+`@unroll`ed methods can be defined in `object`s, `class`es, or `trait`s. Other cases are shown below.
+
+### Unrolling `class`es
+
+Class constructors and secondary constructors are treated by `@unroll` just like any
+other method:
+
+```scala
+class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0){
+ def foo = s + n + b + l
+}
+```
+
+Unrolls to:
+
+```scala
+class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0){
+ def foo = s + n + b + l
+
+ def this(s: String, n: Int, b: Boolean) = this(s, n, b, 0)
+ def this(s: String, n: Int) = this(s, n, true, 0)
+}
+```
+
+### Unrolling `class` secondary constructors
+
+```scala
+class Unrolled() {
+ var foo = ""
+
+ def this(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = {
+ this()
+ foo = s + n + b + l
+ }
+}
+```
+
+Unrolls to:
+
+```scala
+class Unrolled() {
+ var foo = ""
+
+ def this(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = {
+ this()
+ foo = s + n + b + l
+ }
+
+ def this(s: String, n: Int, b: Boolean) = this(s, n, b, 0)
+ def this(s: String, n: Int) = this(s, n, true, 0)
+}
+```
+
+### Case Classes
+
+`case class`es can also be `@unroll`ed. Unlike normal `class` constructors
+and method `def`s, `case class`es have several generated methods (`apply`, `copy`)
+that need to be kept in sync with their primary constructor. `@unroll` thus
+generates forwarders for those methods as well, based on the presence of the
+`@unroll` annotation in the primary constructor:
+
+```scala
+case class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true){
+ def foo = s + n + b
+}
+```
+
+Unrolls to:
+
+```scala
+case class Unrolled(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0L){
+ def this(s: String, n: Int) = this(s, n, true, 0L)
+ def this(s: String, n: Int, b: Boolean) = this(s, n, b, 0L)
+
+ def copy(s: String, n: Int) = copy(s, n, this.b, this.l)
+ def copy(s: String, n: Int, b: Boolean) = copy(s, n, b, this.l)
+
+ def foo = s + n + b
+}
+object Unrolled{
+ def apply(s: String, n: Int) = apply(s, n, true, 0L)
+ def apply(s: String, n: Int, b: Boolean) = apply(s, n, b, 0L)
+}
+```
+
+Notes:
+
+1. `@unroll`ed `case class`es are fully binary and backwards compatible in Scala 3, but not in Scala 2
+
+2. `.unapply` does not need to be duplicated in Scala 3.x, as its signature
+ `def unapply(x: Unrolled): Unrolled` does not change when new `case class` fields are
+ added.
+
+3. Even in Scala 2.x, where `def unapply(x: Unrolled): Option[TupleN]` is not
+ binary compatible, pattern matching on `case class`es is already binary compatible
+ to addition of new fields due to
+ [Option-less Pattern Matching](https://docs.scala-lang.org/scala3/reference/changed-features/pattern-matching.html).
+ Thus, only calls to `.tupled` or `.curried` on the `case class` companion `object`, or direct calls
+ to `.unapply` on an unrolled `case class` in Scala 2.x (shown below)
+ will cause a crash if additional fields were added:
+
+```scala
+def foo(t: (String, Int)) = println(t)
+Unrolled.unapply(unrolled).map(foo)
+```
+
+In Scala 3, `@unroll`ing a `case class` also needs to generate a `fromProduct`
+implementation in the companion object, as shown below:
+
+```scala
+def fromProduct(p: Product): CaseClass = p.productArity match
+ case 2 =>
+ CaseClass(
+ p.productElement(0).asInstanceOf[...],
+ p.productElement(1).asInstanceOf[...],
+ )
+ case 3 =>
+ CaseClass(
+ p.productElement(0).asInstanceOf[...],
+ p.productElement(1).asInstanceOf[...],
+ p.productElement(2).asInstanceOf[...],
+ )
+ ...
+```
+
+This is not necessary for preserving binary compatibility - the method signature of
+`def fromProduct` does not change depending on the number of fields - but it is
+necessary to preserve semantic compatibility. `fromProduct` by default does not
+take into account field default values, and this change is necessary to make it
+use them when the given `p: Product` has a smaller `productArity` than the current
+`CaseClass` implementation
+
+
+### Hiding Generated Forwarder Methods
+
+As the generated forwarder methods are intended only for binary compatibility purposes,
+we should generally hide them: IDEs, downstream compilers, ScalaDoc, etc. should behave as
+if the generated methods do not exist.
+
+This is done in two different ways:
+
+1. In Scala 2, we generate the methods in a post-`pickler` phase. This ensures they do
+ not appear in the scala signature, and thus are not exposed to downstream tooling
+
+2. In Scala 3, the generated methods are flagged as `Invisible`
+
+## Limitations
+
+### Only the one parameter list of multi-parameter list methods can be `@unroll`ed.
+
+Unrolling multiple parameter lists would generate a number
+of forwarder methods exponential with regard to the number of parameter lists unrolled,
+and the generated forwarders may begin to conflict with each other. We can choose to spec
+this out and implement it later if necessary, but for 99% of use cases `@unroll`ing one
+parameter list should be enough. Typically, only one parameter list in a method has default
+arguments, with other parameter lists being `implicit`s or a single callback/blocks, neither
+of which usually has default values.
+
+### Unrolled forwarder methods can collide with manually-defined overrides
+
+This is similar to any other generated methods. We can raise an error to help users
+debug such scenarios, but such name collisions are inevitably possible given how binary
+compatibility on the JVM works.
+
+### `@unroll`ed case classes are only fully binary compatible in Scala 3
+
+
+They are _almost_ binary compatible in Scala 2. Direct calls to `unapply` are binary
+incompatible, but most common pattern matching of `case class`es goes through a different
+code path that _is_ binary compatible. There are also the `AbstractFunctionN` traits, from
+which the companion object inherits `.curried` and `.tupled` members. Luckily, `unapply`
+was made binary compatible in Scala 3, and `AbstractFunctionN`, `.curried`, and `.tupled`
+were removed
+
+### While `@unroll`ed `case class`es are *not* fully _source_ compatible
+
+This is due to the fact that pattern matching requires all arguments to
+be specified. This proposal does not change that. Future improvements related to
+[Pattern Matching on Named Fields](https://github.com/scala/improvement-proposals/pull/44)
+may bring improvements here. But as we discussed earlier, binary compatibility is generally
+more important than source compatibility, and so we do not need to wait for any source
+compatibility improvements to land before proceeding with these binary compatibility
+improvements.
+
+### Binary and semantic compatibility for macro-derived derive typeclasses is out of scope
+
+
+This propsosal does not have any opinion on whether or not macro-derivation is be binary/source/semantically
+compatible. That is up to the
+individual macro implementations to decide. e.g., [uPickle](https://github.com/com-lihaoyi/upickle)
+has a very similar rule about adding `case class` fields, except that field ordering
+does not matter. Trying to standardize this across all possible macros and all possible
+typeclasses is out of scope
+
+### `@unroll` generates a quadratic amount of generated bytecode as more default parameters are added
+
+Each forwarder has `O(num-params)` size, and there are `O(num-default-params)`
+forwarders. We do not expect this to be a problem in practice, as the small size of the
+generated forwarder methods means the constant factor is small, but one could imagine
+the `O(n^2)` asymptotic complexity becoming a problem if a method accumulates hundreds of
+default parameters over time. In such extreme scenarios, some kind of builder pattern
+(such as those listed in [Major Alternatives](#major-alternatives)) may be preferable.
+
+### `@unroll` only supports `final` methods.
+
+`object` methods and constructors are naturally
+final, but `class` or `trait` methods that are `@unroll`ed need to be explicitly marked `final`.
+It has proved difficult to implement the semantics of `@unroll` in the presence of downstream
+overrides, `super`, etc. where the downstream overrides can be compiled against by different
+versions of the upstream code. If we can come up with some implementation that works, we can
+lift this restriction later, but for now I have not managed to do so and so this restriction
+stays.
+
+### Challenges of Non-Final Methods and Overriding
+
+To elaborate a bit on the issues with non-final methods and overriding, consider the following
+case with four classes, `Upstream`, `Downstream`, `Main1` and `Main2`, each of which is compiled
+against different versions of each other (hence the varying number of parameters for `foo`):
+
+```scala
+class Upstream{ // V2
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l
+}
+```
+
+```scala
+class Downstream extends Upstream{ // compiled against Upstream V1
+ override def foo(s: String, n: Int = 1) = super.foo(s, n) + s + n
+}
+```
+
+```scala
+object Main1 { // compiled against Upstream V2
+ def main(args: Array[String]): Unit = {
+ new Downstream().foo("hello", 123, false, 456L)
+ }
+}
+```
+
+```scala
+object Main2 { // compiled against Upstream V1
+ def main(args: Array[String]): Unit = {
+ new Downstream().foo("hello", 123)
+ }
+}
+```
+
+
+The challenge here is: how do we make sure that `Main1` and `Main2`, who call
+`new Downstream().foo`, correctly pick up the version of `def foo` that is
+provided by `Downstream`?
+
+With the current implementation, the `override def foo` inside `Downstream` would only
+override one of `Upstream`'s synthetic forwarders, but would not override the actual
+primary implementation. As a result, we would see `Main1` calling the implementation
+of `foo` from `Upstream`, while `Main2` calls the implementation of `foo` from
+`Downstream`. So even though both `Main1` and `Main2` have the same
+`Upstream` and `Downstream` code on the classpath, they end up calling different
+implementations based on what they were compiled against.
+
+We cannot perform the method search and dispatch _within_ the `def foo` methods,
+because it depends on exactly _how_ `foo` is called: the `InvokeVirtual` call from
+`Main1` is meant to resolve to `Downstream#foo`, while the `InvokeSpecial` call
+from `Downstream#foo`'s `super.foo` is meant to resolve to `Upstream#foo`. But a
+method implementation cannot know how it was called, and thus it is impossible
+for `def foo` to forward the call to the right place.
+
+Like our treatment of [Abstract Methods](#abstract-methods), this scenario can never
+happen according to what version combinations are supported by our definition of
+[Backwards Compatibility](#backwards-compatibility), but nevertheless is a real
+concern due to the requirement that [All Overrides Are Equivalent](#all-overrides-are-equivalent).
+
+It may be possible to loosen this restriction to also allow abstract methods that
+are implemented only once by a final method. See the section about
+[Abstract Methods](#abstract-methods) for details.
+
+## Major Alternatives
+
+The major alternatives to `@unroll` are listed below:
+
+1. [data-class](https://index.scala-lang.org/alexarchambault/data-class)
+2. [SBT Contrabad](https://www.scala-sbt.org/contraband/)
+3. [Structural Data Structures](https://contributors.scala-lang.org/t/pre-sip-structural-data-structures-that-can-evolve-in-a-binary-compatible-way/5684)
+4. Avoiding language features like `case class`es or default parameters, as suggested by the
+ [Binary Compatibility for Library Authors](https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html) documentation.
+
+While those alternate approaches _do work_ - `data-class` and `SBT Datatype` are used heavily
+in various open-source projects - I believe they are inferior to the approach that `@unroll`
+takes:
+
+### Case Class v.s. not-a-Case-Class
+
+The first major difference between `@unroll` and the above alternatives is that these alternatives
+all introduce something new: some kind of _not-a-case-class_ `class` that is to be used
+when binary compatibility is desired. This _not-a-case-class_ has different syntax from
+`case class`es, different semantics, different methods, and so on.
+
+In contrast, `@unroll` does not introduce any new language-level or library-level constructs.
+The `@unroll` annotation is purely a compiler-backend concern for maintaining binary
+compatibility. At a language level, `@unroll` allows you to keep using normal method `def`s,
+`class`es and `case class`es with exactly the same syntax and semantics you have been using
+all along.
+
+Having people be constantly choosing between _case-class_ and _not-a-case-class_ when
+designing their data types, is inferior to simply using `case class`es all the time
+
+
+### Scala Syntax v.s. Java-esque Syntax
+
+
+The alternatives linked above all build a
+Java-esque "[inner platform](https://en.wikipedia.org/wiki/Inner-platform_effect)"
+on top of the Scala language, with its own conventions like `.withFoo` methods.
+
+In contrast, `@unroll` makes use of the existing Scala language's default parameters
+to achieve the same effect.
+
+If we think Scala is nicer to write then Java due to its language
+features, then `@unroll`'s approach of leveraging those language features is nicer
+to use than the alternative's Java-esque syntax.
+
+Having implementation-level problems - which is what binary compatibility across version
+skew is - bleed into the syntax and semantics of the language is also inferior to having it
+be controlled by an annotation. Martin Odersky has said that annotations are intended for
+things that do not affect typechecking, and `@unroll` fits the bill perfectly.
+
+
+### Evolving Any Class v.s. Evolving Pre-determined Classes
+
+The alternatives given require that the developer has to decide _up front_ whether their
+data type needs to be evolved while maintaining binary compatibility.
+
+In contrast, `@unroll` allows you to evolve any existing `class` or `case class`.
+
+In general, trying to decide which classes _will need to evolve later on_ is a difficult
+task that is easy to get wrong. `@unroll` totally removes that requirement, allowing
+you to take _any_ `class` or `case class` and evolve it later in a binary compatible way.
+
+
+### Binary Compatibility for Methods and Classes
+
+Lastly, the above alternatives only solve _half_ the problem: how to evolve `case class`es.
+This is _schema evolution_.
+
+Binary compatility is not just a problem for `case class`es adding new fields: normal
+`class` constructors, instance method `def`s, static method `def`s, etc. have default
+parameters added all the time as well.
+
+In contrast, `@unroll` allows the evolution of `def`s and normal `class`es, in addition
+to `case class`es, all using the same approach:
+
+1. `@unroll`ing `case class`es is about _schema evolution_
+2. `@unroll`ing concrete method `def`s is about _API evolution_
+3. `@unroll`ing abstract method `def`s is about _protocol evolution_
+
+All three cases above have analogous best practices in the broader software engineering
+world: whether you are adding an optional column to a database table, adding an
+optional flag to a command-line tool, are extending an existing protocol with optional
+fields that may need handling by both clients and servers implementing that protocol.
+
+`@unroll` solves all three problems at once - schema evolution, API evolution, and protocol
+evolution. It does so with the same Scala-level syntax and semantics, with the same requirements
+and limitations that common schema/API/protocol-evolution best-practices have in the broader
+software engineering community.
+
+### Abstract Methods
+
+Apart from `final` methods, `@unroll` also supports purely abstract methods. Consider
+the following example with a trait `Unrolled` and an implementation `UnrolledObj`:
+
+```scala
+trait Unrolled{ // version 3
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0): String
+}
+```
+```scala
+object UnrolledObj extends Unrolled{ // version 3
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b
+}
+```
+
+This unrolls to:
+```scala
+trait Unrolled{ // version 3
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0): String = foo(s, n, b)
+ def foo(s: String, n: Int, b: Boolean): String = foo(s, n)
+ def foo(s: String, n: Int): String
+}
+```
+```scala
+object UnrolledObj extends Unrolled{ // version 3
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l
+ def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0)
+ def foo(s: String, n: Int) = foo(s, n, true)
+}
+```
+
+Note that both the abstract methods from `trait Unrolled` and the concrete methods
+from `object UnrolledObj` generate forwarders when `@unroll`ed, but the forwarders
+are generated _in opposite directions_! Unrolled concrete methods forward from longer
+parameter lists to shorter parameter lists, while unrolled abstract methods forward
+from shorter parameter lists to longer parameter lists. For example, we may have a
+version of `object UnrolledObj` that was compiled against an earlier version of `trait Unrolled`:
+
+
+```scala
+object UnrolledObj extends Unrolled{ // version 2
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true) = s + n + b
+ def foo(s: String, n: Int) = foo(s, n, true)
+}
+```
+
+But further downstream code calling `.foo` on `UnrolledObj` may expect any of the following signatures,
+depending on what version of `Unrolled` and `UnrolledObj` it was compiled against:
+
+```scala
+UnrolledObj.foo(String, Int)
+UnrolledObj.foo(String, Int, Boolean)
+UnrolledObj.foo(String, Int, Boolean, Long)
+```
+
+Because such downstream code cannot know which version of `Unrolled` that `UnrolledObj`
+was compiled against, we need to ensure all such calls find their way to the correct
+implementation of `def foo`, which may be at any of the above signatures. This "double
+forwarding" strategy ensures that regardless of _which_ version of `.foo` gets called,
+it ends up eventually forwarding to the actual implementation of `foo`, with
+the correct combination of passed arguments and default arguments
+
+```scala
+UnrolledObj.foo(String, Int) // forwards to UnrolledObj.foo(String, Int, Boolean)
+UnrolledObj.foo(String, Int, Boolean) // actual implementation
+UnrolledObj.foo(String, Int, Boolean, Long) // forwards to UnrolledObj.foo(String, Int, Boolean)
+```
+
+As is the case for `@unroll`ed methods on `trait`s and `class`es, `@unroll`ed
+implementations of an abtract method must be final.
+
+#### Are Reverse Forwarders Really Necessary?
+
+This "double forwarding" strategy is not strictly necessary to support
+[Backwards Compatibility](#backwards-compatibility): the "reverse" forwarders
+generated for abstract methods are only necessary when a downstream callsite
+of `UnrolledObj.foo` is compiled against a newer version of the original
+`trait Unrolled` than the `object UnrolledObj` was, as shown below:
+
+```scala
+trait Unrolled{ // version 3
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0): String = foo(s, n, b)
+ // generated
+ def foo(s: String, n: Int, b: Boolean): String = foo(s, n)
+ def foo(s: String, n: Int): String
+}
+```
+```scala
+object UnrolledObj extends Unrolled{ // version 2
+ def foo(s: String, n: Int = 1, @unroll b: Boolean = true) = s + n + b
+ // generated
+ def foo(s: String, n: Int) = foo(s, n, true)
+}
+```
+```scala
+// version 3
+UnrolledObj.foo("hello", 123, true, 456L)
+```
+
+If we did not have the reverse forwarder from `foo(String, Int, Boolean, Long)` to
+`foo(String, Int, Boolean)`, this call would fail at runtime with an `AbstractMethodError`.
+It also will get caught by MiMa as a `ReversedMissingMethodProblem`.
+
+This configuration of version is not allowed given our definition of backwards compatibility:
+that definition assumes that `Unrolled` must be of a greater or equal version than `UnrolledObj`,
+which itself must be of a greater or equal version than the final call to `UnrolledObj.foo`. However,
+the reverse forwarders are needed to fulfill our requirement
+[All Overrides Are Equivalent](#all-overrides-are-equivalent):
+looking at `trait Unrolled // version 3` and `object UnrolledObj // version 2` in isolation,
+we find that without the reverse forwarders the signature `foo(String, Int, Boolean, Long)`
+is defined but not implemented. Such an un-implemented abstract method is something
+we want to avoid, even if our artifact version constraints mean it should technically
+never get called.
+
+## Minor Alternatives:
+
+
+### `@unrollAll`
+
+Currently, `@unroll` generates a forwarder only for the annotated default parameter;
+if you want to generate multiple forwarders, you need to `@unroll` each one. In the
+vast majority of scenarios, we want to unroll every default parameters we add, and in
+many cases default parameters are added one at a time. In this case, an `@unrollAll`
+annotation may be useful, a shorthand for applying `@unroll` to the annotated default
+parameter and every parameter to the right of it:
+
+```scala
+object Unrolled{
+ def foo(s: String, n: Int = 1, @unrollAll b: Boolean = true, l: Long = 0) = s + n + b + l
+}
+```
+```scala
+object Unrolled{
+ def foo(s: String, n: Int = 1, b: Boolean = true, l: Long = 0) = s + n + b + l
+
+ def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0)
+ def foo(s: String, n: Int) = foo(s, n, true, 0)
+}
+```
+
+
+
+### Generating Forwarders For Parameter Type Widening or Result Type Narrowing
+
+While this proposal focuses on generating forwarders for addition of default parameters,
+you can also imagine similar forwarders being generated if method parameter types
+are widened or if result types are narrowed:
+
+```scala
+// Before
+def foo(s: String, n: Int = 1, b: Boolean = true) = s + n + b + l
+
+// After
+def foo(@unrollType[String] s: Object, n: Int = 1, b: Boolean = true) = s.toString + n + b + l
+
+// Generated
+def foo(s: Object, n: Int = 1, b: Boolean = true) = s.toString + n + b + l
+def foo(s: String, n: Int = 1, b: Boolean = true) = foo(s, n, b)
+```
+
+This would follow the precedence of how Java's and Scala's covariant method return
+type overrides are implemented: when a class overrides a method with a new
+implementation with a narrower return type, a forwarder method is generated to
+allow anyone calling the original signature \to be forwarded to the narrower signature.
+
+This is not currently implemented in `@unroll`, but would be a straightforward addition.
+
+### Incremental Forwarders or Direct Forwarders
+
+Given this:
+
+```scala
+def foo(s: String, n: Int = 1, @unroll b: Boolean = true, @unroll l: Long = 0) = s + n + b + l
+```
+
+There are two ways to do the forwarders. First option, which I used in above, is
+to have each forwarder directly call the primary method:
+
+```scala
+def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0)
+def foo(s: String, n: Int) = foo(s, n, true, 0)
+```
+
+Second option is to have each forwarder incrementally call the next forwarder, which
+will eventually end up calling the primary method:
+
+```scala
+def foo(s: String, n: Int, b: Boolean) = foo(s, n, b, 0)
+def foo(s: String, n: Int) = foo(s, n, true)
+```
+
+The first option results in shorter stack traces, while the second option results in
+roughly half as much generated bytecode in the method bodies (though it's still `O(n^2)`).
+
+In order to allow `@unroll`ing of [Abstract Methods](#abstract-methods), we had to go with
+the second option. This is because when an abstract method is overriden, it is not necessarily
+true that the longest override that contains the implementation. Thus we need to forward
+between the different `def foo` overrides one at a time until the override containing the
+implementation is found.
+
+
+
+## Implementation & Testing
+
+This SIP has a full implementation for Scala {2.12, 2.13, 3} X {JVM, JS, Native}
+in the following repository, as a compiler plugin:
+
+- https://github.com/com-lihaoyi/unroll
+
+As the `@unroll` annotation is purely a compile-time construct and does not need to exist
+at runtime, `@unroll` can be added to Scala 2.13.x without breaking forwards compatibility.
+
+The linked repo also contains an extensive test suite that uses both MIMA as well
+as classpath-mangling to validate that it provides both the binary and semantic
+compatibility benefits claimed in this document. In fact, it has even discovered
+bugs in the upstream Scala implementation related to binary compatibility, e.g.
+[scala-native/scala-native#3747](https://github.com/scala-native/scala-native/issues/3747)
+
+I have also opened pull requests to a number of popular OSS Scala libraries,
+using `@unroll` as a replacement for manually writing binary compatibility stubs,
+and the 100s of lines of boilerplate reduction can be seen in the links below:
+
+- https://github.com/com-lihaoyi/mainargs/pull/113/files
+- https://github.com/com-lihaoyi/mill/pull/3008/files
+- https://github.com/com-lihaoyi/upickle/pull/555/files
+- https://github.com/com-lihaoyi/os-lib/pull/254
+
+These pull requests all pass both the test suite as well as the MIMA
+`check-binary-compatibility` job, demonstrating that this approach does work
+in real-world codebases. At time of writing, these are published under the following
+artifacts and can be used in your own projects already:
+
+- Compiler Plugin: `ivy"com.lihaoyi::unroll-plugin:0.1.12"`
+- Annotation: `ivy"com.lihaoyi::unroll-annotation:0.1.12"`
diff --git a/_sips/sips/unsigned-integers.md b/_sips/sips/unsigned-integers.md
new file mode 100644
index 0000000000..4cfa9995db
--- /dev/null
+++ b/_sips/sips/unsigned-integers.md
@@ -0,0 +1,6 @@
+---
+title: SIP-26 - Unsigned Integers
+status: rejected
+pull-request-number: 27
+
+---
diff --git a/_sips/sips/2012-01-30-value-classes.md b/_sips/sips/value-classes.md
similarity index 97%
rename from _sips/sips/2012-01-30-value-classes.md
rename to _sips/sips/value-classes.md
index 35ad090bc1..48ad643281 100644
--- a/_sips/sips/2012-01-30-value-classes.md
+++ b/_sips/sips/value-classes.md
@@ -1,15 +1,16 @@
---
layout: sip
title: SIP-15 - Value Classes
-
-vote-status: complete
-vote-text: This SIP has already been accepted and completed. There has been concern for numerical computing. We think future SIP(s), using work from SIP-15, can provide more benefit to numerical computing users. The SIP as it exists benefits all users of implicit enrichment classes, and takes us much further to unboxed high performance code. This SIP does not exclude further work towards improving numerical computing in Scala.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/value-classes.html
---
**By: Martin Odersky and Jeff Olson and Paul Phillips and Joshua Suereth**
+> Note from the SIP Committee: we think future SIP(s), using work from SIP-15, can provide more benefit to numerical computing users. The SIP as it exists benefits all users of implicit enrichment classes, and takes us much further to unboxed high performance code. This SIP does not exclude further work towards improving numerical computing in Scala.
+
## History
| Date | Version |
diff --git a/_sips/sips/wildcard-context-bounds.md b/_sips/sips/wildcard-context-bounds.md
new file mode 100644
index 0000000000..7ef71f1f61
--- /dev/null
+++ b/_sips/sips/wildcard-context-bounds.md
@@ -0,0 +1,6 @@
+---
+title: SIP-52 - Wildcard context bounds
+status: withdrawn
+pull-request-number: 55
+
+---
diff --git a/_sips/sips/xistential-containers.md b/_sips/sips/xistential-containers.md
new file mode 100644
index 0000000000..a3f4764c3e
--- /dev/null
+++ b/_sips/sips/xistential-containers.md
@@ -0,0 +1,7 @@
+---
+title: 'SIP-69: Existential containers'
+status: under-review
+pull-request-number: 101
+stage: design
+
+---
diff --git a/_style/declarations.md b/_style/declarations.md
index ed02e81785..06fbfadcb7 100644
--- a/_style/declarations.md
+++ b/_style/declarations.md
@@ -13,7 +13,7 @@ next-page: control-structures
## Classes
-Class/Object/Trait constructors should be declared all on one line,
+Class, object, and trait constructors should be declared all on one line,
unless the line becomes "too long" (about 100 characters). In that case,
put each constructor argument on its own line with
[trailing commas](https://docs.scala-lang.org/sips/trailing-commas.html#motivation):
@@ -102,7 +102,7 @@ Local methods or private methods may omit their return type:
#### Procedure Syntax
-Avoid the procedure syntax, as it tends to be confusing for very little gain in brevity.
+Avoid the (now deprecated) procedure syntax, as it tends to be confusing for very little gain in brevity.
// don't do this
def printBar(bar: Baz) {
@@ -160,7 +160,7 @@ or is of a non-functional nature (some mutable state, local or
otherwise), the body must be enclosed in braces:
def sum(ls: List[String]): Int = {
- val ints = ls map (_.toInt)
+ val ints = ls.map(_.toInt)
ints.foldLeft(0)(_ + _)
}
@@ -197,7 +197,8 @@ There are three main reasons you should do this:
Multiple parameter lists allow you to create your own "control
structures":
- def unless(exp: Boolean)(code: => Unit): Unit = if (!exp) code
+ def unless(exp: Boolean)(code: => Unit): Unit =
+ if (!exp) code
unless(x < 5) {
println("x was not less than five")
}
@@ -223,16 +224,33 @@ There are three main reasons you should do this:
List("").foldLeft(0, (b: Int, a: String) => b + a.length)
List("").foldLeft[Int](0, _ + _.length)
-For complex DSLs, or with type-names that are long, it can be difficult
-to fit the entire signature on one line. In those cases, align the
-open-paren of the parameter lists, one list per line (i.e. if you can't
-put them all on one line, put one each per line):
+For complex DSLs, or with type names that are long, it can be difficult
+to fit the entire signature on one line. For those cases there are several
+different styles in use:
+
+1. Split the parameter lists, one parameter per line with
+[trailing commas](https://docs.scala-lang.org/sips/trailing-commas.html#motivation)
+and parentheses being on separate lines adding to visual separation between
+the lists:
+
+ protected def forResource(
+ resourceInfo: Any,
+ )(
+ f: (JsonNode) => Any,
+ )(implicit
+ urlCreator: URLCreator,
+ configurer: OAuthConfiguration,
+ ): Any = {
+ ...
+ }
- protected def forResource(resourceInfo: Any)
- (f: (JsonNode) => Any)
- (implicit urlCreator: URLCreator, configurer: OAuthConfiguration): Any = {
- ...
- }
+2. Or align the open-paren of the parameter lists, one list per line:
+
+ protected def forResource(resourceInfo: Any)
+ (f: (JsonNode) => Any)
+ (implicit urlCreator: URLCreator, configurer: OAuthConfiguration): Any = {
+ ...
+ }
#### Higher-Order Functions
diff --git a/_style/files.md b/_style/files.md
index 54ddf4e2db..704948ab32 100644
--- a/_style/files.md
+++ b/_style/files.md
@@ -11,33 +11,32 @@ previous-page: method-invocation
next-page: scaladoc
---
-As a rule, files should contain a *single* logical compilation unit. By
-"logical" I mean a class, trait or object. One exception to this
-guideline is for classes or traits which have companion objects.
-Companion objects should be grouped with their corresponding class or
-trait in the same file. These files should be named according to the
-class, trait or object they contain:
+The unit of work for the compiler is a "compilation unit",
+which is usually just an ordinary file.
+The Scala language places few restrictions on how code is organized across files.
+The definition of a class, or equivalently a trait or object, can't be split over multiple files,
+so it must be contained within a single file.
+A class and its companion object must be defined together in the same file.
+A sealed class can be extended only in the same file, so all its subclasses must be defined there.
- package com.novell.coolness
+Similarly, there are no restrictions on the name of a source file or where it is located in the file system,
+although certain conventions are broadly honored in practice.
+Generally, the file is named after the class it contains,
+or if it has more than one class, the parent class.
+
+For example, a file, `Inbox.scala`, is expected to contain `Inbox` and its companion:
+
+ package org.coolness
class Inbox { ... }
// companion object
object Inbox { ... }
-These compilation units should be placed within a file named
-`Inbox.scala` within the `com/novell/coolness` directory. In short, the
-Java file naming and positioning conventions should be preferred,
-despite the fact that Scala allows for greater flexibility in this
-regard.
-
-## Multi-Unit Files
+The file may be located in a directory, `org/coolness`, following Java tooling conventions,
+but this is at the discretion of the developer and for their convenience.
-Despite what was said above, there are some important situations which
-warrant the inclusion of multiple compilation units within a single
-file. One common example is that of a sealed trait and several
-sub-classes (often emulating the ADT language feature available in
-functional languages):
+It is natural to put the following `Option` ADT in a file, `Option.scala`:
sealed trait Option[+A]
@@ -45,26 +44,11 @@ functional languages):
case object None extends Option[Nothing]
-Because of the nature of sealed superclasses (and traits), all subtypes
-*must* be included in the same file. Thus, such a situation definitely
-qualifies as an instance where the preference for single-unit files
-should be ignored.
-
-Another case is when multiple classes logically form a single, cohesive
-group, sharing concepts to the point where maintenance is greatly served
-by containing them within a single file. These situations are harder to
-predict than the aforementioned sealed supertype exception. Generally
-speaking, if it is *easier* to perform long-term maintenance and
-development on several units in a single file rather than spread across
-multiple, then such an organizational strategy should be preferred for
-these classes. However, keep in mind that when multiple units are
-contained within a single file, it is often more difficult to find
-specific units when it comes time to make changes.
-
-**All multi-unit files should be given camelCase names with a lower-case
-first letter.** This is a very important convention. It differentiates
-multi- from single-unit files, greatly easing the process of finding
-declarations. These filenames may be based upon a significant type which
-they contain (e.g. `option.scala` for the example above), or may be
-descriptive of the logical property shared by all units within (e.g.
-`ast.scala`).
+The related elements, `Some` and `None`, are easily discoverable, even in the absence of tooling.
+
+When unrelated classes are grouped together, perhaps because they implement a feature or a model a domain,
+the source file receives a descriptive `camelCase` name.
+Some prefer this naming scheme for top-level terms. For example, `object project` would be found in `project.scala`.
+Similarly, a package object defined as `package object model` is located in `package.scala` in the `model` source directory.
+
+Files created just for quick testing can have arbitrary names, such as `demo-bug.scala`.
diff --git a/_style/index.md b/_style/index.md
index 279779349f..9c126423ca 100644
--- a/_style/index.md
+++ b/_style/index.md
@@ -20,7 +20,7 @@ This document is intended to outline some basic Scala stylistic guidelines which
- [Accessors/Mutators](naming-conventions.html#accessorsmutators)
- [Parentheses](naming-conventions.html#parentheses)
- [Symbolic Method Names](naming-conventions.html#symbolic-method-names)
- - [Constants, Values, Variable and Methods](naming-conventions.html#constants-values-variable-and-methods)
+ - [Constants, Values and Variables](naming-conventions.html#constants-values-and-variables)
- [Type Parameters (generics)](naming-conventions.html#type-parameters-generics)
- [Higher-Kinds and Parameterized Type parameters](naming-conventions.html#higher-kinds-and-parameterized-type-parameters)
- [Annotations](naming-conventions.html#annotations)
@@ -59,7 +59,6 @@ This document is intended to outline some basic Scala stylistic guidelines which
- [Symbolic Methods/Operators](method-invocation.html#symbolic-methodsoperators)
- [Higher-Order Functions](method-invocation.html#higher-order-functions)
- [Files](files.html)
- - [Multi-Unit Files](files.html#multi-unit-files)
- [Scaladoc](scaladoc.html)
- [General Style](scaladoc.html#general-style)
- [Packages](scaladoc.html#packages)
diff --git a/_style/method-invocation.md b/_style/method-invocation.md
index 861d07dba6..eb1e548785 100644
--- a/_style/method-invocation.md
+++ b/_style/method-invocation.md
@@ -51,7 +51,7 @@ acceptable to omit parentheses when calling `queue.size`, but not when
calling `println()`. This convention mirrors the method declaration
convention given above.
-Religiously observing this convention will *dramatically* improve code
+Observing this convention improves code
readability and will make it much easier to understand at a glance the
most basic operation of any given method. Resist the urge to omit
parentheses simply to save two characters!
@@ -92,35 +92,28 @@ gray area is short, operator-like methods like `max`, especially if commutative:
// fairly common
a max b
-Symbolic methods which take more than one parameter (they do exist!)
-may still be invoked using infix notation, delimited by spaces:
+Symbolic methods which take more than one parameter are discouraged.
+When they exist, they may still be invoked using infix notation, delimited by spaces:
foo ** (bar, baz)
Such methods are fairly rare, however, and should normally be avoided during API
-design. For example, the use of the `/:` and `:\` methods should be avoided in
+design. For example, the use of the (now deprecated) `/:` and `:\` methods should be avoided in
preference to their better-known names, `foldLeft` and `foldRight`.
### Higher-Order Functions
-As noted, methods which take functions as parameters (such as `map` or
-`foreach`) should be invoked using infix notation. It is also *possible* to
-invoke such methods in the following way:
+Invoking higher-order functions may use parens or braces, but in
+either case, use dot notation and omit any space after the method name:
- // wrong!
- names.map { _.toUpperCase }
-
-This style is *not* the accepted standard! The reason to avoid this style is for
-situations where more than one invocation must be chained together:
+ names.map(_.toUpperCase)
- // wrong!
- names.map { _.toUpperCase }.filter { _.length > 5 }
+These are not recommended:
- // right!
- names map { _.toUpperCase } filter { _.length > 5 }
+ // wrong! missing dot
+ names map (_.toUpperCase)
+ // wrong! extra space
+ names.map (_.toUpperCase)
-Both of these work, but the former can easily lead to confusion. The
-sub-expression `{ _.toUpperCase }.filter` when taken in isolation looks like we
-are invoking the `filter` method on a function value. However, we are actually
-invoking `filter` on the result of the `map` method, which takes the function
-value as a parameter.
+Experience has shown that these styles make code harder to read,
+especially when multiple such method calls are chained.
diff --git a/_style/naming-conventions.md b/_style/naming-conventions.md
index 03e6ccd117..9ea2bd8084 100644
--- a/_style/naming-conventions.md
+++ b/_style/naming-conventions.md
@@ -195,44 +195,36 @@ getter and setter. For example:
### Parentheses
-Unlike Ruby, Scala attaches significance to whether or not a method is
-*declared* with parentheses (only applicable to methods of
-[arity](https://en.wikipedia.org/wiki/Arity)-0). For example:
+Scala allows a parameterless, zero-[arity](https://en.wikipedia.org/wiki/Arity)
+method to be declared with an empty parameter list:
def foo1() = ...
+or with no parameter lists at all:
+
def foo2 = ...
-These are different methods at compile-time. While `foo1` can be called
-with or without the parentheses, `foo2` *may not* be called *with*
-parentheses.
-
-Thus, it is actually quite important that proper guidelines be observed
-regarding when it is appropriate to declare a method without parentheses
-and when it is not.
-
-Methods which act as accessors of any sort (either encapsulating a field
-or a logical property) should be declared *without* parentheses except
-if they have side effects. While Ruby and Lift use a `!` to indicate
-this, the usage of parens is preferred (please note that fluid APIs and
-internal domain-specific languages have a tendency to break the
-guidelines given below for the sake of syntax. Such exceptions should
-not be considered a violation so much as a time when these rules do not
-apply. In a DSL, syntax should be paramount over convention).
-
-Further, the callsite should follow the declaration; if declared with
-parentheses, call with parentheses. While there is temptation to save a
-few characters, if you follow this guideline, your code will be *much*
-more readable and maintainable.
-
- // doesn't change state, call as birthdate
- def birthdate = firstName
-
- // updates our internal state, call as age()
- def age() = {
- _age = updateAge(birthdate)
- _age
- }
+By convention, parentheses are used to indicate that a method has
+side effects, such as altering the receiver.
+
+On the other hand, the absence of parentheses indicates that a
+method is like an accessor: it returns a value without altering the
+receiver, and on the same receiver in the same state, it always
+returns the same answer.
+
+The callsite should follow the declaration; if declared with
+parentheses, call with parentheses.
+
+These conventions are followed in the Scala standard library and
+you should follow them in your own code as well.
+
+Additional notes:
+
+* Scala 3 errors if you leave out the parentheses at the call site. Scala 2 merely warns.
+* Scala 3 and 2 both error if the call site has parentheses where the definition doesn't.
+* Java-defined methods are exempt from this distinction and may be called either way.
+* If a method _does_ take parameters, there isn't any convention for indicating whether it also has side effects.
+* Creating an object isn't considered a side effect. So for example, Scala collections have an `iterator` method with no parens. Yes, you get a new iterator each time. And yes, iterators are mutable. But every fresh iterator is the same until it has been altered by calling a side-effecting method such as `Iterator#next()`, which _is_ declared with parentheses. See this [2018 design discussion](https://github.com/scala/collection-strawman/issues/520).
### Symbolic Method Names
@@ -266,7 +258,7 @@ advanced feature in Scala, to be used only by those most well-versed in
its pitfalls. Without care, excessive use of symbolic method names can
easily transform even the simplest code into symbolic soup.
-## Constants, Values, Variable and Methods
+## Constants, Values and Variables
Constant names should be in upper camel case. Similar to Java's `static final`
members, if the member is final, immutable and it belongs to a package
@@ -278,10 +270,9 @@ object or an object, it may be considered a constant:
The value: `Pi` in `scala.math` package is another example of such a constant.
-Method, Value and variable names should be in lower camel case:
+Value and variable names should be in lower camel case:
val myValue = ...
- def myMethod = ...
var myVariable
## Type Parameters (generics)
@@ -365,8 +356,7 @@ for local names to be very short:
def add(a: Int, b: Int) = a + b
-This would be bad practice in languages like Java, but it is *good*
-practice in Scala. This convention works because properly-written Scala
+This convention works because properly-written Scala
methods are quite short, only spanning a single expression and rarely
going beyond a few lines. Few local names are used (including
parameters), and so there is no need to contrive long, descriptive
diff --git a/_style/scaladoc.md b/_style/scaladoc.md
index 7a78bd713f..12dc9528a5 100644
--- a/_style/scaladoc.md
+++ b/_style/scaladoc.md
@@ -208,7 +208,7 @@ sure to indicate the actual method names:
* @return a new Person instance with the age determined by the
* birthdate and current date.
*/
- def apply(name: String, birthDate: java.util.Date) = {}
+ def apply(name: String, birthDate: java.time.LocalDate) = {}
}
If your object holds implicit conversions, provide an example in the
diff --git a/_style/types.md b/_style/types.md
index 87b9a1eb3d..67df05af71 100644
--- a/_style/types.md
+++ b/_style/types.md
@@ -38,7 +38,7 @@ Function values support a special case of type inference which is worth
calling out on its own:
val ls: List[String] = ...
- ls map (str => str.toInt)
+ ls.map(str => str.toInt)
In cases where Scala already knows the type of the function value we are
declaring, there is no need to annotate the parameters (in this case,
diff --git a/_th/cheatsheets/index.md b/_th/cheatsheets/index.md
index 49861d3f0c..b59cf817a3 100644
--- a/_th/cheatsheets/index.md
+++ b/_th/cheatsheets/index.md
@@ -66,9 +66,9 @@ language: "th"
| `for (i <- 1 until 5) {`
`println(i)`
`}` | ทำความเข้าใจ for : ทำซ้ำโดยละเว้นขอบเขตบน | | จับคู่รูปแบบ | | | Good
`(xs zip ys) map { case (x,y) => x*y }`
Bad
`(xs zip ys) map( (x,y) => x*y )` | ใช้ case ใน arg ของฟังก์ชันสำหรับ จับคู่รูปแบบ (pattern maching) | -| Bad
`val v42 = 42`
`Some(3) match {`
` case Some(v42) => println("42")`
` case _ => println("Not 42")`
`}` | "v42" ถูกตีความว่าเป็นชื่อที่ตรงกับค่า Int และพิมพ์ "42" | -| Good
`val v42 = 42`
`Some(3) match {`
`` case Some(`v42`) => println("42")``
`case _ => println("Not 42")`
`}` | "v42" กับ backticks ถูกตีความว่าเป็น v42 val ที่มีอยู่และ
พิมพ์ "Not 42" | -| Good
`val UppercaseVal = 42`
`Some(3) match {`
` case Some(UppercaseVal) => println("42")`
` case _ => println("Not 42")`
`}` | UppercaseVal ถือว่าเป็น val ที่มีอยู่ไม่ใช่ตัวแปรรูปแบบใหม่
เพราะมันเริ่มต้นด้วยตัวอักษรตัวพิมพ์ใหญ่ ดังนั้นค่าที่มีอยู่ใน
UppercaseVal จะถูกตรวจสอบเทียบกับ 3 และพิมพ์ "Not 42" | +| Bad
`val v42 = 42`
`Some(3) match {`
` case Some(v42) => println("42")`
` case _ => println("Not 42")`
`}` | "v42" ถูกตีความว่าเป็นชื่อที่ตรงกับค่า Int และแสดงค่า "42" | +| Good
`val v42 = 42`
`Some(3) match {`
`` case Some(`v42`) => println("42")``
`case _ => println("Not 42")`
`}` | "v42" กับ backticks ถูกตีความว่าเป็น v42 val ที่มีอยู่และ
แสดงค่า "Not 42" | +| Good
`val UppercaseVal = 42`
`Some(3) match {`
` case Some(UppercaseVal) => println("42")`
` case _ => println("Not 42")`
`}` | UppercaseVal ถือว่าเป็น val ที่มีอยู่ไม่ใช่ตัวแปรรูปแบบใหม่
เพราะมันเริ่มต้นด้วยตัวอักษรตัวพิมพ์ใหญ่ ดังนั้นค่าที่มีอยู่ใน
UppercaseVal จะถูกตรวจสอบเทียบกับ 3 และแสดงค่า "Not 42" | | การใช้งาน object | | | `class C(x: R)` _เหมือนกับ_
`class C(private val x: R)`
`var c = new C(4)` | ตัวสร้างพารามิเตอร์ - x มีเฉพาะในคลาส body เท่านั้น | | `class C(val x: R)`
`var c = new C(4)`
`c.x` | ตัวสร้างพารามิเตอร์ - กำหนดสมาชิกสาธารณะโดยอัตโนมัติ | diff --git a/_th/tour/automatic-closures.md b/_th/tour/automatic-closures.md deleted file mode 100644 index 1c30b693a9..0000000000 --- a/_th/tour/automatic-closures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: tour -title: Automatic Closures -partof: scala-tour - -language: th ---- diff --git a/_th/tour/basics.md b/_th/tour/basics.md index 48c285511e..273161fd6a 100644 --- a/_th/tour/basics.md +++ b/_th/tour/basics.md @@ -15,16 +15,14 @@ In this page, we will cover basics of Scala. ## ทดลอง Scala ในเว็บบราวเซอร์ -เราสามารถรัน Scala ในเว็บเบราว์เซอร์ด้วย ScalaFiddle +เราสามารถรัน Scala ในเว็บเบราว์เซอร์ด้วย Scastie -1. ไปที่ [https://scalafiddle.io](https://scalafiddle.io). +1. ไปที่ [Scastie](https://scastie.scala-lang.org/). 2. วาง `println("Hello, world!")` ในด้านซ้าย. 3. กดที่ปุ่ม "Run" . output จะแสดงในด้านขวา ในขั้นตอนนี้ง่ายมาก ที่จะได้ประสบการณ์ของเรากับ Scala -หลายๆ โค้ดตัวอย่างในเอกสารนี้จะฝังใน ScalaFiddle ซึ่งคุณสามารถกดที่ปุ่ม Run เพื่อดูว่าโด้นนั้นๆ จะได้ผลลัพธ์อย่างไร - ## Expressions Expression หรือ นิพจน์ เป็นโค้ดที่ทำการคำนวนได้ @@ -33,14 +31,12 @@ Expression หรือ นิพจน์ เป็นโค้ดที่ท ``` เราสามารถแสดงผลลัพธ์ของ Expression ด้วยการใช้ `println` -{% scalafiddle %} ```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! println("Hello," + " world!") // Hello, world! ``` -{% endscalafiddle %} ### Values @@ -111,21 +107,17 @@ function เป็น expression ที่รับ parameter ได้ เราสามารถตั้งชื่อของ function ได้ดังนี้ -{% scalafiddle %} ```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -{% endscalafiddle %} function สามารถรับ parameter ได้หลายตัว -{% scalafiddle %} ```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} หรือ เราจะไม่รับ parameter เลยก็ได้ @@ -140,23 +132,19 @@ Method มีลักษณะเหมือนกับ function มาก Method จะประกาศได้ด้วย keyword `def` ตามด้วยชื่อของ function, รายการ parameter, return type และ body ของ function -{% scalafiddle %} ```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} สังเกตว่า การ return type จะประกาศ _หลังจาก_ รายการ parameter และ colon `: Int` Method ยังสามารถรับรายการ parameter ได้หลายรายการ -{% scalafiddle %} ```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -{% endscalafiddle %} หรือ ไม่มีรายการ parameter เลยก็ได้ อย่างเช่น @@ -169,7 +157,6 @@ println("Hello, " + name + "!") Method สามารถมี expression ได้หลายบรรทัด -{% scalafiddle %} ```scala mdoc def getSquareString(input: Double): String = { val square = input * input @@ -177,7 +164,6 @@ def getSquareString(input: Double): String = { } println(getSquareString(2.5)) // 6.25 ``` -{% endscalafiddle %} expression สุดท้ายใน body เป็น expression ที่ return value ของ method (Scala ก็มี keyword `return` แต่ว่าไม่ค่อยได้ใช้) @@ -222,15 +208,15 @@ val yetAnotherPoint = Point(2, 2) ```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) and Point(1,2) are the same. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) and Point(2,2) are different. ``` @@ -277,7 +263,6 @@ trait Greeter { Trait สามารถมี default implementation ได้ -{% scalafiddle %} ```scala mdoc:reset trait Greeter { def greet(name: String): Unit = @@ -302,7 +287,6 @@ greeter.greet("Scala developer") // Hello, Scala developer! val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` -{% endscalafiddle %} จากตัวอย่างนี้ `defaultGreeter` ขยายเพียง trait เดียว แต่มันสามารถขยายหลาย trait @@ -310,7 +294,7 @@ customGreeter.greet("Scala developer") // How are you, Scala developer? ## Main Method -main method เป็น entry point หรือจุดเริ่มต้นของโปรแกรม ใน Java Virtual Machine +main method เป็น entry point หรือจุดเริ่มต้นของโปรแกรม ใน Java Virtual Machine ต้องการ main method ชื่อว่า `main` และสามารถรับ argument ที่เป็น array ของ string ใช้ object เราสามารถประกาศ main method ได้ดังนี้: diff --git a/_th/tour/classes.md b/_th/tour/classes.md index 7800a5f492..3054dbcc8d 100644 --- a/_th/tour/classes.md +++ b/_th/tour/classes.md @@ -11,7 +11,7 @@ next-page: traits previous-page: unified-types --- -คลาสใน Scala เป็นพิมพ์เขียวสำหรับสร้าง object ในคลาสสามารถมี method, value, ตัวแปร, type, object, +คลาสใน Scala เป็นพิมพ์เขียวสำหรับสร้าง object ในคลาสสามารถมี method, value, ตัวแปร, type, object, trait และคลาส ซึ่งเรียกรวมๆ กันว่า _members_ หรือ _สมาชิก_ ของคลาส type, object และ trait จะกล่าวถึงภายหลัง ## การกำหนดคลาส @@ -22,7 +22,7 @@ class User val user1 = new User ``` -keyword `new` ใช้เพื่อสร้าง instance ของคลาส `User` มี constructor เริ่มต้นซึ่งไม่รับค่า argument เพราะว่าไม่ได้กำหนด constructor ไว้ตอนประกาสคลาส +keyword `new` ใช้เพื่อสร้าง instance ของคลาส `User` มี constructor เริ่มต้นซึ่งไม่รับค่า argument เพราะว่าไม่ได้กำหนด constructor ไว้ตอนประกาสคลาส อย่างไรก็ตาม, เราอาจจะมี constructor และ body ของคลาส ตัวอย่างดังนี้ เป็นการประกาศคลาสสำหรับจุด (point): @@ -41,11 +41,11 @@ class Point(var x: Int, var y: Int) { val point1 = new Point(2, 3) point1.x // 2 -println(point1) // พิมพ์ (2, 3) +println(point1) // แสดงค่า (2, 3) ``` คลาส `Point` นี้มีสมาชิก 4 ตัว คือ ตัวแปร `x` และ `y` และ method `move` และ `toString` -ไม่เหมือนภาษาอื่นๆ, ซึ่ง constructor หลักจะอยู่ใน class signature `(var x: Int, var y: Int)` +ไม่เหมือนภาษาอื่นๆ, ซึ่ง constructor หลักจะอยู่ใน class signature `(var x: Int, var y: Int)` method `move` รับ argument ชนิดตัวเลข 2 ตัว และ return เป็นค่า Unit `()` ซึ่งไม่มีค่า จะมีผลลัพธ์คลายกับ `void` ในภาษาที่เหมือน Java, `toString` ในทางกลับกัน ไม่รับ argument ใดๆ แต่ return เป็นค่า `String` ซึ่งแทนที่ method `toString` จาก [`AnyRef`](unified-types.html) โดยจะมี keyword `override` @@ -58,7 +58,7 @@ class Point(var x: Int = 0, var y: Int = 0) val origin = new Point // x and y are both set to 0 val point1 = new Point(1) -println(point1.x) // พิมพ์ 1 +println(point1.x) // แสดงค่า 1 ``` @@ -68,13 +68,13 @@ println(point1.x) // พิมพ์ 1 ```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val point2 = new Point(y=2) -println(point2.y) // พิมพ์ 2 +println(point2.y) // แสดงค่า 2 ``` นี้เป็นวิธีปฏิบัติที่ดีเพื่อจะทำให้โค้ดชัดเจนมากขึ้น ## Private Members และ Getter/Setter -สมาชิกของคลาสจะเป็น public โดยค่าเริ่มต้น ใช้ access modifier `private` +สมาชิกของคลาสจะเป็น public โดยค่าเริ่มต้น ใช้ access modifier `private` เพื่อซ่อนสมาชิกนั้นจากภายนอกของคลาส ```scala mdoc:reset class Point { @@ -97,10 +97,10 @@ class Point { val point1 = new Point point1.x = 99 -point1.y = 101 // พิมพ์คำเตือน warning +point1.y = 101 // แสดงค่า "WARNING: Out of bounds" ``` -คลาส `Point` เวอร์ชันนี้ ข้อมูลจะถูกเก็บไว้ในตัวแปรชนิด private ที่ชื่อว่า `_x` และ `_y` และมี method ที่ชื่อว่า `def x` และ `def y` ทีจะใช้ในการเข้าถึงข้อมูล private เป็น getter, `def x_=` และ `def y=` -เป็น method สำหรับตรวจสอบข้อมูลและ setting ค่าของตัวแปร `_x` และ `_y` +คลาส `Point` เวอร์ชันนี้ ข้อมูลจะถูกเก็บไว้ในตัวแปรชนิด private ที่ชื่อว่า `_x` และ `_y` และมี method ที่ชื่อว่า `def x` และ `def y` ทีจะใช้ในการเข้าถึงข้อมูล private เป็น getter, `def x_=` และ `def y=` +เป็น method สำหรับตรวจสอบข้อมูลและ setting ค่าของตัวแปร `_x` และ `_y` สังเกตว่า syntax พิเศษนี้สำหรับ setter: คือ method ที่ตามด้วย `_=` ไปยังตัวระบุของ setter และ parameter ตามหลังมา constructor หลักกำหนด parameter ด้วย `val` และ `var` เป็น public อย่างไรก็ตามเพราะว่า `val` เป็นตัวแปรที่เปลี่ยนแปลงไม่ได้ (immutable) เราไม่สามารถเขียบแบบนี้ได้ diff --git a/_th/tour/named-arguments.md b/_th/tour/named-arguments.md index 161b53b50e..0257732c5d 100644 --- a/_th/tour/named-arguments.md +++ b/_th/tour/named-arguments.md @@ -10,3 +10,56 @@ language: th next-page: packages-and-imports previous-page: default-parameter-values --- + +เมื่อเราเรียกใช้ method แล้วเราสามารถระบุชื่อ argument (label the argument) สำหรับ parameter ใดๆ ได้ดังนี้: + +{% tabs named-arguments-when-good %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-good %} + +```scala mdoc +def printName(first: String, last: String): Unit = + println(s"$first $last") + +printName("John", "Public") // แสดงค่า "John Public" +printName(first = "John", last = "Public") // แสดงค่า "John Public" +printName(last = "Public", first = "John") // แสดงค่า "John Public" +printName("Elton", last = "John") // แสดงค่า "Elton John" +``` + +{% endtab %} + +{% endtabs %} + +named argument นั้นมีประโยชน์เมื่อ parameter 2 ตัวมี type เดียวกัน\ +ทำให้ argument ที่เราส่งไปให้ function อาจถูกสลับกันโดยไม่ได้ตั้งใจ + +สังเกตว่าเราจะเขียน argument ที่ระบุชื่อในลำดับใดก็ได้\ +แต่ถ้า argument ไม่ได้อยู่ในลำดับของ parameter ใน function จากซ้ายไปขวา แล้ว argument ที่เหลือจะต้องระบุชื่อทั้งหมด + +ในตัวอย่างข้างล่างนี้ named argument ทำให้เราสามารถเว้น parameter `middle` ได้\ +แต่ในกรณีที่เกิด `error: positional after named argument`\ +เนื่องจาก argument ตัวแรกไม่ได้เรียงตามลำดับของ parameter (ตัวแรกไม่ใช่ parameter `first` และ argument ตัวที่ 2 เป็นต้นไปก็ไม่ได้ระบุชื่อด้วย)\ +ดังนั้น เราจะต้องระบุชื่อ argument ตั้งแต่ตัวที่ 2 เป็นต้นไป + +{% tabs named-arguments-when-error %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-error %} + +```scala mdoc:fail +def printFullName(first: String, middle: String = "Q.", last: String): Unit = + println(s"$first $middle $last") + +printFullName(first = "John", last = "Public") // แสดงค่า "John Q. Public" +printFullName("John", last = "Public") // แสดงค่า "John Q. Public" +printFullName("John", middle = "Quincy", "Public") // แสดงค่า "John Quincy Public" +printFullName(last = "Public", first = "John") // แสดงค่า "John Q. Public" +printFullName(last = "Public", "John") // error: positional after named argument +``` + +{% endtab %} + +{% endtabs %} + +เราสามารถใช้ Named Argument กับการเรียกใช้ method ของ Java ได้\ +แต่ทำได้เฉพาะในกรณีที่ Java library นั้นถูกคอมไพล์ด้วยออพชั่น `-parameters` เท่านั้น diff --git a/_th/tour/tour-of-scala.md b/_th/tour/tour-of-scala.md index f10a88d77d..ab75a7d541 100644 --- a/_th/tour/tour-of-scala.md +++ b/_th/tour/tour-of-scala.md @@ -13,7 +13,7 @@ next-page: basics ## ยินดีต้อนรับสู่การเดินทาง การเดินทางครั้งนี้ประกอบด้วยการแนะนำแบบสั้นๆ สำหรับแต่ล่ะคุณสมบัติของ Scala ที่ใช้บ่อยที่สุด และมีมีความตั้งใจเพื่อสำหรับผู้ที่เรียนรู้ภาษา Scala ใหม่ -และนี่ก็เป็นเพียงบทความสั้นๆ ที่ไม่ใช้การสอนเต็มรูปแบบของภาษา Scala หากต้องการเรียนรู้มากขึ้นให้พิจารณา[หนังสือ](/books.html) หรือขอคำปรึกษาจาก[แหล่งอื่นๆ](/learn.html) +และนี่ก็เป็นเพียงบทความสั้นๆ ที่ไม่ใช้การสอนเต็มรูปแบบของภาษา Scala หากต้องการเรียนรู้มากขึ้นให้พิจารณา[หนังสือ](/books.html) หรือขอคำปรึกษาจาก[แหล่งอื่นๆ](/online-courses.html) ## อะไรคือ Scala? Scala เป็นภาษาเขียนโปรแกรมแบบหลากหลายกระบวนทัศน์ที่ทันสมัย ที่ออกแบบมาเพื่อแสดงรูปแบบการเขียนโปรแกรมโดยทั่วไปที่กระชับ สง่างาม และมีชนิดข้อมูลที่ปลอดภัย (type-safe) ซึ่งผสานคุณสมบัติของภาษาเชิงวัตถุและภาษาเชิงฟังก์ชัน diff --git a/_th/tour/traits.md b/_th/tour/traits.md index dfc3b31a74..92dc07597c 100644 --- a/_th/tour/traits.md +++ b/_th/tour/traits.md @@ -75,7 +75,7 @@ val cat = new Cat("Sally") val animals = ArrayBuffer.empty[Pet] animals.append(dog) animals.append(cat) -animals.foreach(pet => println(pet.name)) // พิมพ์ Harry Sally +animals.foreach(pet => println(pet.name)) // แสดงค่า Harry Sally ``` -`trait Pet` มี abstract field `name` ซึ่ง implement โดย Cat และ Dog ใน constructor ของมัน +`trait Pet` มี abstract field `name` ซึ่ง implement โดย Cat และ Dog ใน constructor ของมัน ในบรรทัดสุดท้าย เราเรียก `pet.name` ซึ่งจะต้องถูก implement แล้วใน subtype ใดๆ ของ trait `Pet` diff --git a/_th/tour/unified-types.md b/_th/tour/unified-types.md index 7e92c8a39f..4c2b24c48a 100644 --- a/_th/tour/unified-types.md +++ b/_th/tour/unified-types.md @@ -57,7 +57,7 @@ Value type สามารถแปลได้ด้วยวิธีดัง ```scala mdoc val x: Long = 987654321 -val y: Float = x // 9.8765434E8 (หมายเหตุว่าค่าความละเอียดจะสูญหายไปในกรณีนี้) +val y: Float = x.toFloat // 9.8765434E8 (หมายเหตุว่าค่าความละเอียดจะสูญหายไปในกรณีนี้) val face: Char = '☺' val number: Int = face // 9786 @@ -67,7 +67,7 @@ val number: Int = face // 9786 ``` val x: Long = 987654321 -val y: Float = x // 9.8765434E8 +val y: Float = x.toFloat // 9.8765434E8 val z: Long = y // ไม่เป็นไปตามที่ต้องการ ``` diff --git a/_tour/abstract-type-members.md b/_tour/abstract-type-members.md index 8cad19b617..aef46a52b2 100644 --- a/_tour/abstract-type-members.md +++ b/_tour/abstract-type-members.md @@ -8,22 +8,37 @@ previous-page: inner-classes topics: abstract type members prerequisite-knowledge: variance, upper-type-bound -redirect_from: "/tutorials/tour/abstract-types.html" -redirect_from: "/tour/abstract-types.html" +redirect_from: + - "/tutorials/tour/abstract-types.html" + - "/tour/abstract-types.html" --- Abstract types, such as traits and abstract classes, can in turn have abstract type members. This means that the concrete implementations define the actual types. Here's an example: +{% tabs abstract-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_1 %} ```scala mdoc trait Buffer { type T val element: T } ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_1 %} +```scala +trait Buffer: + type T + val element: T +``` +{% endtab %} +{% endtabs %} + Here we have defined an abstract `type T`. It is used to describe the type of `element`. We can extend this trait in an abstract class, adding an upper-type-bound to `T` to make it more specific. +{% tabs abstract-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_2 %} ```scala mdoc abstract class SeqBuffer extends Buffer { type U @@ -31,29 +46,61 @@ abstract class SeqBuffer extends Buffer { def length = element.length } ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_2 %} +```scala +abstract class SeqBuffer extends Buffer: + type U + type T <: Seq[U] + def length = element.length +``` +{% endtab %} +{% endtabs %} + Notice how we can use yet another abstract type `U` in the specification of an upper-type-bound for `T`. This `class SeqBuffer` allows us to store only sequences in the buffer by stating that type `T` has to be a subtype of `Seq[U]` for a new abstract type `U`. Traits or [classes](classes.html) with abstract type members are often used in combination with anonymous class instantiations. To illustrate this, we now look at a program which deals with a sequence buffer that refers to a list of integers: +{% tabs abstract-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_3 %} ```scala mdoc abstract class IntSeqBuffer extends SeqBuffer { type U = Int } - def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = new IntSeqBuffer { - type T = List[U] - val element = List(elem1, elem2) - } + type T = List[U] + val element = List(elem1, elem2) + } val buf = newIntSeqBuf(7, 8) println("length = " + buf.length) println("content = " + buf.element) ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_3 %} +```scala +abstract class IntSeqBuffer extends SeqBuffer: + type U = Int + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer: + type T = List[U] + val element = List(elem1, elem2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% endtabs %} + Here the factory `newIntSeqBuf` uses an anonymous class implementation of `IntSeqBuffer` (i.e. `new IntSeqBuffer`) to set the abstract type `T` to the concrete type `List[Int]`. It is also possible to turn abstract type members into type parameters of classes and vice versa. Here is a version of the code above which only uses type parameters: +{% tabs abstract-types_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_4 %} ```scala mdoc:nest abstract class Buffer[+T] { val element: T @@ -71,5 +118,24 @@ val buf = newIntSeqBuf(7, 8) println("length = " + buf.length) println("content = " + buf.element) ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_4 %} +```scala +abstract class Buffer[+T]: + val element: T + +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T]: + def length = element.length + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]]: + val element = List(e1, e2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% endtabs %} Note that we have to use [variance annotations](variances.html) here (`+T <: Seq[U]`) in order to hide the concrete sequence implementation type of the object returned from method `newIntSeqBuf`. Furthermore, there are cases where it is not possible to replace abstract type members with type parameters. diff --git a/_tour/annotations.md b/_tour/annotations.md index bdd39a09b7..a9876fab42 100644 --- a/_tour/annotations.md +++ b/_tour/annotations.md @@ -11,14 +11,29 @@ redirect_from: "/tutorials/tour/annotations.html" --- Annotations associate meta-information with definitions. For example, the annotation `@deprecated` before a method causes the compiler to print a warning if the method is used. -``` + +{% tabs annotations_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_1 %} +```scala mdoc:fail object DeprecationDemo extends App { @deprecated("deprecation message", "release # which deprecates method") def hello = "hola" - hello + hello } ``` +{% endtab %} +{% tab 'Scala 3' for=annotations_1 %} +```scala +object DeprecationDemo extends App: + @deprecated("deprecation message", "release # which deprecates method") + def hello = "hola" + + hello +``` +{% endtab %} +{% endtabs %} + This will compile but the compiler will print a warning: "there was one deprecation warning". An annotation clause applies to the first definition or declaration following it. More than one annotation clause may precede a definition and declaration. The order in which these clauses are given does not matter. @@ -26,6 +41,9 @@ An annotation clause applies to the first definition or declaration following it ## Annotations that ensure correctness of encodings Certain annotations will actually cause compilation to fail if a condition(s) is not met. For example, the annotation `@tailrec` ensures that a method is [tail-recursive](https://en.wikipedia.org/wiki/Tail_call). Tail-recursion can keep memory requirements constant. Here's how it's used in a method which calculates the factorial: + +{% tabs annotations_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_2 %} ```scala mdoc import scala.annotation.tailrec @@ -38,8 +56,26 @@ def factorial(x: Int): Int = { factorialHelper(x, 1) } ``` -The `factorialHelper` method has the `@tailrec` which ensures the method is indeed tail-recursive. If we were to change the implementation of `factorialHelper` to the following, it would fail: +{% endtab %} +{% tab 'Scala 3' for=annotations_2 %} +```scala +import scala.annotation.tailrec + +def factorial(x: Int): Int = + + @tailrec + def factorialHelper(x: Int, accumulator: Int): Int = + if x == 1 then accumulator else factorialHelper(x - 1, accumulator * x) + factorialHelper(x, 1) ``` +{% endtab %} +{% endtabs %} + +The `factorialHelper` method has the `@tailrec` which ensures the method is indeed tail-recursive. If we were to change the implementation of `factorialHelper` to the following, it would fail: + +{% tabs annotations_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_3 %} +```scala mdoc:fail import scala.annotation.tailrec def factorial(x: Int): Int = { @@ -50,76 +86,134 @@ def factorial(x: Int): Int = { factorialHelper(x) } ``` -We would get the message "Recursive call not in tail position". +{% endtab %} +{% tab 'Scala 3' for=annotations_3 %} +```scala +import scala.annotation.tailrec +def factorial(x: Int): Int = + @tailrec + def factorialHelper(x: Int): Int = + if x == 1 then 1 else x * factorialHelper(x - 1) + factorialHelper(x) +``` +{% endtab %} +{% endtabs %} + +We would get the message "Recursive call not in tail position". ## Annotations affecting code generation + +{% tabs annotations_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_4 %} + Some annotations like `@inline` affect the generated code (i.e. your jar file might have different bytes than if you hadn't used the annotation). Inlining means inserting the code in a method's body at the call site. The resulting bytecode is longer, but hopefully runs faster. Using the annotation `@inline` does not ensure that a method will be inlined, but it will cause the compiler to do it if and only if some heuristics about the size of the generated code are met. +{% endtab %} +{% tab 'Scala 3' for=annotations_4 %} + +Some annotations like `@main` affect the generated code (i.e. your jar file might have different bytes than if you hadn't used the annotation). A `@main` annotation on a method generates an executable program that calls the method as an entry point. + +{% endtab %} +{% endtabs %} + ### Java Annotations ### When writing Scala code which interoperates with Java, there are a few differences in annotation syntax to note. **Note:** Make sure you use the `-target:jvm-1.8` option with Java annotations. Java has user-defined metadata in the form of [annotations](https://docs.oracle.com/javase/tutorial/java/annotations/). A key feature of annotations is that they rely on specifying name-value pairs to initialize their elements. For instance, if we need an annotation to track the source of some class we might define it as -``` +{% tabs annotations_5 %} +{% tab 'Java' for=annotations_5 %} +```java @interface Source { - public String URL(); + public String url(); public String mail(); } ``` +{% endtab %} +{% endtabs %} And then apply it as follows -``` -@Source(URL = "https://coders.com/", +{% tabs annotations_6 %} +{% tab 'Java' for=annotations_6 %} +```java +@Source(url = "https://coders.com/", mail = "support@coders.com") -public class MyClass extends TheirClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -An annotation application in Scala looks like a constructor invocation, for instantiating a Java annotation one has to use named arguments: +An annotation application in Scala looks like a constructor invocation, but to instantiate a Java annotation one has to use named arguments: -``` -@Source(URL = "https://coders.com/", +{% tabs annotations_7 %} +{% tab 'Scala 2 and 3' for=annotations_7 %} +```scala +@Source(url = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} This syntax is quite tedious if the annotation contains only one element (without default value) so, by convention, if the name is specified as `value` it can be applied in Java using a constructor-like syntax: -``` +{% tabs annotations_8 %} +{% tab 'Java' for=annotations_8 %} +```java @interface SourceURL { public String value(); public String mail() default ""; } ``` +{% endtab %} +{% endtabs %} -And then apply it as follows +And then apply it as follows: -``` +{% tabs annotations_9 %} +{% tab 'Java' for=annotations_9 %} +```java @SourceURL("https://coders.com/") -public class MyClass extends TheirClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -In this case, Scala provides the same possibility +In this case, Scala provides the same possibility: -``` +{% tabs annotations_10 %} +{% tab 'Scala 2 and 3' for=annotations_10 %} +```scala @SourceURL("https://coders.com/") class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} -The `mail` element was specified with a default value so we need not explicitly provide a value for it. However, if we need to do it we can not mix-and-match the two styles in Java: +The `mail` element was specified with a default value so we need not explicitly provide a value for it. +However, if we need to provide one then in Java we must also explicitly name the `value` parameter: -``` +{% tabs annotations_11 %} +{% tab 'Java' for=annotations_11 %} +```java @SourceURL(value = "https://coders.com/", mail = "support@coders.com") -public class MyClass extends TheirClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -Scala provides more flexibility in this respect +Scala provides more flexibility in this respect, so we can choose to only name the `mail` parameter: -``` +{% tabs annotations_12 %} +{% tab 'Scala 2 and 3' for=annotations_12 %} +```scala @SourceURL("https://coders.com/", mail = "support@coders.com") - class MyScalaClass ... +class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} diff --git a/_tour/automatic-closures.md b/_tour/automatic-closures.md deleted file mode 100644 index 7df0b975ab..0000000000 --- a/_tour/automatic-closures.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: tour -title: Automatic Type-Dependent Closure Construction -partof: scala-tour - -redirect_from: "/tutorials/tour/automatic-closures.html" ---- - -Scala allows parameterless function names as parameters of methods. When such a method is called, the actual parameters for parameterless function names are not evaluated and a nullary function is passed instead which encapsulates the computation of the corresponding parameter (so-called *call-by-name* evaluation). - -The following code demonstrates this mechanism: - - object TargetTest1 extends Application { - def whileLoop(cond: => Boolean)(body: => Unit): Unit = - if (cond) { - body - whileLoop(cond)(body) - } - var i = 10 - whileLoop (i > 0) { - println(i) - i -= 1 - } - } - -The function whileLoop takes two parameters `cond` and `body`. When the function is applied, the actual parameters do not get evaluated. But whenever the formal parameters are used in the body of `whileLoop`, the implicitly created nullary functions will be evaluated instead. Thus, our method `whileLoop` implements a Java-like while-loop with a recursive implementation scheme. - -We can combine the use of [infix/postfix operators](operators.html) with this mechanism to create more complex statements (with a nice syntax). - -Here is the implementation of a loop-unless statement: - - object TargetTest2 extends Application { - def loop(body: => Unit): LoopUnlessCond = - new LoopUnlessCond(body) - protected class LoopUnlessCond(body: => Unit) { - def unless(cond: => Boolean) { - body - if (!cond) unless(cond) - } - } - var i = 10 - loop { - println("i = " + i) - i -= 1 - } unless (i == 0) - } -The `loop` function just accepts a body of a loop and returns an instance of class `LoopUnlessCond` (which encapsulates this body object). Note that the body didn't get evaluated yet. Class `LoopUnlessCond` has a method `unless` which we can use as a *infix operator*. This way, we achieve a quite natural syntax for our new loop: `loop { < stats > } unless ( < cond > )`. - -Here's the output when `TargetTest2` gets executed: - - i = 10 - i = 9 - i = 8 - i = 7 - i = 6 - i = 5 - i = 4 - i = 3 - i = 2 - i = 1 diff --git a/_tour/basics.md b/_tour/basics.md index f5acd95ab3..ccfb324feb 100644 --- a/_tour/basics.md +++ b/_tour/basics.md @@ -14,72 +14,98 @@ In this page, we will cover the basics of Scala. ## Trying Scala in the Browser -You can run Scala in your browser with _ScalaFiddle_. This is an easy, zero-setup way to experiment with pieces of Scala code: +You can run Scala in your browser with _Scastie_. This is an easy, zero-setup way to experiment with pieces of Scala code: -1. Go to [https://scalafiddle.io](https://scalafiddle.io). +1. Go to [Scastie](https://scastie.scala-lang.org/). 2. Paste `println("Hello, world!")` in the left pane. 3. Click __Run__. The output appears in the right pane. -_ScalaFiddle_ is integrated with some of the code examples in this documentation; if you see a __Run__ button in a code example below, click it to directly experiment with the code. - ## Expressions Expressions are computable statements: + +{% tabs expression %} +{% tab 'Scala 2 and 3' for=expression %} ```scala mdoc 1 + 1 ``` +{% endtab %} +{% endtabs %} + You can output the results of expressions using `println`: -{% scalafiddle %} +{% tabs println %} +{% tab 'Scala 2 and 3' for=println %} ```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! println("Hello," + " world!") // Hello, world! ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} ### Values You can name the results of expressions using the `val` keyword: +{% tabs val %} +{% tab 'Scala 2 and 3' for=val %} ```scala mdoc val x = 1 + 1 println(x) // 2 ``` +{% endtab %} +{% endtabs %} Named results, such as `x` here, are called values. Referencing a value does not re-compute it. Values cannot be re-assigned: +{% tabs val-error %} +{% tab 'Scala 2 and 3' for=val-error %} ```scala mdoc:fail x = 3 // This does not compile. ``` +{% endtab %} +{% endtabs %} The type of a value can be omitted and [inferred](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated: +{% tabs type-inference %} +{% tab 'Scala 2 and 3' for=type-inference %} ```scala mdoc:nest val x: Int = 1 + 1 ``` +{% endtab %} +{% endtabs %} -Notice how the type declaration `Int` comes after the identifier `x`. You also need a `:`. +Notice how the type declaration `Int` comes after the identifier `x`. You also need a `:`. ### Variables Variables are like values, except you can re-assign them. You can define a variable with the `var` keyword. +{% tabs var %} +{% tab 'Scala 2 and 3' for=var %} ```scala mdoc:nest var x = 1 + 1 x = 3 // This compiles because "x" is declared with the "var" keyword. println(x * x) // 9 ``` +{% endtab %} +{% endtabs %} As with values, the type of a variable can be omitted and [inferred](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated: +{% tabs type-inference-2 %} +{% tab 'Scala 2 and 3' for=type-inference-2 %} ```scala mdoc:nest var x: Int = 1 + 1 ``` +{% endtab %} +{% endtabs %} ## Blocks @@ -88,12 +114,16 @@ You can combine expressions by surrounding them with `{}`. We call this a block. The result of the last expression in the block is the result of the overall block, too: +{% tabs blocks %} +{% tab 'Scala 2 and 3' for=blocks %} ```scala mdoc println({ val x = 1 + 1 x + 1 }) // 3 ``` +{% endtab %} +{% endtabs %} ## Functions @@ -101,36 +131,48 @@ Functions are expressions that have parameters, and take arguments. You can define an anonymous function (i.e., a function that has no name) that returns a given integer plus one: +{% tabs anonymous-function %} +{% tab 'Scala 2 and 3' for=anonymous-function %} ```scala mdoc (x: Int) => x + 1 ``` +{% endtab %} +{% endtabs %} On the left of `=>` is a list of parameters. On the right is an expression involving the parameters. You can also name functions: -{% scalafiddle %} +{% tabs named-function %} +{% tab 'Scala 2 and 3' for=named-function %} ```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} A function can have multiple parameters: -{% scalafiddle %} +{% tabs multiple-parameters %} +{% tab 'Scala 2 and 3' for=multiple-parameters %} ```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} Or it can have no parameters at all: +{% tabs no-parameters %} +{% tab 'Scala 2 and 3' for=no-parameters %} ```scala mdoc val getTheAnswer = () => 42 println(getTheAnswer()) // 42 ``` +{% endtab %} +{% endtabs %} ## Methods @@ -138,36 +180,46 @@ Methods look and behave very similar to functions, but there are a few key diffe Methods are defined with the `def` keyword. `def` is followed by a name, parameter list(s), a return type, and a body: -{% scalafiddle %} +{% tabs method %} +{% tab 'Scala 2 and 3' for=method %} ```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} Notice how the return type `Int` is declared _after_ the parameter list and a `:`. A method can take multiple parameter lists: -{% scalafiddle %} +{% tabs multiple-parameter-lists %} +{% tab 'Scala 2 and 3' for=multiple-parameter-lists %} ```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} Or no parameter lists at all: +{% tabs no-parameter-lists %} +{% tab 'Scala 2 and 3' for=no-parameter-lists %} ```scala mdoc def name: String = System.getProperty("user.name") println("Hello, " + name + "!") ``` +{% endtab %} +{% endtabs %} There are some other differences, but for now, you can think of methods as something similar to functions. Methods can have multi-line expressions as well: -{% scalafiddle %} +{% tabs get-square-string class=tabs-scala-version %} + +{% tab 'Scala 2' for=get-square-string %} ```scala mdoc def getSquareString(input: Double): String = { val square = input * input @@ -175,7 +227,19 @@ def getSquareString(input: Double): String = { } println(getSquareString(2.5)) // 6.25 ``` -{% endscalafiddle %} +{% endtab %} + +{% tab 'Scala 3' for=get-square-string %} +```scala +def getSquareString(input: Double): String = + val square = input * input + square.toString + +println(getSquareString(2.5)) // 6.25 +``` +{% endtab %} + +{% endtabs %} The last expression in the body is the method's return value. (Scala does have a `return` keyword, but it is rarely used.) @@ -183,20 +247,48 @@ The last expression in the body is the method's return value. (Scala does have a You can define classes with the `class` keyword, followed by its name and constructor parameters: +{% tabs greeter-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-definition %} ```scala mdoc class Greeter(prefix: String, suffix: String) { def greet(name: String): Unit = println(prefix + name + suffix) } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-definition %} +```scala +class Greeter(prefix: String, suffix: String): + def greet(name: String): Unit = + println(prefix + name + suffix) +``` +{% endtab %} + +{% endtabs %} + The return type of the method `greet` is `Unit`, which signifies that there is nothing meaningful to return. It is used similarly to `void` in Java and C. (A difference is that, because every Scala expression must have some value, there is actually a singleton value of type Unit, written (). It carries no information.) -You can make an instance of a class with the `new` keyword: +In Scala 2 you can make an instance of a class with the `new` keyword. In Scala 3, however, the `new` keyword is not needed thanks to [universal apply methods](https://docs.scala-lang.org/scala3/reference/other-new-features/creator-applications.html): +{% tabs greeter-usage class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-usage %} ```scala mdoc:nest val greeter = new Greeter("Hello, ", "!") greeter.greet("Scala developer") // Hello, Scala developer! ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-usage %} +```scala +val greeter = Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` +{% endtab %} + +{% endtabs %} We will cover classes in depth [later](classes.html). @@ -206,33 +298,63 @@ Scala has a special type of class called a "case" class. By default, instances o You can define case classes with the `case class` keywords: +{% tabs case-class-definition %} +{% tab 'Scala 2 and 3' for=case-class-definition %} ```scala mdoc case class Point(x: Int, y: Int) ``` +{% endtab %} +{% endtabs %} You can instantiate case classes without the `new` keyword: +{% tabs case-class-creation %} +{% tab 'Scala 2 and 3' for=case-class-creation %} ```scala mdoc val point = Point(1, 2) val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) ``` +{% endtab %} +{% endtabs %} Instances of case classes are compared by value, not by reference: +{% tabs compare-case-class-equality class=tabs-scala-version %} + +{% tab 'Scala 2' for=compare-case-class-equality %} ```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) and Point(1,2) are the same. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) and Point(2,2) are different. ``` +{% endtab %} + +{% tab 'Scala 3' for=compare-case-class-equality %} +```scala +if point == anotherPoint then + println(s"$point and $anotherPoint are the same.") +else + println(s"$point and $anotherPoint are different.") +// ==> Point(1,2) and Point(1,2) are the same. + +if point == yetAnotherPoint then + println(s"$point and $yetAnotherPoint are the same.") +else + println(s"$point and $yetAnotherPoint are different.") +// ==> Point(1,2) and Point(2,2) are different. +``` +{% endtab %} + +{% endtabs %} There is a lot more to case classes that we would like to introduce, and we are convinced you will fall in love with them! We will cover them in depth [later](case-classes.html). @@ -242,6 +364,9 @@ Objects are single instances of their own definitions. You can think of them as You can define objects with the `object` keyword: +{% tabs id-factory-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=id-factory-definition %} ```scala mdoc object IdFactory { private var counter = 0 @@ -251,15 +376,32 @@ object IdFactory { } } ``` +{% endtab %} + +{% tab 'Scala 3' for=id-factory-definition %} +```scala +object IdFactory: + private var counter = 0 + def create(): Int = + counter += 1 + counter +``` +{% endtab %} + +{% endtabs %} You can access an object by referring to its name: +{% tabs id-factory-usage %} +{% tab 'Scala 2 and 3' for=id-factory-usage %} ```scala mdoc val newId: Int = IdFactory.create() println(newId) // 1 val newerId: Int = IdFactory.create() println(newerId) // 2 ``` +{% endtab %} +{% endtabs %} We will cover objects in depth [later](singleton-objects.html). @@ -269,24 +411,53 @@ Traits are abstract data types containing certain fields and methods. In Scala i You can define traits with the `trait` keyword: +{% tabs greeter-trait-def class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-trait-def %} ```scala mdoc:nest trait Greeter { def greet(name: String): Unit } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def %} +```scala +trait Greeter: + def greet(name: String): Unit +``` +{% endtab %} + +{% endtabs %} Traits can also have default implementations: -{% scalafiddle %} +{% tabs greeter-trait-def-impl class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-trait-def-impl %} ```scala mdoc:reset trait Greeter { def greet(name: String): Unit = println("Hello, " + name + "!") } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def-impl %} +```scala +trait Greeter: + def greet(name: String): Unit = + println("Hello, " + name + "!") +``` +{% endtab %} + +{% endtabs %} You can extend traits with the `extends` keyword and override an implementation with the `override` keyword: +{% tabs greeter-implementations class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-implementations %} ```scala mdoc class DefaultGreeter extends Greeter @@ -302,19 +473,41 @@ greeter.greet("Scala developer") // Hello, Scala developer! val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` -{% endscalafiddle %} +{% endtab %} + +{% tab 'Scala 3' for=greeter-implementations %} +```scala +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter: + override def greet(name: String): Unit = + println(prefix + name + postfix) + +val greeter = DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` +{% endtab %} + +{% endtabs %} Here, `DefaultGreeter` extends only one single trait, but it could extend multiple traits. We will cover traits in depth [later](traits.html). -## Main Method +## Program Entry Point The main method is the entry point of a Scala program. The Java Virtual Machine requires a main method, named `main`, that takes one argument: an array of strings. -Using an object, you can define the main method as follows: +{% tabs hello-world-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-demo %} + +In Scala 2 you must define a main method manually. Using an object, you can define the main method as follows: ```scala mdoc object Main { @@ -322,7 +515,19 @@ object Main { println("Hello, Scala developer!") } ``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} + +In Scala 3, with the `@main` annotation, a main method is automatically generated from a method as follows: + +```scala +@main def hello() = println("Hello, Scala developer!") +``` +{% endtab %} + +{% endtabs %} ## More resources -* [Scala book](/overviews/scala-book/prelude-taste-of-scala.html) overview +* [Scala book](/scala3/book/taste-intro.html) overview diff --git a/_tour/by-name-parameters.md b/_tour/by-name-parameters.md index 6d0ff8b610..441aefa597 100644 --- a/_tour/by-name-parameters.md +++ b/_tour/by-name-parameters.md @@ -8,16 +8,25 @@ next-page: annotations previous-page: operators redirect_from: "/tutorials/tour/by-name-parameters.html" +redirect_from: "/tutorials/tour/automatic-closures.html" --- _By-name parameters_ are evaluated every time they are used. They won't be evaluated at all if they are unused. This is similar to replacing the by-name parameters with the passed expressions. They are in contrast to _by-value parameters_. To make a parameter called by-name, simply prepend `=>` to its type. + +{% tabs by-name-parameters_1 %} +{% tab 'Scala 2 and 3' for=by-name-parameters_1 %} ```scala mdoc def calculate(input: => Int) = input * 37 ``` +{% endtab %} +{% endtabs %} + By-name parameters have the advantage that they are not evaluated if they aren't used in the function body. On the other hand, by-value parameters have the advantage that they are evaluated only once. Here's an example of how we could implement a while loop: +{% tabs by-name-parameters_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=by-name-parameters_2 %} ```scala mdoc def whileLoop(condition: => Boolean)(body: => Unit): Unit = if (condition) { @@ -32,6 +41,24 @@ whileLoop (i > 0) { i -= 1 } // prints 2 1 ``` +{% endtab %} +{% tab 'Scala 3' for=by-name-parameters_2 %} +```scala +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if condition then + body + whileLoop(condition)(body) + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // prints 2 1 +``` +{% endtab %} +{% endtabs %} + The method `whileLoop` uses multiple parameter lists to take a condition and a body of the loop. If the `condition` is true, the `body` is executed and then a recursive call to whileLoop is made. If the `condition` is false, the body is never evaluated because we prepended `=>` to the type of `body`. Now when we pass `i > 0` as our `condition` and `println(i); i-= 1` as the `body`, it behaves like the standard while loop in many languages. diff --git a/_tour/case-classes.md b/_tour/case-classes.md index b05756f81b..889f8e98bc 100644 --- a/_tour/case-classes.md +++ b/_tour/case-classes.md @@ -15,14 +15,26 @@ Case classes are like regular classes with a few key differences which we will g ## Defining a case class A minimal case class requires the keywords `case class`, an identifier, and a parameter list (which may be empty): + +{% tabs case-classe_Book %} + +{% tab 'Scala 2 and 3' for=case-classe_Book %} ```scala mdoc case class Book(isbn: String) val frankenstein = Book("978-0486282114") ``` -Notice how the keyword `new` was not used to instantiate the `Book` case class. This is because case classes have an `apply` method by default which takes care of object construction. +{% endtab %} + +{% endtabs %} + +Although that is usually left out, it is possible to explicitly use the `new` keyword, as `new Book()`. This is because case classes have an `apply` method by default which takes care of object construction. When you create a case class with parameters, the parameters are public `val`s. + +{% tabs case-classe_Message_define %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_define %} ``` case class Message(sender: String, recipient: String, body: String) val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") @@ -30,10 +42,18 @@ val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") println(message1.sender) // prints guillaume@quebec.ca message1.sender = "travis@washington.us" // this line does not compile ``` +{% endtab %} + +{% endtabs %} + You can't reassign `message1.sender` because it is a `val` (i.e. immutable). It is possible to use `var`s in case classes but this is discouraged. ## Comparison Instances of case classes are compared by structure and not by reference: + +{% tabs case-classe_Message_compare %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_compare %} ```scala mdoc case class Message(sender: String, recipient: String, body: String) @@ -41,10 +61,18 @@ val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") val messagesAreTheSame = message2 == message3 // true ``` +{% endtab %} + +{% endtabs %} + Even though `message2` and `message3` refer to different objects, the value of each object is equal. ## Copying You can create a (shallow) copy of an instance of a case class simply by using the `copy` method. You can optionally change the constructor arguments. + +{% tabs case-classe_Message_copy %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_copy %} ```scala mdoc:nest case class Message(sender: String, recipient: String, body: String) val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") @@ -53,8 +81,12 @@ message5.sender // travis@washington.us message5.recipient // claire@bourgogne.fr message5.body // "Me zo o komz gant ma amezeg" ``` +{% endtab %} + +{% endtabs %} + The recipient of `message4` is used as the sender of `message5` but the `body` of `message4` was copied directly. ## More resources -* Learn more about case classes in the [Scala Book](/overviews/scala-book/case-classes.html) +* Learn more about case classes in the [Scala Book](/scala3/book/domain-modeling-tools.html#case-classes) diff --git a/_tour/classes.md b/_tour/classes.md index 47b5079bc5..683ae049cf 100644 --- a/_tour/classes.md +++ b/_tour/classes.md @@ -18,13 +18,37 @@ values, variables, types, objects, traits, and classes which are collectively ca ## Defining a class A minimal class definition is simply the keyword `class` and an identifier. Class names should be capitalized. + +{% tabs class-minimal-user class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-minimal-user %} ```scala mdoc class User val user1 = new User ``` -The keyword `new` is used to create an instance of the class. `User` has a default constructor which takes no arguments because no constructor was defined. However, you'll often want a constructor and class body. Here is an example class definition for a point: +The keyword `new` is used to create an instance of the class. +{% endtab %} + +{% tab 'Scala 3' for=class-minimal-user %} +```scala +class User + +val user1 = User() +``` + +We call the class like a function, as `User()`, to create an instance of the class. +It is also possible to explicitly use the `new` keyword, as `new User()`, although that is usually left out. +{% endtab %} + +{% endtabs %} + +`User` has a default constructor which takes no arguments because no constructor was defined. However, you'll often want a constructor and class body. Here is an example class definition for a point: + +{% tabs class-point-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-example %} ```scala mdoc class Point(var x: Int, var y: Int) { @@ -38,78 +62,205 @@ class Point(var x: Int, var y: Int) { } val point1 = new Point(2, 3) -println(point1.x) // 2 -println(point1) // prints (2, 3) +println(point1.x) // prints 2 +println(point1) // prints (2, 3) ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-example %} +```scala +class Point(var x: Int, var y: Int): + + def move(dx: Int, dy: Int): Unit = + x = x + dx + y = y + dy + + override def toString: String = + s"($x, $y)" +end Point + +val point1 = Point(2, 3) +println(point1.x) // prints 2 +println(point1) // prints (2, 3) +``` +{% endtab %} + +{% endtabs %} This `Point` class has four members: the variables `x` and `y` and the methods `move` and -`toString`. Unlike many other languages, the primary constructor is in the class signature `(var x: Int, var y: Int)`. The `move` method takes two integer arguments and returns the Unit value `()`, which carries no information. This corresponds roughly with `void` in Java-like languages. `toString`, on the other hand, does not take any arguments but returns a `String` value. Since `toString` overrides `toString` from [`AnyRef`](unified-types.html), it is tagged with the `override` keyword. +`toString`. Unlike many other languages, the primary constructor is in the class signature `(var x: Int, var y: Int)`. The `move` method takes two integer arguments and returns the Unit value `()`, which carries no information. This corresponds roughly to `void` in Java-like languages. `toString`, on the other hand, does not take any arguments but returns a `String` value. Since `toString` overrides `toString` from [`AnyRef`](unified-types.html), it is tagged with the `override` keyword. ## Constructors Constructors can have optional parameters by providing a default value like so: +{% tabs class-point-with-default-values class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-with-default-values %} ```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) -val origin = new Point // x and y are both set to 0 -val point1 = new Point(1) -println(point1.x) // prints 1 +val origin = new Point // x and y are both set to 0 +val point1 = new Point(1) // x is set to 1 and y is set to 0 +println(point1) // prints (1, 0) +``` +{% endtab %} +{% tab 'Scala 3' for=class-point-with-default-values %} +```scala +class Point(var x: Int = 0, var y: Int = 0) + +val origin = Point() // x and y are both set to 0 +val point1 = Point(1) // x is set to 1 and y is set to 0 +println(point1) // prints (1, 0) ``` +{% endtab %} + +{% endtabs %} In this version of the `Point` class, `x` and `y` have the default value `0` so no arguments are required. However, because the constructor reads arguments left to right, if you just wanted to pass in a `y` value, you would need to name the parameter. + +{% tabs class-point-named-argument class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-named-argument %} ```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val point2 = new Point(y = 2) -println(point2.y) // prints 2 +println(point2) // prints (0, 2) +``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-named-argument %} +```scala +class Point(var x: Int = 0, var y: Int = 0) +val point2 = Point(y = 2) +println(point2) // prints (0, 2) ``` +{% endtab %} + +{% endtabs %} This is also a good practice to enhance clarity. ## Private Members and Getter/Setter Syntax Members are public by default. Use the `private` access modifier to hide them from outside of the class. + +{% tabs class-point-private-getter-setter class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-private-getter-setter %} ```scala mdoc:reset class Point { private var _x = 0 private var _y = 0 private val bound = 100 - def x = _x - def x_= (newValue: Int): Unit = { - if (newValue < bound) _x = newValue else printWarning + def x: Int = _x + def x_=(newValue: Int): Unit = { + if (newValue < bound) + _x = newValue + else + printWarning() } - def y = _y - def y_= (newValue: Int): Unit = { - if (newValue < bound) _y = newValue else printWarning + def y: Int = _y + def y_=(newValue: Int): Unit = { + if (newValue < bound) + _y = newValue + else + printWarning() } - private def printWarning = println("WARNING: Out of bounds") + private def printWarning(): Unit = + println("WARNING: Out of bounds") } val point1 = new Point point1.x = 99 point1.y = 101 // prints the warning ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-private-getter-setter %} +```scala +class Point: + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x: Int = _x + def x_=(newValue: Int): Unit = + if newValue < bound then + _x = newValue + else + printWarning() + + def y: Int = _y + def y_=(newValue: Int): Unit = + if newValue < bound then + _y = newValue + else + printWarning() + + private def printWarning(): Unit = + println("WARNING: Out of bounds") +end Point + +val point1 = Point() +point1.x = 99 +point1.y = 101 // prints the warning +``` +{% endtab %} + +{% endtabs %} + In this version of the `Point` class, the data is stored in private variables `_x` and `_y`. There are methods `def x` and `def y` for accessing the private data. `def x_=` and `def y_=` are for validating and setting the value of `_x` and `_y`. Notice the special syntax for the setters: the method has `_=` appended to the identifier of the getter and the parameters come after. Primary constructor parameters with `val` and `var` are public. However, because `val`s are immutable, you can't write the following. + +{% tabs class-point-cannot-set-val class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-cannot-set-val %} ```scala mdoc:fail class Point(val x: Int, val y: Int) val point = new Point(1, 2) point.x = 3 // <-- does not compile ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-cannot-set-val %} +```scala +class Point(val x: Int, val y: Int) +val point = Point(1, 2) +point.x = 3 // <-- does not compile +``` +{% endtab %} + +{% endtabs %} Parameters without `val` or `var` are private values, visible only within the class. + +{% tabs class-point-non-val-ctor-param class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-non-val-ctor-param %} ```scala mdoc:fail class Point(x: Int, y: Int) val point = new Point(1, 2) point.x // <-- does not compile ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-non-val-ctor-param %} +```scala +class Point(x: Int, y: Int) +val point = Point(1, 2) +point.x // <-- does not compile +``` +{% endtab %} + +{% endtabs %} ## More resources -* Learn more about Classes in the [Scala Book](/overviews/scala-book/classes.html) -* How to use [Auxiliary Class Constructors](/overviews/scala-book/classes-aux-constructors.html) +* Learn more about Classes in the [Scala Book](/scala3/book/domain-modeling-tools.html#classes) +* How to use [Auxiliary Class Constructors](/scala3/book/domain-modeling-tools.html#auxiliary-constructors) diff --git a/_tour/compound-types.md b/_tour/compound-types.md index 4cd53674b5..2c12773600 100644 --- a/_tour/compound-types.md +++ b/_tour/compound-types.md @@ -1,6 +1,6 @@ --- layout: tour -title: Compound Types +title: Intersection Types, aka Compound Types partof: scala-tour num: 26 @@ -10,13 +10,18 @@ previous-page: abstract-type-members redirect_from: "/tutorials/tour/compound-types.html" --- -Sometimes it is necessary to express that the type of an object is a subtype of several other types. In Scala this can be expressed with the help of *compound types*, which are intersections of object types. +Sometimes it is necessary to express that the type of an object is a subtype of several other types. + +In Scala this can be expressed with the help of *intersection types*, (or *compound types* in +Scala 2) which are types that behave like any part of the intersection. Suppose we have two traits `Cloneable` and `Resetable`: +{% tabs compound-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_1 %} ```scala mdoc trait Cloneable extends java.lang.Cloneable { - override def clone(): Cloneable = { + override def clone(): Cloneable = { // makes clone public super.clone().asInstanceOf[Cloneable] } } @@ -24,28 +29,67 @@ trait Resetable { def reset: Unit } ``` +{% endtab %} +{% tab 'Scala 3' for=compound-types_1 %} +```scala +trait Cloneable extends java.lang.Cloneable: + override def clone(): Cloneable = // makes clone public + super.clone().asInstanceOf[Cloneable] +trait Resetable: + def reset: Unit +``` +{% endtab %} +{% endtabs %} Now suppose we want to write a function `cloneAndReset` which takes an object, clones it and resets the original object: -``` +{% tabs compound-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_2 %} +```scala mdoc:fail def cloneAndReset(obj: ?): Cloneable = { val cloned = obj.clone() obj.reset cloned } ``` +{% endtab %} +{% tab 'Scala 3' for=compound-types_2 %} +```scala +def cloneAndReset(obj: ?): Cloneable = + val cloned = obj.clone() + obj.reset + cloned +``` +{% endtab %} +{% endtabs %} -The question arises what the type of the parameter `obj` is. If it's `Cloneable` then the object can be `clone`d, but not `reset`; if it's `Resetable` we can `reset` it, but there is no `clone` operation. To avoid type casts in such a situation, we can specify the type of `obj` to be both `Cloneable` and `Resetable`. This compound type is written like this in Scala: `Cloneable with Resetable`. +The question arises what the type of the parameter `obj` is. If it's `Cloneable` then the object can be `clone`d, but not `reset`; if it's `Resetable` we can `reset` it, but there is no `clone` operation. To avoid type casts in such a situation, we can specify the type of `obj` to be both `Cloneable` and `Resetable`. +{% tabs compound-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_3 %} +This compound type is written in Scala as `Cloneable with Resetable`. Here's the updated function: - -``` +```scala mdoc:fail def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { //... } ``` +Note that you can have more than two types: `A with B with C with ...`. +This means the same as thing as `(...(A with B) with C) with ... )` +{% endtab %} +{% tab 'Scala 3' for=compound-types_3 %} +This intersection type is written in Scala as `Cloneable & Resetable`. -Compound types can consist of several object types and they may have a single refinement which can be used to narrow the signature of existing object members. -The general form is: `A with B with C ... { refinement }` +Here's the updated function: +```scala +def cloneAndReset(obj: Cloneable & Resetable): Cloneable = { + //... +} +``` + +Note that you can have more than two types: `A & B & C & ...`. +And `&` is associative, so parentheses can be added around any part without changing the meaning. +{% endtab %} +{% endtabs %} -An example for the use of refinements is given on the page about [class composition with mixins](mixin-class-composition.html). + diff --git a/_tour/default-parameter-values.md b/_tour/default-parameter-values.md index 60776fd228..96b28f278a 100644 --- a/_tour/default-parameter-values.md +++ b/_tour/default-parameter-values.md @@ -13,29 +13,45 @@ redirect_from: "/tutorials/tour/default-parameter-values.html" Scala provides the ability to give parameters default values that can be used to allow a caller to omit those parameters. +{% tabs default-parameter-values-1 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-1 %} ```scala mdoc def log(message: String, level: String = "INFO") = println(s"$level: $message") log("System starting") // prints INFO: System starting log("User not found", "WARNING") // prints WARNING: User not found ``` +{% endtab %} +{% endtabs %} + The parameter `level` has a default value so it is optional. On the last line, the argument `"WARNING"` overrides the default argument `"INFO"`. Where you might do overloaded methods in Java, you can use methods with optional parameters to achieve the same effect. However, if the caller omits an argument, any following arguments must be named. +{% tabs default-parameter-values-2 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-2 %} ```scala mdoc class Point(val x: Double = 0, val y: Double = 0) val point1 = new Point(y = 1) ``` +{% endtab %} +{% endtabs %} + Here we have to say `y = 1`. Note that default parameters in Scala are not optional when called from Java code: +{% tabs default-parameter-values-3 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-3 %} ```scala mdoc:reset // Point.scala class Point(val x: Double = 0, val y: Double = 0) ``` +{% endtab %} +{% endtabs %} +{% tabs default-parameter-values-4 %} +{% tab 'Java' for=default-parameter-values-4 %} ```java // Main.java public class Main { @@ -44,3 +60,30 @@ public class Main { } } ``` +{% endtab %} +{% endtabs %} + +### Default Parameters for Overloaded Methods + +Scala doesn't allow having two methods with default parameters and with the same name (overloaded). +An important reason why is to avoid the ambiguity that can be caused due to the existence of default parameters. To illustrate the problem, let's consider the method declarations provided below: + +{% tabs default-parameter-values-5 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:fail +object A { + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object A: + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +``` +{% endtab %} +{% endtabs %} + +If we call `A.func()`, compiler cannot know whether the programmer intended to call `func(x: Int = 34)` or `func(y: String = "abc")`. diff --git a/_tour/extractor-objects.md b/_tour/extractor-objects.md index b7e08ed708..a859d6cdda 100644 --- a/_tour/extractor-objects.md +++ b/_tour/extractor-objects.md @@ -12,12 +12,15 @@ redirect_from: "/tutorials/tour/extractor-objects.html" An extractor object is an object with an `unapply` method. Whereas the `apply` method is like a constructor which takes arguments and creates an object, the `unapply` takes an object and tries to give back the arguments. This is most often used in pattern matching and partial functions. +{% tabs extractor-objects_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=extractor-objects_definition %} ```scala mdoc import scala.util.Random object CustomerID { - def apply(name: String) = s"$name--${Random.nextLong}" + def apply(name: String) = s"$name--${Random.nextLong()}" def unapply(customerID: String): Option[String] = { val stringArray: Array[String] = customerID.split("--") @@ -31,28 +34,68 @@ customer1ID match { case _ => println("Could not extract a CustomerID") } ``` +{% endtab %} + +{% tab 'Scala 3' for=extractor-objects_definition %} +```scala +import scala.util.Random + +object CustomerID: + + def apply(name: String) = s"$name--${Random.nextLong()}" + + def unapply(customerID: String): Option[String] = + val stringArray: Array[String] = customerID.split("--") + if stringArray.tail.nonEmpty then Some(stringArray.head) else None + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match + case CustomerID(name) => println(name) // prints Sukyoung + case _ => println("Could not extract a CustomerID") +``` +{% endtab %} + +{% endtabs %} The `apply` method creates a `CustomerID` string from a `name`. The `unapply` does the inverse to get the `name` back. When we call `CustomerID("Sukyoung")`, this is shorthand syntax for calling `CustomerID.apply("Sukyoung")`. When we call `case CustomerID(name) => println(name)`, we're calling the unapply method with `CustomerID.unapply(customer1ID)`. Since a value definition can use a pattern to introduce a new variable, an extractor can be used to initialize the variable, where the unapply method supplies the value. +{% tabs extractor-objects_use-case-1 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-1 %} ```scala mdoc val customer2ID = CustomerID("Nico") val CustomerID(name) = customer2ID println(name) // prints Nico ``` +{% endtab %} + +{% endtabs %} This is equivalent to `val name = CustomerID.unapply(customer2ID).get`. +{% tabs extractor-objects_use-case-2 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-2 %} ```scala mdoc val CustomerID(name2) = "--asdfasdfasdf" ``` +{% endtab %} + +{% endtabs %} If there is no match, a `scala.MatchError` is thrown: -```scala +{% tabs extractor-objects_use-case-3 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-3 %} +```scala mdoc:crash val CustomerID(name3) = "-asdfasdfasdf" ``` +{% endtab %} + +{% endtabs %} The return type of an `unapply` should be chosen as follows: diff --git a/_tour/for-comprehensions.md b/_tour/for-comprehensions.md index 54ed69f0bf..a97758d8b3 100644 --- a/_tour/for-comprehensions.md +++ b/_tour/for-comprehensions.md @@ -7,14 +7,18 @@ num: 19 next-page: generic-classes previous-page: extractor-objects -redirect_from: "/tutorials/tour/for-comprehensions.html" -redirect_from: "/tutorials/tour/sequence-comprehensions.html" +redirect_from: + - "/tutorials/tour/for-comprehensions.html" + - "/tutorials/tour/sequence-comprehensions.html" --- -Scala offers a lightweight notation for expressing *sequence comprehensions*. Comprehensions have the form `for (enumerators) yield e`, where `enumerators` refers to a semicolon-separated list of enumerators. An *enumerator* is either a generator which introduces new variables, or it is a filter. A comprehension evaluates the body `e` for each binding generated by the enumerators and returns a sequence of these values. +Scala offers a lightweight notation for expressing _sequence comprehensions_. Comprehensions have the form `for (enumerators) yield e`, where `enumerators` refers to a list of enumerators. An _enumerator_ is either a generator, or it is a guard (see: [Control Structures](/scala3/book/control-structures.html#for-loops)). A comprehension evaluates the body `e` for each binding generated by the enumerators and returns a sequence of these values. Here's an example: +{% tabs for-comprehensions-01 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-01 %} + ```scala mdoc case class User(name: String, age: Int) @@ -31,23 +35,66 @@ val twentySomethings = twentySomethings.foreach(println) // prints Travis Dennis ``` +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-01 %} + +```scala +case class User(name: String, age: Int) + +val userBase = List( + User("Travis", 28), + User("Kelly", 33), + User("Jennifer", 44), + User("Dennis", 23)) + +val twentySomethings = + for user <- userBase if user.age >=20 && user.age < 30 + yield user.name // i.e. add this to a list + +twentySomethings.foreach(println) // prints Travis Dennis +``` + +{% endtab %} +{% endtabs %} + A `for` loop with a `yield` statement returns a result, the container type of which is determined by the first generator. `user <- userBase` is a `List`, and because we said `yield user.name` where `user.name` is a `String`, the overall result is a `List[String]`. And `if user.age >=20 && user.age < 30` is a guard that filters out users who are not in their twenties. Here is a more complicated example using two generators. It computes all pairs of numbers between `0` and `n-1` whose sum is equal to a given value `v`: +{% tabs for-comprehensions-02 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-02 %} + ```scala mdoc def foo(n: Int, v: Int) = for (i <- 0 until n; j <- 0 until n if i + j == v) yield (i, j) -foo(10, 10) foreach { +foo(10, 10).foreach { case (i, j) => println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) } +``` +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-02 %} + +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + yield (i, j) + +foo(10, 10).foreach { + (i, j) => println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) +} ``` + +{% endtab %} +{% endtabs %} + Here `n == 10` and `v == 10`. On the first iteration, `i == 0` and `j == 0` so `i + j != v` and therefore nothing is yielded. `j` gets incremented 9 more times before `i` gets incremented to `1`. Without the `if` guard, this would simply print the following: + ```scala (0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... ``` @@ -56,6 +103,9 @@ Note that comprehensions are not restricted to lists. Every datatype that suppor You can omit `yield` in a comprehension. In that case, comprehension will return `Unit`. This can be useful in case you need to perform side-effects. Here's a program equivalent to the previous one, but without using `yield`: +{% tabs for-comprehensions-03 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-03 %} + ```scala mdoc:nest def foo(n: Int, v: Int) = for (i <- 0 until n; @@ -65,6 +115,22 @@ def foo(n: Int, v: Int) = foo(10, 10) ``` +{% endtab %} + +{% tab 'Scala 3' for=for-comprehensions-03 %} + +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + do println(s"($i, $j)") + +foo(10, 10) +``` + +{% endtab %} +{% endtabs %} + ## More resources -* Other examples of "For comprehension" in the [Scala Book](/overviews/scala-book/for-expressions.html) +- Other examples of "For comprehension" in the [Scala Book](/scala3/book/control-structures.html#for-expressions) diff --git a/_tour/generic-classes.md b/_tour/generic-classes.md index 0b479d30df..5dbb8990d8 100644 --- a/_tour/generic-classes.md +++ b/_tour/generic-classes.md @@ -10,10 +10,14 @@ assumed-knowledge: classes unified-types redirect_from: "/tutorials/tour/generic-classes.html" --- + Generic classes are classes which take a type as a parameter. They are particularly useful for collection classes. ## Defining a generic class Generic classes take a type as a parameter within square brackets `[]`. One convention is to use the letter `A` as type parameter identifier, though any parameter name may be used. + +{% tabs generic-classes-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-1 %} ```scala mdoc class Stack[A] { private var elements: List[A] = Nil @@ -27,6 +31,22 @@ class Stack[A] { } } ``` +{% endtab %} +{% tab 'Scala 3' for=generic-classes-1 %} +```scala +class Stack[A]: + private var elements: List[A] = Nil + def push(x: A): Unit = + elements = x :: elements + def peek: A = elements.head + def pop(): A = + val currentTop = peek + elements = elements.tail + currentTop +``` +{% endtab %} +{% endtabs %} + This implementation of a `Stack` class takes any type `A` as a parameter. This means the underlying list, `var elements: List[A] = Nil`, can only store elements of type `A`. The procedure `def push` only accepts objects of type `A` (note: `elements = x :: elements` reassigns `elements` to a new list created by prepending `x` to the current `elements`). `Nil` here is an empty `List` and is not to be confused with `null`. @@ -34,15 +54,33 @@ This implementation of a `Stack` class takes any type `A` as a parameter. This m ## Usage To use a generic class, put the type in the square brackets in place of `A`. -``` + +{% tabs generic-classes-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-2 %} +```scala mdoc val stack = new Stack[Int] stack.push(1) stack.push(2) -println(stack.pop) // prints 2 -println(stack.pop) // prints 1 +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 ``` -The instance `stack` can only take Ints. However, if the type argument had subtypes, those could be passed in: +{% endtab %} +{% tab 'Scala 3' for=generic-classes-2 %} +```scala +val stack = Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 ``` +{% endtab %} +{% endtabs %} + +The instance `stack` can only take Ints. However, if the type argument had subtypes, those could be passed in: + +{% tabs generic-classes-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-3 %} +```scala mdoc:nest class Fruit class Apple extends Fruit class Banana extends Fruit @@ -54,6 +92,23 @@ val banana = new Banana stack.push(apple) stack.push(banana) ``` +{% endtab %} +{% tab 'Scala 3' for=generic-classes-3 %} +```scala +class Fruit +class Apple extends Fruit +class Banana extends Fruit + +val stack = Stack[Fruit] +val apple = Apple() +val banana = Banana() + +stack.push(apple) +stack.push(banana) +``` +{% endtab %} +{% endtabs %} + Class `Apple` and `Banana` both extend `Fruit` so we can push instances `apple` and `banana` onto the stack of `Fruit`. _Note: subtyping of generic types is *invariant*. This means that if we have a stack of characters of type `Stack[Char]` then it cannot be used as an integer stack of type `Stack[Int]`. This would be unsound because it would enable us to enter true integers into the character stack. To conclude, `Stack[A]` is only a subtype of `Stack[B]` if and only if `B = A`. Since this can be quite restrictive, Scala offers a [type parameter annotation mechanism](variances.html) to control the subtyping behavior of generic types._ diff --git a/_tour/higher-order-functions.md b/_tour/higher-order-functions.md index c56846b81a..7dc08ea005 100644 --- a/_tour/higher-order-functions.md +++ b/_tour/higher-order-functions.md @@ -16,31 +16,54 @@ The terminology can get a bit confusing at this point, and we use the phrase "higher order function" for both methods and functions that take functions as parameters or that return a function. -In a pure Object Oriented world a good practice is to avoid exposing methods parameterized with functions that might leak object's internal state. Leaking internal state might break the invariants of the object itself thus violating encapsulation. +In a pure Object Oriented world, a good practice is to avoid exposing methods parameterised with functions that might leak an object's internal state. Leaking internal state might break the invariants of the object itself, thus violating encapsulation. One of the most common examples is the higher-order function `map` which is available for collections in Scala. -```scala mdoc -val salaries = Seq(20000, 70000, 40000) + +{% tabs map_example_1 %} + +{% tab 'Scala 2 and 3' for=map_example_1 %} +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) val doubleSalary = (x: Int) => x * 2 val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) ``` +{% endtab %} + +{% endtabs %} + `doubleSalary` is a function which takes a single Int, `x`, and returns `x * 2`. In general, the tuple on the left of the arrow `=>` is a parameter list and the value of the expression on the right is what gets returned. On line 3, the function `doubleSalary` gets applied to each element in the list of salaries. To shrink the code, we could make the function anonymous and pass it directly as an argument to map: -```scala:nest -val salaries = Seq(20000, 70000, 40000) + +{% tabs map_example_2 %} + +{% tab 'Scala 2 and 3' for=map_example_2 %} +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) ``` +{% endtab %} + +{% endtabs %} + Notice how `x` is not declared as an Int in the above example. That's because the -compiler can infer the type based on the type of function map expects (see [Currying](/tour/multiple-parameter-lists.html). An even more idiomatic way to write the same piece of code would be: +compiler can infer the type based on the type of function `map` expects (see [Currying](/tour/multiple-parameter-lists.html)). An even more idiomatic way to write the same piece of code would be: + +{% tabs map_example_3 %} +{% tab 'Scala 2 and 3' for=map_example_3 %} ```scala mdoc:nest -val salaries = Seq(20000, 70000, 40000) +val salaries = Seq(20_000, 70_000, 40_000) val newSalaries = salaries.map(_ * 2) ``` +{% endtab %} + +{% endtabs %} + Since the Scala compiler already knows the type of the parameters (a single Int), you just need to provide the right side of the function. The only caveat is that you need to use `_` in place of a parameter name (it was `x` in @@ -49,6 +72,10 @@ the previous example). ## Coercing methods into functions It is also possible to pass methods as arguments to higher-order functions because the Scala compiler will coerce the method into a function. + +{% tabs Coercing_methods_into_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Coercing_methods_into_functions %} ```scala mdoc case class WeeklyWeatherForecast(temperatures: Seq[Double]) { @@ -57,6 +84,20 @@ case class WeeklyWeatherForecast(temperatures: Seq[Double]) { def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF } ``` +{% endtab %} + +{% tab 'Scala 3' for=Coercing_methods_into_functions %} +```scala +case class WeeklyWeatherForecast(temperatures: Seq[Double]): + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF +``` +{% endtab %} + +{% endtabs %} + Here the method `convertCtoF` is passed to the higher order function `map`. This is possible because the compiler coerces `convertCtoF` to the function `x => convertCtoF(x)` (note: `x` will be a generated name which is guaranteed to be unique within its scope). @@ -64,6 +105,9 @@ Here the method `convertCtoF` is passed to the higher order function `map`. This One reason to use higher-order functions is to reduce redundant code. Let's say you wanted some methods that could raise someone's salaries by various factors. Without creating a higher-order function, it might look something like this: +{% tabs Functions_that_accept_functions_1 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_1 %} ```scala mdoc object SalaryRaiser { @@ -77,10 +121,31 @@ object SalaryRaiser { salaries.map(salary => salary * salary) } ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_1 %} +```scala +object SalaryRaiser: + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +``` +{% endtab %} + +{% endtabs %} Notice how each of the three methods vary only by the multiplication factor. To simplify, you can extract the repeated code into a higher-order function like so: +{% tabs Functions_that_accept_functions_2 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_2 %} ```scala mdoc:nest object SalaryRaiser { @@ -97,17 +162,41 @@ object SalaryRaiser { promotion(salaries, salary => salary * salary) } ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_2 %} +```scala +object SalaryRaiser: + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +``` +{% endtab %} + +{% endtabs %} The new method, `promotion`, takes the salaries plus a function of type `Double => Double` (i.e. a function that takes a Double and returns a Double) and returns the product. -Methods and functions usually express behaviours or data transformations, therefore having functions that compose based on other functions can help building generic mechanisms. Those generic operations defer to lock down the entire operation behaviour giving clients a way to control or further customize parts of the operation itself. +Methods and functions usually express behaviours or data transformations. Therefore, having functions that compose based on other functions can allow us to build more generic mechanisms. Such generic operations avoid completely locking down their behaviour in order to give clients a way to control or further customize parts of those operations. ## Functions that return functions There are certain cases where you want to generate a function. Here's an example of a method that returns a function. +{% tabs Functions_that_return_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_return_functions %} ```scala mdoc def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { val schema = if (ssl) "https://" else "http://" @@ -120,6 +209,23 @@ val endpoint = "users" val query = "id=1" val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_return_functions %} +```scala +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = + val schema = if ssl then "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` +{% endtab %} + +{% endtabs %} Notice the return type of urlBuilder `(String, String) => String`. This means that the returned anonymous function takes two Strings and returns a String. In this case, diff --git a/_tour/implicit-conversions.md b/_tour/implicit-conversions.md index 4915f51daf..7c0b5840e4 100644 --- a/_tour/implicit-conversions.md +++ b/_tour/implicit-conversions.md @@ -10,51 +10,34 @@ previous-page: implicit-parameters redirect_from: "/tutorials/tour/implicit-conversions.html" --- -An implicit conversion from type `S` to type `T` is defined by an implicit value which has function type `S => T`, or by an implicit method convertible to a value of that type. +Implicit conversions are a powerful Scala feature that enable two common use cases: +- allow users to supply an argument of one type, as if it were another type, to avoid boilerplate. +- in Scala 2, to provide additional members to closed classes (replaced by [extension methods][exts] in Scala 3). + +### Detailed Explanation +{% tabs implicit-conversion-defn class=tabs-scala-version %} +{% tab 'Scala 2' %} +In Scala 2, an implicit conversion from type `S` to type `T` is defined by either an [implicit class]({% link _overviews/core/implicit-classes.md %}) `T` that has a single parameter of type `S`, an [implicit value]({% link _tour/implicit-parameters.md %}) which has function type `S => T`, or by an implicit method convertible to a value of that type. +{% endtab %} +{% tab 'Scala 3' %} +In Scala 3, an implicit conversion from type `S` to type `T` is defined by a [given instance]({% link _tour/implicit-parameters.md %}) which has type `scala.Conversion[S, T]`. For compatibility with Scala 2, they can also be defined by an implicit method (read more in the Scala 2 tab). +{% endtab %} +{% endtabs %} Implicit conversions are applied in two situations: -* If an expression `e` is of type `S`, and `S` does not conform to the expression's expected type `T`. -* In a selection `e.m` with `e` of type `S`, if the selector `m` does not denote a member of `S`. +1. If an expression `e` is of type `S`, and `S` does not conform to the expression's expected type `T`. +2. In a selection `e.m` with `e` of type `S`, if the selector `m` does not denote a member of `S`. -In the first case, a conversion `c` is searched for which is applicable to `e` and whose result type conforms to `T`. -In the second case, a conversion `c` is searched for which is applicable to `e` and whose result contains a member named `m`. +In the first case, a conversion `c` is searched for, which is applicable to `e` and whose result type conforms to `T`. -If an implicit method `List[A] => Ordered[List[A]]` is in scope, as well as an implicit method `Int => Ordered[Int]`, the following operation on the two lists of type `List[Int]` is legal: +An example is to pass a `scala.Int`, e.g. `x`, to a method that expects `scala.Long`. In this case, the implicit conversion `Int.int2long(x)` is inserted. -``` -List(1, 2, 3) <= List(4, 5) -``` -An implicit method `Int => Ordered[Int]` is provided automatically through `scala.Predef.intWrapper`. An example of an implicit method `List[A] => Ordered[List[A]]` is provided below. +In the second case, a conversion `c` is searched for, which is applicable to `e` and whose result contains a member named `m`. -```scala mdoc -import scala.language.implicitConversions +An example is to compare two strings `"foo" < "bar"`. In this case, `String` has no member `<`, so the implicit conversion `Predef.augmentString("foo") < "bar"` is inserted. (`scala.Predef` is automatically imported into all Scala programs.) -implicit def list2ordered[A](x: List[A]) - (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] = - new Ordered[List[A]] { - //replace with a more useful implementation - def compare(that: List[A]): Int = 1 - } -``` +Further reading: [Implicit Conversions (in the Scala book)]({% link _overviews/scala3-book/ca-implicit-conversions.md %}). -The implicitly imported object `scala.Predef` declares several aliases to frequently used types (e.g. `scala.collection.immutable.Map` is aliased to `Map`) and methods (e.g. `assert`) but also several implicit conversions. - -For example, when calling a Java method that expects a `java.lang.Integer`, you are free to pass it a `scala.Int` instead. That's because Predef includes the following implicit conversions: - -```scala mdoc -import scala.language.implicitConversions - -implicit def int2Integer(x: Int) = - java.lang.Integer.valueOf(x) -``` - -Because implicit conversions can have pitfalls if used indiscriminately the compiler warns when compiling the implicit conversion definition. - -To turn off the warnings take either of these actions: - -* Import `scala.language.implicitConversions` into the scope of the implicit conversion definition -* Invoke the compiler with `-language:implicitConversions` - -No warning is emitted when the conversion is applied by the compiler. +[exts]: {% link _overviews/scala3-book/ca-extension-methods.md %} diff --git a/_tour/implicit-parameters.md b/_tour/implicit-parameters.md index e67d992d79..4d5977f242 100644 --- a/_tour/implicit-parameters.md +++ b/_tour/implicit-parameters.md @@ -1,6 +1,6 @@ --- layout: tour -title: Implicit Parameters +title: Contextual Parameters, aka Implicit Parameters partof: scala-tour num: 28 @@ -10,61 +10,93 @@ previous-page: self-types redirect_from: "/tutorials/tour/implicit-parameters.html" --- -A method can have an _implicit_ parameter list, marked by the _implicit_ keyword at the start of the parameter list. If the parameters in that parameter list are not passed as usual, Scala will look if it can get an implicit value of the correct type, and if it can, pass it automatically. +A method can have *contextual parameters*, also called *implicit parameters*, or more concisely *implicits*. +Parameter lists starting with the keyword `using` (or `implicit` in Scala 2) mark contextual parameters. +Unless the call site explicitly provides arguments for those parameters, Scala will look for implicitly available `given` (or `implicit` in Scala 2) values of the correct type. +If it can find appropriate values, it automatically passes them. -The places Scala will look for these parameters fall into two categories: +This is best shown using a small example first. +We define an interface `Comparator[A]` that can compare elements of type `A`, and provide two implementations, for `Int`s and `String`s. +We then define a method `max[A](x: A, y: A)` that returns the greater of the two arguments. +Since `x` and `y` are generically typed, in general we do not know how to compare them, but we can ask for an appropriate comparator. +As there is typically a canonical comparator for any given type `A`, we can declare them as *given*s, or *implicitly* available. -* Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called. -* Then it looks for members marked implicit in all the companion objects associated with the implicit candidate type. - -A more detailed guide to where Scala looks for implicits can be found in [the FAQ](//docs.scala-lang.org/tutorials/FAQ/finding-implicits.html). - -In the following example we define a method `sum` which computes the sum of a list of elements using the monoid's `add` and `unit` operations. Please note that implicit values cannot be top-level. +{% tabs implicits-comparator class=tabs-scala-version %} +{% tab 'Scala 2' for=implicits-comparator %} ```scala mdoc -abstract class Monoid[A] { - def add(x: A, y: A): A - def unit: A +trait Comparator[A] { + def compare(x: A, y: A): Int } -object ImplicitTest { - implicit val stringMonoid: Monoid[String] = new Monoid[String] { - def add(x: String, y: String): String = x concat y - def unit: String = "" +object Comparator { + implicit object IntComparator extends Comparator[Int] { + def compare(x: Int, y: Int): Int = Integer.compare(x, y) } - - implicit val intMonoid: Monoid[Int] = new Monoid[Int] { - def add(x: Int, y: Int): Int = x + y - def unit: Int = 0 - } - - def sum[A](xs: List[A])(implicit m: Monoid[A]): A = - if (xs.isEmpty) m.unit - else m.add(xs.head, sum(xs.tail)) - - def main(args: Array[String]): Unit = { - println(sum(List(1, 2, 3))) // uses intMonoid implicitly - println(sum(List("a", "b", "c"))) // uses stringMonoid implicitly + + implicit object StringComparator extends Comparator[String] { + def compare(x: String, y: String): Int = x.compareTo(y) } } -``` -`Monoid` defines an operation called `add` here, that combines a pair of `A`s and returns another `A`, together with an operation called `unit` that is able to create some (specific) `A`. +def max[A](x: A, y: A)(implicit comparator: Comparator[A]): A = + if (comparator.compare(x, y) >= 0) x + else y + +println(max(10, 6)) // 10 +println(max("hello", "world")) // world +``` -To show how implicit parameters work, we first define monoids `stringMonoid` and `intMonoid` for strings and integers, respectively. The `implicit` keyword indicates that the corresponding object can be used implicitly. +```scala mdoc:fail +// does not compile: +println(max(false, true)) +// ^ +// error: could not find implicit value for parameter comparator: Comparator[Boolean] +``` -The method `sum` takes a `List[A]` and returns an `A`, which takes the initial `A` from `unit`, and combines each next `A` in the list to that with the `add` method. Making the parameter `m` implicit here means we only have to provide the `xs` parameter when we call the method if Scala can find an implicit `Monoid[A]` to use for the implicit `m` parameter. +The `comparator` parameter is automatically filled in with `Comparator.IntComparator` for `max(10, 6)`, and with `Comparator.StringComparator` for `max("hello", "world")`. +Since no implicit `Comparator[Boolean]` can be found, the call `max(false, true)` fails to compile. +{% endtab %} -In our `main` method we call `sum` twice, and only provide the `xs` parameter. Scala will now look for an implicit in the scope mentioned above. The first call to `sum` passes a `List[Int]` for `xs`, which means that `A` is `Int`. The implicit parameter list with `m` is left out, so Scala will look for an implicit of type `Monoid[Int]`. The first lookup rule reads +{% tab 'Scala 3' for=implicits-comparator %} +```scala +trait Comparator[A]: + def compare(x: A, y: A): Int -> Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called. +object Comparator: + given Comparator[Int] with + def compare(x: Int, y: Int): Int = Integer.compare(x, y) -`intMonoid` is an implicit definition that can be accessed directly in `main`. It is also of the correct type, so it's passed to the `sum` method automatically. + given Comparator[String] with + def compare(x: String, y: String): Int = x.compareTo(y) +end Comparator -The second call to `sum` passes a `List[String]`, which means that `A` is `String`. Implicit lookup will go the same way as with `Int`, but will this time find `stringMonoid`, and pass that automatically as `m`. +def max[A](x: A, y: A)(using comparator: Comparator[A]): A = + if comparator.compare(x, y) >= 0 then x + else y -The program will output +println(max(10, 6)) // 10 +println(max("hello", "world")) // world ``` -6 -abc + +```scala +// does not compile: +println(max(false, true)) +-- Error: ---------------------------------------------------------------------- +1 |println(max(false, true)) + | ^ + |no given instance of type Comparator[Boolean] was found for parameter comparator of method max ``` + +The `comparator` parameter is automatically filled in with the `given Comparator[Int]` for `max(10, 6)`, and with the `given Comparator[String]` for `max("hello", "world")`. +Since no `given Comparator[Boolean]` can be found, the call `max(false, true)` fails to compile. +{% endtab %} + +{% endtabs %} + +Scala will look for available given values in two places: + +* Scala will first look for given definitions and using parameters that can be accessed directly (without a prefix) at the call site of `max`. +* Then it looks for members marked `given`/`implicit` in the companion objects associated with the implicit candidate type (for example: `object Comparator` for the candidate type `Comparator[Int]`). + +A more detailed guide to where Scala looks for implicits can be found in [the FAQ](/tutorials/FAQ/finding-implicits.html). diff --git a/_tour/inner-classes.md b/_tour/inner-classes.md index fc9e4f150a..e2d94542b4 100644 --- a/_tour/inner-classes.md +++ b/_tour/inner-classes.md @@ -14,6 +14,8 @@ In Scala it is possible to let classes have other classes as members. As opposed To illustrate the difference, we quickly sketch the implementation of a graph datatype: +{% tabs inner-classes_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_1 %} ```scala mdoc class Graph { class Node { @@ -32,8 +34,29 @@ class Graph { } } ``` +{% endtab %} +{% tab 'Scala 3' for=inner-classes_1 %} +```scala +class Graph: + class Node: + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` +{% endtab %} +{% endtabs %} + This program represents a graph as a list of nodes (`List[Node]`). Each node has a list of other nodes it's connected to (`connectedNodes`). The `class Node` is a _path-dependent type_ because it is nested in the `class Graph`. Therefore, all nodes in the `connectedNodes` must be created using the `newNode` from the same instance of `Graph`. +{% tabs inner-classes_2 %} +{% tab 'Scala 2 and 3' for=inner-classes_2 %} ```scala mdoc val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode @@ -42,11 +65,16 @@ val node3: graph1.Node = graph1.newNode node1.connectTo(node2) node3.connectTo(node1) ``` +{% endtab %} +{% endtabs %} + We have explicitly declared the type of `node1`, `node2`, and `node3` as `graph1.Node` for clarity but the compiler could have inferred it. This is because when we call `graph1.newNode` which calls `new Node`, the method is using the instance of `Node` specific to the instance `graph1`. If we now have two graphs, the type system of Scala does not allow us to mix nodes defined within one graph with the nodes of another graph, since the nodes of the other graph have a different type. Here is an illegal program: +{% tabs inner-classes_3 %} +{% tab 'Scala 2 and 3' for=inner-classes_3 %} ```scala mdoc:fail val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode @@ -56,8 +84,13 @@ val graph2: Graph = new Graph val node3: graph2.Node = graph2.newNode node1.connectTo(node3) // illegal! ``` +{% endtab %} +{% endtabs %} + The type `graph1.Node` is distinct from the type `graph2.Node`. In Java, the last line in the previous example program would have been correct. For nodes of both graphs, Java would assign the same type `Graph.Node`; i.e. `Node` is prefixed with class `Graph`. In Scala such a type can be expressed as well, it is written `Graph#Node`. If we want to be able to connect nodes of different graphs, we have to change the definition of our initial graph implementation in the following way: +{% tabs inner-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_4 %} ```scala mdoc:nest class Graph { class Node { @@ -76,3 +109,21 @@ class Graph { } } ``` +{% endtab %} +{% tab 'Scala 3' for=inner-classes_4 %} +```scala +class Graph: + class Node: + var connectedNodes: List[Graph#Node] = Nil + def connectTo(node: Graph#Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` +{% endtab %} +{% endtabs %} diff --git a/_tour/lower-type-bounds.md b/_tour/lower-type-bounds.md index a1cdb9648f..bac1883358 100644 --- a/_tour/lower-type-bounds.md +++ b/_tour/lower-type-bounds.md @@ -15,53 +15,93 @@ While [upper type bounds](upper-type-bounds.html) limit a type to a subtype of a Here is an example where this is useful: +{% tabs upper-type-bounds_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_1 %} ```scala mdoc:fail -trait Node[+B] { - def prepend(elem: B): Node[B] +trait List[+A] { + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) } -case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { - def prepend(elem: B): ListNode[B] = ListNode(elem, this) - def head: B = h - def tail: Node[B] = t -} +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] -case class Nil[+B]() extends Node[B] { - def prepend(elem: B): ListNode[B] = ListNode(elem, this) -} +object Nil extends List[Nothing] +``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_1 %} +```scala +trait List[+A]: + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] ``` +{% endtab %} +{% endtabs %} -This program implements a singly-linked list. `Nil` represents an empty element (i.e. an empty list). `class ListNode` is a node which contains an element of type `B` (`head`) and a reference to the rest of the list (`tail`). The `class Node` and its subtypes are covariant because we have `+B`. +This program implements a singly-linked list. `Nil` represents an empty list with no elements. `class NonEmptyList` is a node which contains an element of type `A` (`head`) and a reference to the rest of the list (`tail`). The `trait List` and its subtypes are covariant because we have `+A`. -However, this program does _not_ compile because the parameter `elem` in `prepend` is of type `B`, which we declared *co*variant. This doesn't work because functions are *contra*variant in their parameter types and *co*variant in their result types. +However, this program does _not_ compile because the parameter `elem` in `prepend` is of type `A`, which we declared *co*variant. This doesn't work because functions are *contra*variant in their parameter types and *co*variant in their result types. -To fix this, we need to flip the variance of the type of the parameter `elem` in `prepend`. We do this by introducing a new type parameter `U` that has `B` as a lower type bound. +To fix this, we need to flip the variance of the type of the parameter `elem` in `prepend`. We do this by introducing a new type parameter `B` that has `A` as a lower type bound. +{% tabs upper-type-bounds_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_2 %} ```scala mdoc -trait Node[+B] { - def prepend[U >: B](elem: U): Node[U] +trait List[+A] { + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) } -case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { - def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) - def head: B = h - def tail: Node[B] = t -} +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] -case class Nil[+B]() extends Node[B] { - def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) -} +object Nil extends List[Nothing] +``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_2 %} +```scala +trait List[+A]: + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] ``` +{% endtab %} +{% endtabs %} Now we can do the following: + +{% tabs upper-type-bounds_3 %} +{% tab 'Scala 2 and 3' for=upper-type-bounds_3 %} ```scala mdoc trait Bird case class AfricanSwallow() extends Bird case class EuropeanSwallow() extends Bird +val africanSwallows: List[AfricanSwallow] = Nil.prepend(AfricanSwallow()) +val swallowsFromAntarctica: List[Bird] = Nil +val someBird: Bird = EuropeanSwallow() + +// assign swallows to birds +val birds: List[Bird] = africanSwallows + +// add some bird to swallows, `B` is `Bird` +val someBirds = africanSwallows.prepend(someBird) + +// add a swallow to birds +val moreBirds = birds.prepend(EuropeanSwallow()) -val africanSwallowList = ListNode[AfricanSwallow](AfricanSwallow(), Nil()) -val birdList: Node[Bird] = africanSwallowList -birdList.prepend(EuropeanSwallow()) +// add disparate swallows together, `B` is `Bird` because that is the supertype common to both swallows +val allBirds = africanSwallows.prepend(EuropeanSwallow()) + +// but this is a mistake! adding a list of birds widens the type arg too much. -Xlint will warn! +val error = moreBirds.prepend(swallowsFromAntarctica) // List[Object] ``` -The `Node[Bird]` can be assigned the `africanSwallowList` but then accept `EuropeanSwallow`s. +{% endtab %} +{% endtabs %} + +The covariant type parameter allows `birds` to get the value of `africanSwallows`. + +The type bound on the type parameter for `prepend` allows adding different varieties of swallows and getting a wider type: instead of `List[AfricanSwallow]`, we get a `List[Bird]`. + +Use `-Xlint` to warn if the inferred type arg is widened too much. diff --git a/_tour/mixin-class-composition.md b/_tour/mixin-class-composition.md index fc362b2643..27eeafbf61 100644 --- a/_tour/mixin-class-composition.md +++ b/_tour/mixin-class-composition.md @@ -12,6 +12,9 @@ redirect_from: "/tutorials/tour/mixin-class-composition.html" --- Mixins are traits which are used to compose a class. +{% tabs mixin-first-exemple class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-first-exemple %} ```scala mdoc abstract class A { val message: String @@ -30,8 +33,33 @@ println(d.loudMessage) // I'M AN INSTANCE OF CLASS B ``` Class `D` has a superclass `B` and a mixin `C`. Classes can only have one superclass but many mixins (using the keywords `extends` and `with` respectively). The mixins and the superclass may have the same supertype. +{% endtab %} + +{% tab 'Scala 3' for=mixin-first-exemple %} +```scala +abstract class A: + val message: String +class B extends A: + val message = "I'm an instance of class B" +trait C extends A: + def loudMessage = message.toUpperCase() +class D extends B, C + +val d = D() +println(d.message) // I'm an instance of class B +println(d.loudMessage) // I'M AN INSTANCE OF CLASS B +``` +Class `D` has a superclass `B` and a mixin `C`. Classes can only have one superclass but many mixins (using the keyword `extends` and the separator `,` respectively). The mixins and the superclass may have the same supertype. + +{% endtab %} + +{% endtabs %} + Now let's look at a more interesting example starting with an abstract class: +{% tabs mixin-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-abstract-iterator %} ```scala mdoc abstract class AbsIterator { type T @@ -39,10 +67,26 @@ abstract class AbsIterator { def next(): T } ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-abstract-iterator %} +```scala +abstract class AbsIterator: + type T + def hasNext: Boolean + def next(): T +``` +{% endtab %} + +{% endtabs %} + The class has an abstract type `T` and the standard iterator methods. Next, we'll implement a concrete class (all abstract members `T`, `hasNext`, and `next` have implementations): +{% tabs mixin-concrete-string-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-concrete-string-iterator %} ```scala mdoc class StringIterator(s: String) extends AbsIterator { type T = Char @@ -55,10 +99,30 @@ class StringIterator(s: String) extends AbsIterator { } } ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-concrete-string-iterator %} +```scala +class StringIterator(s: String) extends AbsIterator: + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = + val ch = s charAt i + i += 1 + ch +``` +{% endtab %} + +{% endtabs %} + `StringIterator` takes a `String` and can be used to iterate over the String (e.g. to see if a String contains a certain character). Now let's create a trait which also extends `AbsIterator`. +{% tabs mixin-extended-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-extended-abstract-iterator %} ```scala mdoc trait RichIterator extends AbsIterator { def foreach(f: T => Unit): Unit = while (hasNext) f(next()) @@ -66,13 +130,41 @@ trait RichIterator extends AbsIterator { ``` This trait implements `foreach` by continually calling the provided function `f: T => Unit` on the next element (`next()`) as long as there are further elements (`while (hasNext)`). Because `RichIterator` is a trait, it doesn't need to implement the abstract members of AbsIterator. +{% endtab %} + +{% tab 'Scala 3' for=mixin-extended-abstract-iterator %} +```scala +trait RichIterator extends AbsIterator: + def foreach(f: T => Unit): Unit = while hasNext do f(next()) +``` +This trait implements `foreach` by continually calling the provided function `f: T => Unit` on the next element (`next()`) as long as there are further elements (`while hasNext`). Because `RichIterator` is a trait, it doesn't need to implement the abstract members of AbsIterator. + +{% endtab %} + +{% endtabs %} + We would like to combine the functionality of `StringIterator` and `RichIterator` into a single class. +{% tabs mixin-combination-class class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-combination-class %} ```scala mdoc class RichStringIter extends StringIterator("Scala") with RichIterator val richStringIter = new RichStringIter richStringIter.foreach(println) ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-combination-class %} +```scala +class RichStringIter extends StringIterator("Scala"), RichIterator +val richStringIter = RichStringIter() +richStringIter.foreach(println) +``` +{% endtab %} + +{% endtabs %} + The new class `RichStringIter` has `StringIterator` as a superclass and `RichIterator` as a mixin. With single inheritance we would not be able to achieve this level of flexibility. diff --git a/_tour/multiple-parameter-lists.md b/_tour/multiple-parameter-lists.md index 9aa3add880..324795b6c0 100644 --- a/_tour/multiple-parameter-lists.md +++ b/_tour/multiple-parameter-lists.md @@ -1,6 +1,6 @@ --- layout: tour -title: Multiple Parameter Lists (Currying) +title: Multiple Parameter Lists partof: scala-tour num: 12 @@ -16,6 +16,9 @@ Methods may have multiple parameter lists. Here is an example, as defined on the `Iterable` trait in Scala's collections API: +{% tabs foldLeft_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=foldLeft_definition %} ```scala trait Iterable[A] { ... @@ -23,18 +26,34 @@ trait Iterable[A] { ... } ``` +{% endtab %} + +{% tab 'Scala 3' for=foldLeft_definition %} +```scala +trait Iterable[A]: + ... + def foldLeft[B](z: B)(op: (B, A) => B): B + ... +``` +{% endtab %} + +{% endtabs %} `foldLeft` applies a two-parameter function `op` to an initial value `z` and all elements of this collection, going left to right. Shown below is an example of its usage. Starting with an initial value of 0, `foldLeft` here applies the function `(m, n) => m + n` to each element in the List and the previous accumulated value. -{% scalafiddle %} +{% tabs foldLeft_use %} + +{% tab 'Scala 2 and 3' for=foldLeft_use %} ```scala mdoc val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) val res = numbers.foldLeft(0)((m, n) => m + n) println(res) // 55 ``` -{% endscalafiddle %} +{% endtab %} + +{% endtabs %} ### Use cases @@ -45,29 +64,53 @@ Suggested use cases for multiple parameter lists include: It so happens that in Scala, type inference proceeds one parameter list at a time. Say you have the following method: +{% tabs foldLeft1_definition %} + +{% tab 'Scala 2 and 3' for=foldLeft1_definition %} ```scala mdoc def foldLeft1[A, B](as: List[A], b0: B, op: (B, A) => B) = ??? ``` +{% endtab %} + +{% endtabs %} Then you'd like to call it in the following way, but will find that it doesn't compile: +{% tabs foldLeft1_wrong_use %} + +{% tab 'Scala 2 and 3' for=foldLeft1_wrong_use %} ```scala mdoc:fail def notPossible = foldLeft1(numbers, 0, _ + _) ``` +{% endtab %} + +{% endtabs %} you will have to call it like one of the below ways: +{% tabs foldLeft1_good_use %} + +{% tab 'Scala 2 and 3' for=foldLeft1_good_use %} ```scala mdoc def firstWay = foldLeft1[Int, Int](numbers, 0, _ + _) def secondWay = foldLeft1(numbers, 0, (a: Int, b: Int) => a + b) ``` +{% endtab %} + +{% endtabs %} That's because Scala won't be able to infer the type of the function `_ + _`, as it's still inferring `A` and `B`. By moving the parameter `op` to its own parameter list, `A` and `B` are inferred in the first parameter list. These inferred types will then be available to the second parameter list and `_ + _` will match the inferred type `(Int, Int) => Int` +{% tabs foldLeft2_definition_and_use %} + +{% tab 'Scala 2 and 3' for=foldLeft2_definition_and_use %} ```scala mdoc def foldLeft2[A, B](as: List[A], b0: B)(op: (B, A) => B) = ??? def possible = foldLeft2(numbers, 0)(_ + _) ``` +{% endtab %} + +{% endtabs %} This definition doesn't need any type hints and can infer all of its type parameters. @@ -78,9 +121,21 @@ To specify only certain parameters as [`implicit`](https://docs.scala-lang.org/t An example of this is: +{% tabs execute_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=execute_definition %} ```scala mdoc def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ??? ``` +{% endtab %} + +{% tab 'Scala 3' for=execute_definition %} +```scala +def execute(arg: Int)(using ec: scala.concurrent.ExecutionContext) = ??? +``` +{% endtab %} + +{% endtabs %} #### Partial application @@ -88,6 +143,9 @@ When a method is called with a fewer number of parameter lists, then this will y For example, +{% tabs foldLeft_partial class=tabs-scala-version %} + +{% tab 'Scala 2' for=foldLeft_partial %} ```scala mdoc:nest val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) val numberFunc = numbers.foldLeft(List[Int]()) _ @@ -98,3 +156,63 @@ println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) val cubes = numberFunc((xs, x) => xs :+ x*x*x) println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) ``` +{% endtab %} + +{% tab 'Scala 3' for=foldLeft_partial %} +```scala +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]()) + +val squares = numberFunc((xs, x) => xs :+ x*x) +println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) + +val cubes = numberFunc((xs, x) => xs :+ x*x*x) +println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` +{% endtab %} + +{% endtabs %} + +### Comparison with "currying" + +You may sometimes see a method with multiple parameter lists referred to as "curried". + +As the [Wikipedia article on currying](https://en.wikipedia.org/wiki/Currying) states, + +> Currying is the technique of converting a function that takes +> multiple arguments into a sequence of functions that each takes a +> single argument + +We discourage the use of the word "curry" in reference to Scala's multiple parameter lists, for two reasons: + +1) In Scala, multiple parameters and multiple parameter lists are +specified and implemented directly, as part of the language, rather +being derived from single-parameter functions. + +2) There is danger of confusion with the Scala standard library's +[`curried`](https://www.scala-lang.org/api/current/scala/Function2.html#curried:T1=%3E(T2=%3ER)) +and [`uncurried`](https://www.scala-lang.org/api/current/scala/Function$.html#uncurried[T1,T2,R](f:T1=%3E(T2=%3ER)):(T1,T2)=%3ER) methods, which don't involve multiple parameter lists at all. + +Regardless, there are certainly similarities to be found between +multiple parameter lists and currying. Though they are different at +the definition site, the call site might nonetheless look identical, +as in this example: + +{% tabs about_currying %} + +{% tab 'Scala 2 and 3' for=about_currying %} +```scala mdoc +// version with multiple parameter lists +def addMultiple(n1: Int)(n2: Int) = n1 + n2 +// two different ways of arriving at a curried version instead +def add(n1: Int, n2: Int) = n1 + n2 +val addCurried1 = (add _).curried +val addCurried2 = (n1: Int) => (n2: Int) => n1 + n2 +// regardless, all three call sites are identical +addMultiple(3)(4) // 7 +addCurried1(3)(4) // 7 +addCurried2(3)(4) // 7 +``` +{% endtab %} + +{% endtabs %} diff --git a/_tour/named-arguments.md b/_tour/named-arguments.md index 3dc7a4a503..cec14a5ebf 100644 --- a/_tour/named-arguments.md +++ b/_tour/named-arguments.md @@ -8,25 +8,50 @@ next-page: traits previous-page: default-parameter-values prerequisite-knowledge: function-syntax -redirect_from: "/tutorials/tour/named-arguments.html" -redirect_from: "/tutorials/tour/named-parameters.html" +redirect_from: + - "/tutorials/tour/named-arguments.html" + - "/tutorials/tour/named-parameters.html" --- When calling methods, you can label the arguments with their parameter names like so: +{% tabs named-arguments-when-good %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-good %} ```scala mdoc -def printName(first: String, last: String): Unit = { - println(first + " " + last) -} +def printName(first: String, last: String): Unit = + println(s"$first $last") -printName("John", "Smith") // Prints "John Smith" -printName(first = "John", last = "Smith") // Prints "John Smith" -printName(last = "Smith", first = "John") // Prints "John Smith" +printName("John", "Public") // Prints "John Public" +printName(first = "John", last = "Public") // Prints "John Public" +printName(last = "Public", first = "John") // Prints "John Public" +printName("Elton", last = "John") // Prints "Elton John" ``` -Notice how the order of named arguments can be rearranged. However, if some arguments are named and others are not, the unnamed arguments must come first and in the order of their parameters in the method signature. +{% endtab %} + +{% endtabs %} + +This is useful when two parameters have the same type and the arguments could be accidentally swapped. + +Notice that named arguments can be written in any order. However, once the arguments are not in parameter order, reading from left to right, then the rest of the arguments must be named. +In the following example, named arguments enable the middle parameter to be omitted. But in the error case, the first argument is out of order, so the second argument must be named. + +{% tabs named-arguments-when-error %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-error %} ```scala mdoc:fail -printName(last = "Smith", "john") // error: positional after named argument +def printFullName(first: String, middle: String = "Q.", last: String): Unit = + println(s"$first $middle $last") + +printFullName(first = "John", last = "Public") // Prints "John Q. Public" +printFullName("John", last = "Public") // Prints "John Q. Public" +printFullName("John", middle = "Quincy", "Public") // Prints "John Quincy Public" +printFullName(last = "Public", first = "John") // Prints "John Q. Public" +printFullName(last = "Public", "John") // error: positional after named argument ``` +{% endtab %} + +{% endtabs %} -Named arguments work with calls to Java methods, but only if the Java library in question was compiled with `-parameters`. +Named arguments work with calls to Java methods, but only if the Java library in question was compiled with the `-parameters` flag. diff --git a/_tour/nested-functions.md b/_tour/nested-functions.md index a250fc2238..45d00e2db6 100644 --- a/_tour/nested-functions.md +++ b/_tour/nested-functions.md @@ -12,24 +12,48 @@ redirect_from: "/tutorials/tour/nested-functions.html" In Scala it is possible to nest method definitions. The following object provides a `factorial` method for computing the factorial of a given number: -{% scalafiddle %} +{% tabs Nested_functions_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=Nested_functions_definition %} ```scala mdoc - def factorial(x: Int): Int = { - def fact(x: Int, accumulator: Int): Int = { - if (x <= 1) accumulator - else fact(x - 1, x * accumulator) - } - fact(x, 1) - } - - println("Factorial of 2: " + factorial(2)) - println("Factorial of 3: " + factorial(3)) +def factorial(x: Int): Int = { + def fact(x: Int, accumulator: Int): Int = { + if (x <= 1) accumulator + else fact(x - 1, x * accumulator) + } + fact(x, 1) +} + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) ``` -{% endscalafiddle %} +{% endtab %} + +{% tab 'Scala 3' for=Nested_functions_definition %} +```scala +def factorial(x: Int): Int = + def fact(x: Int, accumulator: Int): Int = + if x <= 1 then accumulator + else fact(x - 1, x * accumulator) + fact(x, 1) + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) + +``` +{% endtab %} + +{% endtabs %} The output of this program is: +{% tabs Nested_functions_result %} + +{% tab 'Scala 2 and 3' for=Nested_functions_result %} ``` Factorial of 2: 2 Factorial of 3: 6 ``` +{% endtab %} + +{% endtabs %} diff --git a/_tour/operators.md b/_tour/operators.md index 38fd1a426c..fb157ce334 100644 --- a/_tour/operators.md +++ b/_tour/operators.md @@ -11,17 +11,30 @@ prerequisite-knowledge: case-classes redirect_from: "/tutorials/tour/operators.html" --- In Scala, operators are methods. Any method with a single parameter can be used as an _infix operator_. For example, `+` can be called with dot-notation: + +{% tabs operators_1 %} +{% tab 'Scala 2 and 3' for=operators_1 %} ``` 10.+(1) ``` +{% endtab %} +{% endtabs %} However, it's easier to read as an infix operator: + +{% tabs operators_2 %} +{% tab 'Scala 2 and 3' for=operators_2 %} ``` 10 + 1 ``` +{% endtab %} +{% endtabs %} ## Defining and using operators You can use any legal identifier as an operator. This includes a name like `add` or a symbol(s) like `+`. + +{% tabs operators_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_3 %} ```scala mdoc case class Vec(x: Double, y: Double) { def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) @@ -34,8 +47,26 @@ val vector3 = vector1 + vector2 vector3.x // 3.0 vector3.y // 3.0 ``` +{% endtab %} +{% tab 'Scala 3' for=operators_3 %} +```scala +case class Vec(x: Double, y: Double): + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) + +val vector1 = Vec(1.0, 1.0) +val vector2 = Vec(2.0, 2.0) + +val vector3 = vector1 + vector2 +vector3.x // 3.0 +vector3.y // 3.0 +``` +{% endtab %} +{% endtabs %} + The class Vec has a method `+` which we used to add `vector1` and `vector2`. Using parentheses, you can build up complex expressions with readable syntax. Here is the definition of class `MyBool` which includes methods `and` and `or`: +{% tabs operators_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_4 %} ```scala mdoc case class MyBool(x: Boolean) { def and(that: MyBool): MyBool = if (x) that else this @@ -43,13 +74,27 @@ case class MyBool(x: Boolean) { def negate: MyBool = MyBool(!x) } ``` +{% endtab %} +{% tab 'Scala 3' for=operators_4 %} +```scala +case class MyBool(x: Boolean): + def and(that: MyBool): MyBool = if x then that else this + def or(that: MyBool): MyBool = if x then this else that + def negate: MyBool = MyBool(!x) +``` +{% endtab %} +{% endtabs %} It is now possible to use `and` and `or` as infix operators: +{% tabs operators_5 %} +{% tab 'Scala 2 and 3' for=operators_5 %} ```scala mdoc def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) ``` +{% endtab %} +{% endtabs %} This helps to make the definition of `xor` more readable. @@ -60,19 +105,31 @@ When an expression uses multiple operators, the operators are evaluated based on * / % + - : -= ! < > += ! & ^ | -(all letters) +(all letters, $, _) ``` This applies to functions you define. For example, the following expression: + +{% tabs operators_7 %} +{% tab 'Scala 2 and 3' for=operators_7 %} ``` a + b ^? c ?^ d less a ==> b | c ``` +{% endtab %} +{% endtabs %} + Is equivalent to + +{% tabs operators_8 %} +{% tab 'Scala 2 and 3' for=operators_8 %} ``` ((a + b) ^? (c ?^ d)) less ((a ==> b) | c) ``` +{% endtab %} +{% endtabs %} + `?^` has the highest precedence because it starts with the character `?`. `+` has the second highest precedence, followed by `==>`, `^?`, `|`, and `less`. diff --git a/_tour/package-objects.md b/_tour/package-objects.md index 0b785361b8..8be239c933 100644 --- a/_tour/package-objects.md +++ b/_tour/package-objects.md @@ -1,29 +1,50 @@ --- layout: tour -title: Package Objects +title: Top Level Definitions in Packages partof: scala-tour num: 36 previous-page: packages-and-imports --- -# Package objects +Often, it is convenient to have definitions accessible across an entire package, and not need to invent a +name for a wrapper `object` to contain them. -Scala provides package objects as a convenient container shared across an entire package. +{% tabs pkg-obj-vs-top-lvl_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_1 %} +Scala 2 provides _package objects_ as a convenient container shared across an entire package. Package objects can contain arbitrary definitions, not just variable and method definitions. For instance, they are frequently used to hold package-wide type aliases and implicit conversions. Package objects can even inherit Scala classes and traits. +> In a future version of Scala 3, package objects will be removed in favor of top level definitions. + By convention, the source code for a package object is usually put in a source file named `package.scala`. Each package is allowed to have one package object. Any definitions placed in a package object are considered members of the package itself. +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_1 %} +In Scala 3, any kind of definition can be declared at the top level of a package. For example, classes, enums, +methods and variables. + +Any definitions placed at the top level of a package are considered members of the package itself. + +> In Scala 2, top-level method, type and variable definitions had to be wrapped in a **package object**. +> These are still usable in Scala 3 for backwards compatibility. You can see how they work by switching tabs. + +{% endtab %} +{% endtabs %} + See example below. Assume first a class `Fruit` and three `Fruit` objects in a package `gardening.fruits`: + +{% tabs pkg-obj-vs-top-lvl_2 %} +{% tab 'Scala 2 and 3' for=pkg-obj-vs-top-lvl_2 %} ``` // in file gardening/fruits/Fruit.scala package gardening.fruits @@ -33,10 +54,15 @@ object Apple extends Fruit("Apple", "green") object Plum extends Fruit("Plum", "blue") object Banana extends Fruit("Banana", "yellow") ``` +{% endtab %} +{% endtabs %} Now assume you want to place a variable `planted` and a method `showFruit` directly into package `gardening.fruits`. Here's how this is done: +{% tabs pkg-obj-vs-top-lvl_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_3 %} + ``` // in file gardening/fruits/package.scala package gardening @@ -47,13 +73,29 @@ package object fruits { } } ``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_3 %} + +``` +// in file gardening/fruits/package.scala +package gardening.fruits + +val planted = List(Apple, Plum, Banana) +def showFruit(fruit: Fruit): Unit = + println(s"${fruit.name}s are ${fruit.color}") +``` +{% endtab %} +{% endtabs %} -As an example of how the use site looks, the following object `PrintPlanted` imports `planted` and `showFruit` in exactly the same -way it imports class `Fruit`, using a wildcard import on package gardening.fruits: +As an example of how to use this, the following program imports `planted` and `showFruit` in exactly the same +way it imports class `Fruit`, using a wildcard import on package `gardening.fruits`: +{% tabs pkg-obj-vs-top-lvl_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_4 %} ``` // in file PrintPlanted.scala import gardening.fruits._ + object PrintPlanted { def main(args: Array[String]): Unit = { for (fruit <- planted) { @@ -62,11 +104,53 @@ object PrintPlanted { } } ``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_4 %} +``` +// in file printPlanted.scala +import gardening.fruits.* -Package objects are like other objects, which means you can use inheritance for building them. For example, one might mix in a couple of traits: +@main def printPlanted(): Unit = + for fruit <- planted do + showFruit(fruit) +``` +{% endtab %} +{% endtabs %} + +### Aggregating Several Definitions at the Package Level + +Often, your project may have several reusable definitions defined in various modules, that you +wish to aggregate at the top level of a package. + +For example, some helper methods in the trait `FruitHelpers` and +some term/type aliases in trait `FruitAliases`. Here is how you can put all their definitions at the level of the `fruit` +package: + +{% tabs pkg-obj-vs-top-lvl_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_5 %} + +Package objects are like other objects, which means you can use inheritance for building them. +So here we mix in the helper traits as parents of the package object. ``` -package object fruits extends FruitAliases with FruitHelpers { - // helpers and variables follows here -} +package gardening + +// `fruits` instead inherits its members from its parents. +package object fruits extends FruitAliases with FruitHelpers +``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_5 %} + +In Scala 3, it is preferred to use `export` to compose members from several objects into a single scope. +Here we define private objects that mix in the helper traits, then export their members at the top level: + +``` +package gardening.fruits + +private object FruitAliases extends FruitAliases +private object FruitHelpers extends FruitHelpers + +export FruitHelpers.*, FruitAliases.* ``` +{% endtab %} +{% endtabs %} diff --git a/_tour/packages-and-imports.md b/_tour/packages-and-imports.md index f18f8ae5e3..3f07344f32 100644 --- a/_tour/packages-and-imports.md +++ b/_tour/packages-and-imports.md @@ -14,11 +14,16 @@ Scala uses packages to create namespaces which allow you to modularize programs. ## Creating a package Packages are created by declaring one or more package names at the top of a Scala file. +{% tabs packages-and-imports_1 %} +{% tab 'Scala 2 and 3' for=packages-and-imports_1 %} ``` package users class User ``` +{% endtab %} +{% endtabs %} + One convention is to name the package the same as the directory containing the Scala file. However, Scala is agnostic to file layout. The directory structure of an sbt project for `package users` might look like this: ``` - ExampleProject @@ -33,8 +38,11 @@ One convention is to name the package the same as the directory containing the S UserPreferences.scala - test ``` -Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by using braces: -``` +Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by nesting them inside each other: + +{% tabs packages-and-imports_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_2 %} +```scala package users { package administrators { class NormalUser @@ -44,39 +52,95 @@ package users { } } ``` +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_2 %} +```scala +package users: + package administrators: + class NormalUser + + package normalusers: + class NormalUser +``` +{% endtab %} +{% endtabs %} + As you can see, this allows for package nesting and provides greater control for scope and encapsulation. The package name should be all lower case and if the code is being developed within an organization which has a website, it should be the following format convention: `..`. For example, if Google had a project called `SelfDrivingCar`, the package name would look like this:
-```
+
+{% tabs packages-and-imports_3 %}
+{% tab 'Scala 2 and 3' for=packages-and-imports_3 %}
+```scala
package com.google.selfdrivingcar.camera
class Lens
```
+{% endtab %}
+{% endtabs %}
+
This could correspond to the following directory structure: `SelfDrivingCar/src/main/scala/com/google/selfdrivingcar/camera/Lens.scala`.
## Imports
`import` clauses are for accessing members (classes, traits, functions, etc.) in other packages. An `import` clause is not required for accessing members of the same package. Import clauses are selective:
+
+{% tabs packages-and-imports_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=packages-and-imports_4 %}
```
import users._ // import everything from the users package
import users.User // import the class User
import users.{User, UserPreferences} // Only imports selected members
import users.{UserPreferences => UPrefs} // import and rename for convenience
```
+{% endtab %}
+{% tab 'Scala 3' for=packages-and-imports_4 %}
+```
+import users.* // import everything from the users package except given
+import users.given // import all given from the users package
+import users.User // import the class User
+import users.{User, UserPreferences} // Only imports selected members
+import users.UserPreferences as UPrefs // import and rename for convenience
+```
+{% endtab %}
+{% endtabs %}
One way in which Scala is different from Java is that imports can be used anywhere:
+{% tabs packages-and-imports_5 class=tabs-scala-version %}
+{% tab 'Scala 2' for=packages-and-imports_5 %}
```scala mdoc
def sqrtplus1(x: Int) = {
import scala.math.sqrt
sqrt(x) + 1.0
}
```
-In the event there is a naming conflict and you need to import something from the root of the project, prefix the package name with `_root_`:
+{% endtab %}
+{% tab 'Scala 3' for=packages-and-imports_5 %}
+```scala
+def sqrtplus1(x: Int) =
+ import scala.math.sqrt
+ sqrt(x) + 1.0
```
+{% endtab %}
+{% endtabs %}
+
+In the event there is a naming conflict and you need to import something from the root of the project, prefix the package name with `_root_`:
+
+{% tabs packages-and-imports_6 class=tabs-scala-version %}
+{% tab 'Scala 2' for=packages-and-imports_6 %}
+```scala
package accounts
import _root_.users._
```
+{% endtab %}
+{% tab 'Scala 3' for=packages-and-imports_6 %}
+```scala
+package accounts
+import _root_.users.*
+```
+{% endtab %}
+{% endtabs %}
Note: The `scala` and `java.lang` packages as well as `object Predef` are imported by default.
diff --git a/_tour/pattern-matching.md b/_tour/pattern-matching.md
index 0e225b2b65..f48682afea 100644
--- a/_tour/pattern-matching.md
+++ b/_tour/pattern-matching.md
@@ -15,6 +15,8 @@ Pattern matching is a mechanism for checking a value against a pattern. A succes
## Syntax
A match expression has a value, the `match` keyword, and at least one `case` clause.
+{% tabs pattern-matching-1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pattern-matching-1 %}
```scala mdoc
import scala.util.Random
@@ -27,38 +29,74 @@ x match {
case _ => "other"
}
```
-The `val x` above is a random integer between 0 and 10. `x` becomes the left operand of the `match` operator and on the right is an expression with four cases. The last case `_` is a "catch all" case for any other possible `Int` values. Cases are also called _alternatives_.
+{% endtab %}
+{% tab 'Scala 3' for=pattern-matching-1 %}
+```scala
+import scala.util.Random
+
+val x: Int = Random.nextInt(10)
+
+x match
+ case 0 => "zero"
+ case 1 => "one"
+ case 2 => "two"
+ case _ => "other"
+```
+{% endtab %}
+{% endtabs %}
+The `val x` above is a random integer between 0 and 9. `x` becomes the left operand of the `match` operator and on the right is an expression with four cases. The last case `_` is a "catch all" case for any other possible `Int` values. Cases are also called _alternatives_.
Match expressions have a value.
+{% tabs pattern-matching-2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pattern-matching-2 %}
```scala mdoc
def matchTest(x: Int): String = x match {
case 1 => "one"
case 2 => "two"
case _ => "other"
}
-matchTest(3) // prints other
-matchTest(1) // prints one
+matchTest(3) // returns other
+matchTest(1) // returns one
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=pattern-matching-2 %}
+```scala
+def matchTest(x: Int): String = x match
+ case 1 => "one"
+ case 2 => "two"
+ case _ => "other"
+
+matchTest(3) // returns other
+matchTest(1) // returns one
```
+{% endtab %}
+{% endtabs %}
This match expression has a type String because all of the cases return String. Therefore, the function `matchTest` returns a String.
## Matching on case classes
Case classes are especially useful for pattern matching.
+{% tabs notification %}
+{% tab 'Scala 2 and 3' for=notification %}
```scala mdoc
-abstract class Notification
+sealed trait Notification
case class Email(sender: String, title: String, body: String) extends Notification
case class SMS(caller: String, message: String) extends Notification
case class VoiceRecording(contactName: String, link: String) extends Notification
-
-
```
-`Notification` is an abstract super class which has three concrete Notification types implemented with case classes `Email`, `SMS`, and `VoiceRecording`. Now we can do pattern matching on these case classes:
+{% endtab %}
+{% endtabs %}
-```
+`Notification` is a sealed trait which has three concrete Notification types implemented with case classes `Email`, `SMS`, and `VoiceRecording`. (A [sealed trait](/tour/pattern-matching.html#sealed-types) can be extended only in the same file as its declaration.) Now we can do pattern matching on these case classes:
+
+{% tabs pattern-matching-4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pattern-matching-4 %}
+```scala
def showNotification(notification: Notification): String = {
notification match {
case Email(sender, title, _) =>
@@ -76,12 +114,99 @@ println(showNotification(someSms)) // prints You got an SMS from 12345! Message
println(showNotification(someVoiceRecording)) // prints You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123
```
+{% endtab %}
+{% tab 'Scala 3' for=pattern-matching-4 %}
+```scala
+def showNotification(notification: Notification): String =
+ notification match
+ case Email(sender, title, _) =>
+ s"You got an email from $sender with title: $title"
+ case SMS(number, message) =>
+ s"You got an SMS from $number! Message: $message"
+ case VoiceRecording(name, link) =>
+ s"You received a Voice Recording from $name! Click the link to hear it: $link"
+
+val someSms = SMS("12345", "Are you there?")
+val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123")
+
+println(showNotification(someSms)) // prints You got an SMS from 12345! Message: Are you there?
+
+println(showNotification(someVoiceRecording)) // prints You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123
+```
+{% endtab %}
+{% endtabs %}
+
The function `showNotification` takes as a parameter the abstract type `Notification` and matches on the type of `Notification` (i.e. it figures out whether it's an `Email`, `SMS`, or `VoiceRecording`). In the `case Email(sender, title, _)` the fields `sender` and `title` are used in the return value but the `body` field is ignored with `_`.
-## Pattern guards
-Pattern guards are simply boolean expressions which are used to make cases more specific. Just add `if ` after the pattern.
+## Matching on string
+
+The `s`-interpolator allows embedding variables in strings and is also useful for pattern matching.
+
+{% tabs s-interpolator-pattern-matching class=tabs-scala-version %}
+{% tab 'Scala 2' for=s-interpolator-pattern-matching %}
+```scala
+val input: String = "Alice is 25 years old"
+
+input match {
+ case s"$name is $age years old" => s"$name's age is $age"
+ case _ => "No match"
+}
+// Result: "Alice's age is 25"
```
+{% endtab %}
+{% tab 'Scala 3' for=s-interpolator-pattern-matching %}
+```scala
+val input: String = "Alice is 25 years old"
+
+input match
+ case s"$name is $age years old" => s"$name's age is $age"
+ case _ => "No match"
+// Result: "Alice's age is 25"
+```
+{% endtab %}
+{% endtabs %}
+
+In this example, name and age extract parts of the string based on the pattern. This is helpful for parsing structured text.
+We can also use extractor objects for string pattern matching.
+
+{% tabs s-interpolator-pattern-matching-2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=s-interpolator-pattern-matching-2 %}
+```scala
+object Age {
+ def unapply(s: String): Option[Int] = s.toIntOption
+}
+
+val input: String = "Alice is 25 years old"
+
+val (name, age) = input match {
+ case s"$name is ${Age(age)} years old" => (name, age)
+}
+// name: String = Alice
+// age: Int = 25
+```
+{% endtab %}
+{% tab 'Scala 3' for=s-interpolator-pattern-matching-2 %}
+```scala
+object Age:
+ def unapply(s: String): Option[Int] = s.toIntOption
+
+val input: String = "Alice is 25 years old"
+
+val (name, age) = input match
+ case s"$name is ${Age(age)} years old" => (name, age)
+// name: String = Alice
+// age: Int = 25
+```
+{% endtab %}
+{% endtabs %}
+
+## Pattern guards
+Pattern guards are boolean expressions which are used to make cases more specific. Just add `if ` after the pattern.
+
+{% tabs pattern-matching-5 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pattern-matching-5 %}
+```scala
def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String = {
notification match {
case Email(sender, _, _) if importantPeopleInfo.contains(sender) =>
@@ -106,13 +231,42 @@ println(showImportantNotification(importantEmail, importantPeopleInfo)) // print
println(showImportantNotification(importantSms, importantPeopleInfo)) // prints You got an SMS from special someone!
```
+{% endtab %}
+{% tab 'Scala 3' for=pattern-matching-5 %}
+```scala
+def showImportantNotification(notification: Notification, importantPeopleInfo: Seq[String]): String =
+ notification match
+ case Email(sender, _, _) if importantPeopleInfo.contains(sender) =>
+ "You got an email from special someone!"
+ case SMS(number, _) if importantPeopleInfo.contains(number) =>
+ "You got an SMS from special someone!"
+ case other =>
+ showNotification(other) // nothing special, delegate to our original showNotification function
+
+val importantPeopleInfo = Seq("867-5309", "jenny@gmail.com")
+
+val someSms = SMS("123-4567", "Are you there?")
+val someVoiceRecording = VoiceRecording("Tom", "voicerecording.org/id/123")
+val importantEmail = Email("jenny@gmail.com", "Drinks tonight?", "I'm free after 5!")
+val importantSms = SMS("867-5309", "I'm here! Where are you?")
+
+println(showImportantNotification(someSms, importantPeopleInfo)) // prints You got an SMS from 123-4567! Message: Are you there?
+println(showImportantNotification(someVoiceRecording, importantPeopleInfo)) // prints You received a Voice Recording from Tom! Click the link to hear it: voicerecording.org/id/123
+println(showImportantNotification(importantEmail, importantPeopleInfo)) // prints You got an email from special someone!
+
+println(showImportantNotification(importantSms, importantPeopleInfo)) // prints You got an SMS from special someone!
+```
+{% endtab %}
+{% endtabs %}
In the `case Email(sender, _, _) if importantPeopleInfo.contains(sender)`, the pattern is matched only if the `sender` is in the list of important people.
## Matching on type only
You can match on the type like so:
+{% tabs pattern-matching-6 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pattern-matching-6 %}
```scala mdoc
-abstract class Device
+sealed trait Device
case class Phone(model: String) extends Device {
def screenOff = "Turning screen off"
}
@@ -120,27 +274,108 @@ case class Computer(model: String) extends Device {
def screenSaverOn = "Turning screen saver on..."
}
-def goIdle(device: Device) = device match {
+def goIdle(device: Device): String = device match {
case p: Phone => p.screenOff
case c: Computer => c.screenSaverOn
}
```
+{% endtab %}
+{% tab 'Scala 3' for=pattern-matching-6 %}
+```scala
+sealed trait Device
+case class Phone(model: String) extends Device:
+ def screenOff = "Turning screen off"
+
+case class Computer(model: String) extends Device:
+ def screenSaverOn = "Turning screen saver on..."
+
+
+def goIdle(device: Device): String = device match
+ case p: Phone => p.screenOff
+ case c: Computer => c.screenSaverOn
+```
+{% endtab %}
+{% endtabs %}
+
`def goIdle` has a different behavior depending on the type of `Device`. This is useful when the case needs to call a method on the pattern. It is a convention to use the first letter of the type as the case identifier (`p` and `c` in this case).
-## Sealed classes
-Traits and classes can be marked `sealed` which means all subtypes must be declared in the same file. This assures that all subtypes are known.
+## Binding matched patterns to variables
+You can use variable binding to get type-dependent behavior while simultaneously extracting fields from the matched pattern.
+{% tabs pattern-matching-variable-binding class=tabs-scala-version %}
+{% tab 'Scala 2' for=pattern-matching-variable-binding %}
```scala mdoc
-sealed abstract class Furniture
-case class Couch() extends Furniture
-case class Chair() extends Furniture
+def goIdleWithModel(device: Device): String = device match {
+ case p @ Phone(model) => s"$model: ${p.screenOff}"
+ case c @ Computer(model) => s"$model: ${c.screenSaverOn}"
+}
+```
+{% endtab %}
+{% tab 'Scala 3' for=pattern-matching-variable-binding %}
+```scala
+def goIdleWithModel(device: Device): String = device match
+ case p @ Phone(model) => s"$model: ${p.screenOff}"
+ case c @ Computer(model) => s"$model: ${c.screenSaverOn}"
+```
+{% endtab %}
+{% endtabs %}
+
+## Sealed types
+
+You may have noticed that in the examples above the base types are qualified
+with the keyword `sealed`. This provides extra safety because the compiler
+checks that the `cases` of a `match` expression are exhaustive when the base
+type is `sealed`.
-def findPlaceToSit(piece: Furniture): String = piece match {
- case a: Couch => "Lie on the couch"
- case b: Chair => "Sit on the chair"
+For instance, in the method `showNotification` defined above, if we forget
+one case, say, `VoiceRecording`, the compiler emits a warning:
+
+{% tabs pattern-matching-7 class=tabs-scala-version %}
+{% tab 'Scala 2' for=pattern-matching-7 %}
+```scala
+def showNotification(notification: Notification): String = {
+ notification match {
+ case Email(sender, title, _) =>
+ s"You got an email from $sender with title: $title"
+ case SMS(number, message) =>
+ s"You got an SMS from $number! Message: $message"
+ }
}
```
-This is useful for pattern matching because we don't need a "catch all" case.
+{% endtab %}
+{% tab 'Scala 3' for=pattern-matching-7 %}
+```scala
+def showNotification(notification: Notification): String =
+ notification match
+ case Email(sender, title, _) =>
+ s"You got an email from $sender with title: $title"
+ case SMS(number, message) =>
+ s"You got an SMS from $number! Message: $message"
+```
+{% endtab %}
+{% endtabs %}
+
+This definition produces the following warning:
+
+~~~
+match may not be exhaustive.
+
+It would fail on pattern case: VoiceRecording(_, _)
+~~~
+
+The compiler even provides examples of input that would fail!
+
+On the flip side, exhaustivity checking requires you to define all the subtypes
+of the base type in the same file as the base type (otherwise, the compiler
+would not know what are all the possible cases). For instance, if you try
+to define a new type of `Notification` outside of the file that defines
+the `sealed trait Notification`, it will produce a compilation error:
+
+~~~
+case class Telepathy(message: String) extends Notification
+ ^
+ Cannot extend sealed trait Notification in a different source file
+~~~
## Notes
@@ -149,4 +384,4 @@ Scala also allows the definition of patterns independently of case classes, usin
## More resources
-* More details on match expressions in the [Scala Book](/overviews/scala-book/match-expressions.html)
+* More details on match expressions in the [Scala Book](/scala3/book/control-structures.html#match-expressions)
diff --git a/_tour/polymorphic-methods.md b/_tour/polymorphic-methods.md
index ce124cb12a..e8f99858e9 100644
--- a/_tour/polymorphic-methods.md
+++ b/_tour/polymorphic-methods.md
@@ -12,10 +12,12 @@ prerequisite-knowledge: unified-types
redirect_from: "/tutorials/tour/polymorphic-methods.html"
---
-Methods in Scala can be parameterized by type as well as value. The syntax is similar to that of generic classes. Type parameters are enclosed in square brackets, while value parameters are enclosed in parentheses.
+Methods in Scala can be parameterized by type as well as by value. The syntax is similar to that of generic classes. Type parameters are enclosed in square brackets, while value parameters are enclosed in parentheses.
Here is an example:
+{% tabs polymorphic-methods_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=polymorphic-methods_1 %}
```scala mdoc
def listOfDuplicates[A](x: A, length: Int): List[A] = {
if (length < 1)
@@ -26,9 +28,23 @@ def listOfDuplicates[A](x: A, length: Int): List[A] = {
println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3)
println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La)
```
+{% endtab %}
+{% tab 'Scala 3' for=polymorphic-methods_1 %}
+```scala
+def listOfDuplicates[A](x: A, length: Int): List[A] =
+ if length < 1 then
+ Nil
+ else
+ x :: listOfDuplicates(x, length - 1)
+
+println(listOfDuplicates[Int](3, 4)) // List(3, 3, 3, 3)
+println(listOfDuplicates("La", 8)) // List(La, La, La, La, La, La, La, La)
+```
+{% endtab %}
+{% endtabs %}
The method `listOfDuplicates` takes a type parameter `A` and value parameters `x` and `length`. Value `x` is of type `A`. If `length < 1` we return an empty list. Otherwise we prepend `x` to the list of duplicates returned by the recursive call. (Note that `::` means prepend an element on the left to a list on the right.)
-In first example call, we explicitly provide the type parameter by writing `[Int]`. Therefore the first argument must be an `Int` and the return type will be `List[Int]`.
+In the first example call, we explicitly provide the type parameter by writing `[Int]`. Therefore the first argument must be an `Int` and the return type will be a `List[Int]`.
-The second example call shows that you don't always need to explicitly provide the type parameter. The compiler can often infer it based on context or on the types of the value arguments. In this example, `"La"` is a `String` so the compiler knows `A` must be `String`.
+The second example call shows that you don't always need to explicitly provide the type parameter. The compiler can often infer it based on context or on the types of the value arguments. In this example, `"La"` is a `String` so the compiler knows that `A` must be a `String`.
diff --git a/_tour/regular-expression-patterns.md b/_tour/regular-expression-patterns.md
index aa51821463..40d12e5003 100644
--- a/_tour/regular-expression-patterns.md
+++ b/_tour/regular-expression-patterns.md
@@ -13,6 +13,9 @@ redirect_from: "/tutorials/tour/regular-expression-patterns.html"
Regular expressions are strings which can be used to find patterns (or lack thereof) in data. Any string can be converted to a regular expression using the `.r` method.
+{% tabs regex-patterns_numberPattern class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=regex-patterns_numberPattern %}
```scala mdoc
import scala.util.matching.Regex
@@ -23,12 +26,30 @@ numberPattern.findFirstMatchIn("awesomepassword") match {
case None => println("Password must contain a number")
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=regex-patterns_numberPattern %}
+```scala
+import scala.util.matching.Regex
+
+val numberPattern: Regex = "[0-9]".r
+
+numberPattern.findFirstMatchIn("awesomepassword") match
+ case Some(_) => println("Password OK")
+ case None => println("Password must contain a number")
+```
+{% endtab %}
+
+{% endtabs %}
In the above example, the `numberPattern` is a `Regex`
(regular expression) which we use to make sure a password contains a number.
You can also search for groups of regular expressions using parentheses.
+{% tabs regex-patterns_keyValPattern class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=regex-patterns_keyValPattern %}
```scala mdoc
import scala.util.matching.Regex
@@ -47,6 +68,31 @@ val input: String =
for (patternMatch <- keyValPattern.findAllMatchIn(input))
println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}")
```
+{% endtab %}
+
+{% tab 'Scala 3' for=regex-patterns_keyValPattern %}
+```scala
+import scala.util.matching.Regex
+
+val keyValPattern: Regex = "([0-9a-zA-Z- ]+): ([0-9a-zA-Z-#()/. ]+)".r
+
+val input: String =
+ """background-color: #A03300;
+ |background-image: url(img/header100.png);
+ |background-position: top center;
+ |background-repeat: repeat-x;
+ |background-size: 2160px 108px;
+ |margin: 0;
+ |height: 108px;
+ |width: 100%;""".stripMargin
+
+for patternMatch <- keyValPattern.findAllMatchIn(input) do
+ println(s"key: ${patternMatch.group(1)} value: ${patternMatch.group(2)}")
+```
+{% endtab %}
+
+{% endtabs %}
+
Here we parse out the keys and values of a String. Each match has a group of sub-matches. Here is the output:
```
key: background-color value: #A03300
@@ -58,3 +104,63 @@ key: margin value: 0
key: height value: 108px
key: width value: 100
```
+
+Moreover, regular expressions can be used as patterns (in `match` expressions) to conveniently extract the matched groups:
+
+{% tabs regex-patterns_saveContactInformation class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=regex-patterns_saveContactInformation %}
+```scala mdoc
+def saveContactInformation(contact: String): Unit = {
+ import scala.util.matching.Regex
+
+ val emailPattern: Regex = """^(\w+)@(\w+(.\w+)+)$""".r
+ val phonePattern: Regex = """^(\d{3}-\d{3}-\d{4})$""".r
+
+ contact match {
+ case emailPattern(localPart, domainName, _) =>
+ println(s"Hi $localPart, we have saved your email address.")
+ case phonePattern(phoneNumber) =>
+ println(s"Hi, we have saved your phone number $phoneNumber.")
+ case _ =>
+ println("Invalid contact information, neither an email address nor phone number.")
+ }
+}
+
+saveContactInformation("123-456-7890")
+saveContactInformation("JohnSmith@sample.domain.com")
+saveContactInformation("2 Franklin St, Mars, Milky Way")
+```
+{% endtab %}
+
+{% tab 'Scala 3' for=regex-patterns_saveContactInformation %}
+```scala
+def saveContactInformation(contact: String): Unit =
+ import scala.util.matching.Regex
+
+ val emailPattern: Regex = """^(\w+)@(\w+(.\w+)+)$""".r
+ val phonePattern: Regex = """^(\d{3}-\d{3}-\d{4})$""".r
+
+ contact match
+ case emailPattern(localPart, domainName, _) =>
+ println(s"Hi $localPart, we have saved your email address.")
+ case phonePattern(phoneNumber) =>
+ println(s"Hi, we have saved your phone number $phoneNumber.")
+ case _ =>
+ println("Invalid contact information, neither an email address nor phone number.")
+
+saveContactInformation("123-456-7890")
+saveContactInformation("JohnSmith@sample.domain.com")
+saveContactInformation("2 Franklin St, Mars, Milky Way")
+```
+{% endtab %}
+
+{% endtabs %}
+
+The output would be:
+
+```
+Hi, we have saved your phone number 123-456-7890.
+Hi JohnSmith, we have saved your email address.
+Invalid contact information, neither an email address nor phone number.
+```
diff --git a/_tour/self-types.md b/_tour/self-types.md
index 49110f23f9..f209fd5101 100644
--- a/_tour/self-types.md
+++ b/_tour/self-types.md
@@ -16,6 +16,9 @@ Self-types are a way to declare that a trait must be mixed into another trait, e
A self-type is a way to narrow the type of `this` or another identifier that aliases `this`. The syntax looks like normal function syntax but means something entirely different.
To use a self-type in a trait, write an identifier, the type of another trait to mix in, and a `=>` (e.g. `someIdentifier: SomeOtherTrait =>`).
+
+{% tabs self-types_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=self-types_1 %}
```scala mdoc
trait User {
def username: String
@@ -33,5 +36,25 @@ class VerifiedTweeter(val username_ : String) extends Tweeter with User { // We
val realBeyoncé = new VerifiedTweeter("Beyoncé")
realBeyoncé.tweet("Just spilled my glass of lemonade") // prints "real Beyoncé: Just spilled my glass of lemonade"
```
-
Because we said `this: User =>` in `trait Tweeter`, now the variable `username` is in scope for the `tweet` method. This also means that since `VerifiedTweeter` extends `Tweeter`, it must also mix-in `User` (using `with User`).
+
+{% endtab %}
+{% tab 'Scala 3' for=self-types_1 %}
+```scala
+trait User:
+ def username: String
+
+trait Tweeter:
+ this: User => // reassign this
+ def tweet(tweetText: String) = println(s"$username: $tweetText")
+
+class VerifiedTweeter(val username_ : String) extends Tweeter, User: // We mixin User because Tweeter required it
+ def username = s"real $username_"
+
+val realBeyoncé = VerifiedTweeter("Beyoncé")
+realBeyoncé.tweet("Just spilled my glass of lemonade") // prints "real Beyoncé: Just spilled my glass of lemonade"
+```
+Because we said `this: User =>` in `trait Tweeter`, now the variable `username` is in scope for the `tweet` method. This also means that since `VerifiedTweeter` extends `Tweeter`, it must also mix-in `User` (using `, User`).
+
+{% endtab %}
+{% endtabs %}
diff --git a/_tour/singleton-objects.md b/_tour/singleton-objects.md
index 037e855b0b..828d49a38a 100644
--- a/_tour/singleton-objects.md
+++ b/_tour/singleton-objects.md
@@ -16,23 +16,52 @@ As a top-level value, an object is a singleton.
As a member of an enclosing class or as a local value, it behaves exactly like a lazy val.
# Defining a singleton object
An object is a value. The definition of an object looks like a class, but uses the keyword `object`:
+
+
+{% tabs object-definition-box %}
+
+{% tab 'Scala 2 and 3' for=object-definition-box %}
```scala mdoc
object Box
```
+{% endtab %}
+
+{% endtabs %}
Here's an example of an object with a method:
-```
+{% tabs singleton-logger-example class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=singleton-logger-example %}
+
+```scala
package logging
object Logger {
def info(message: String): Unit = println(s"INFO: $message")
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=singleton-logger-example %}
+
+```scala
+package logging
+
+object Logger:
+ def info(message: String): Unit = println(s"INFO: $message")
+```
+{% endtab %}
+
+{% endtabs %}
+
The method `info` can be imported from anywhere in the program. Creating utility methods like this is a common use case for singleton objects.
Let's see how to use `info` in another package:
+{% tabs singleton-usage-example class=tabs-scala-version %}
-```
+{% tab 'Scala 2' for=singleton-usage-example %}
+
+```scala
import logging.Logger.info
class Project(name: String, daysToComplete: Int)
@@ -43,6 +72,24 @@ class Test {
info("Created projects") // Prints "INFO: Created projects"
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=singleton-usage-example %}
+
+```scala
+import logging.Logger.info
+
+class Project(name: String, daysToComplete: Int)
+
+class Test:
+ val project1 = Project("TPS Reports", 1)
+ val project2 = Project("Website redesign", 5)
+ info("Created projects") // Prints "INFO: Created projects"
+```
+{% endtab %}
+
+{% endtabs %}
+
The `info` method is visible because of the import statement, `import logging.Logger.info`.
@@ -53,8 +100,11 @@ Note: If an `object` is not top-level but is nested in another class or object,
## Companion objects
An object with the same name as a class is called a _companion object_. Conversely, the class is the object's companion class. A companion class or object can access the private members of its companion. Use a companion object for methods and values which are not specific to instances of the companion class.
-```
-import scala.math._
+{% tabs companion-object-circle class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=companion-object-circle %}
+```scala
+import scala.math.{Pi, pow}
case class Circle(radius: Double) {
import Circle._
@@ -69,10 +119,34 @@ val circle1 = Circle(5.0)
circle1.area
```
+{% endtab %}
+
+{% tab 'Scala 3' for=companion-object-circle %}
+```scala
+import scala.math.{Pi, pow}
+
+case class Circle(radius: Double):
+ import Circle.*
+ def area: Double = calculateArea(radius)
+
+object Circle:
+ private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0)
+
+
+val circle1 = Circle(5.0)
+
+circle1.area
+```
+{% endtab %}
+
+{% endtabs %}
The `class Circle` has a member `area` which is specific to each instance, and the singleton `object Circle` has a method `calculateArea` which is available to every instance.
The companion object can also contain factory methods:
+{% tabs companion-object-email class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=companion-object-email %}
```scala mdoc
class Email(val username: String, val domainName: String)
@@ -95,8 +169,41 @@ scalaCenterEmail match {
case None => println("Error: could not parse email")
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=companion-object-email %}
+```scala
+class Email(val username: String, val domainName: String)
+
+object Email:
+ def fromString(emailString: String): Option[Email] =
+ emailString.split('@') match
+ case Array(a, b) => Some(Email(a, b))
+ case _ => None
+
+val scalaCenterEmail = Email.fromString("scala.center@epfl.ch")
+scalaCenterEmail match
+ case Some(email) => println(
+ s"""Registered an email
+ |Username: ${email.username}
+ |Domain name: ${email.domainName}
+ """.stripMargin)
+ case None => println("Error: could not parse email")
+```
+{% endtab %}
+
+{% endtabs %}
+
The `object Email` contains a factory `fromString` which creates an `Email` instance from a String. We return it as an `Option[Email]` in case of parsing errors.
+A note about `Option`, `Some`, and `None` in the code above:
+* `Option` is a data type which allows for optionality. It has two cases: `Some` and `None`
+ * `Some` above represents a match: the emailString, when split by a @, returns an array with two components. This allows creation of a valid instance of class Email.
+ * `None` above represents no match: the emailString, when split by a @, did not return an array with two components. It could not allow creation of a valid instance of class Email.
+* The `Option` return type can then be used in a match/case:
+ * For a `Some` result, the match knows the returned value is an instance of `Email`, so it can access the inner `username` and `domainName`.
+ * For a `None` result, the match knows the returned value is not an instance of `Email`, so it prints an appropriate error message.
+
Note: If a class or object has a companion, both must be defined in the same file. To define companions in the REPL, either define them on the same line or enter `:paste` mode.
## Notes for Java programmers ##
@@ -107,4 +214,4 @@ When using a companion object from Java code, the members will be defined in a c
## More resources
-* Learn more about Companion objects in the [Scala Book](/overviews/scala-book/companion-objects.html)
+* Learn more about Companion objects in the [Scala Book](/scala3/book/domain-modeling-tools.html#companion-objects)
diff --git a/_tour/tour-of-scala.md b/_tour/tour-of-scala.md
index 2f23fdd254..16052b51f8 100644
--- a/_tour/tour-of-scala.md
+++ b/_tour/tour-of-scala.md
@@ -7,9 +7,10 @@ num: 1
next-page: basics
-redirect_from: "/tutorials/tour/tour-of-scala.html"
-redirect_from: "/tutorials/tour/anonymous-function-syntax.html"
-redirect_from: "/tutorials/tour/explicitly-typed-self-references.html"
+redirect_from:
+ - "/tutorials/tour/tour-of-scala.html"
+ - "/tutorials/tour/anonymous-function-syntax.html"
+ - "/tutorials/tour/explicitly-typed-self-references.html"
---
## Welcome to the tour
@@ -17,8 +18,8 @@ This tour contains bite-sized introductions to the most frequently used features
of Scala. It is intended for newcomers to the language.
This is just a brief tour, not a full language tutorial. If
-you want a more detailed guide, consider obtaining [a book](/books.html) or consulting
-[other resources](/learn.html).
+you want a more detailed guide, consider obtaining [a book](/books.html) or taking
+[an online courses](/online-courses.html).
## What is Scala?
Scala is a modern multi-paradigm programming language designed to express common programming patterns in a concise, elegant, and type-safe way. It seamlessly integrates features of object-oriented and functional languages.
@@ -27,9 +28,7 @@ Scala is a modern multi-paradigm programming language designed to express common
Scala is a pure object-oriented language in the sense that [every value is an object](unified-types.html). Types and behaviors of objects are described by [classes](classes.html) and [traits](traits.html). Classes can be extended by subclassing, and by using a flexible [mixin-based composition](mixin-class-composition.html) mechanism as a clean replacement for multiple inheritance.
## Scala is functional ##
-Scala is also a functional language in the sense that [every function is a value](unified-types.html). Scala provides a [lightweight syntax](basics.html#functions) for defining anonymous functions, it supports [higher-order functions](higher-order-functions.html), it allows functions to be [nested](nested-functions.html), and it supports [currying](multiple-parameter-lists.html). Scala's [case classes](case-classes.html) and its built-in support for [pattern matching](pattern-matching.html) provide the functionality of algebraic types, which are used in many functional languages. [Singleton objects](singleton-objects.html) provide a convenient way to group functions that aren't members of a class.
-
-Furthermore, Scala's notion of pattern matching naturally extends to the [processing of XML data](https://github.com/scala/scala-xml/wiki/XML-Processing) with the help of [right-ignoring sequence patterns](regular-expression-patterns.html), by way of general extension via [extractor objects](extractor-objects.html). In this context, [for comprehensions](for-comprehensions.html) are useful for formulating queries. These features make Scala ideal for developing applications like web services.
+Scala is also a functional language in the sense that [every function is a value](unified-types.html). Scala provides a [lightweight syntax](basics.html#functions) for defining anonymous functions, supports [higher-order functions](higher-order-functions.html), allows functions to be [nested](nested-functions.html), and supports [currying](multiple-parameter-lists.html). Scala's [case classes](case-classes.html) and its built-in support for [pattern matching](pattern-matching.html) provide the functionality of algebraic types, which are used in many functional languages. [Singleton objects](singleton-objects.html) provide a convenient way to group functions that aren't members of a class.
## Scala is statically typed ##
Scala's expressive type system enforces, at compile-time, that abstractions are used in a safe and coherent manner. In particular, the type system supports:
diff --git a/_tour/traits.md b/_tour/traits.md
index 6500490b7d..f719f96744 100644
--- a/_tour/traits.md
+++ b/_tour/traits.md
@@ -17,22 +17,45 @@ Traits are used to share interfaces and fields between classes. They are similar
## Defining a trait
A minimal trait is simply the keyword `trait` and an identifier:
+{% tabs trait-hair-color %}
+{% tab 'Scala 2 and 3' for=trait-hair-color %}
```scala mdoc
trait HairColor
```
+{% endtab %}
+{% endtabs %}
Traits become especially useful as generic types and with abstract methods.
+
+{% tabs trait-iterator-definition class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=trait-iterator-definition %}
```scala mdoc
trait Iterator[A] {
def hasNext: Boolean
def next(): A
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=trait-iterator-definition %}
+```scala
+trait Iterator[A]:
+ def hasNext: Boolean
+ def next(): A
+```
+{% endtab %}
+
+{% endtabs %}
Extending the `trait Iterator[A]` requires a type `A` and implementations of the methods `hasNext` and `next`.
## Using traits
Use the `extends` keyword to extend a trait. Then implement any abstract members of the trait using the `override` keyword:
+
+{% tabs trait-intiterator-definition class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=trait-intiterator-definition %}
```scala mdoc:nest
trait Iterator[A] {
def hasNext: Boolean
@@ -51,15 +74,46 @@ class IntIterator(to: Int) extends Iterator[Int] {
}
}
-
val iterator = new IntIterator(10)
iterator.next() // returns 0
iterator.next() // returns 1
```
+{% endtab %}
+
+{% tab 'Scala 3' for=trait-intiterator-definition %}
+```scala
+trait Iterator[A]:
+ def hasNext: Boolean
+ def next(): A
+
+class IntIterator(to: Int) extends Iterator[Int]:
+ private var current = 0
+ override def hasNext: Boolean = current < to
+ override def next(): Int =
+ if hasNext then
+ val t = current
+ current += 1
+ t
+ else
+ 0
+end IntIterator
+
+val iterator = IntIterator(10)
+iterator.next() // returns 0
+iterator.next() // returns 1
+```
+{% endtab %}
+
+{% endtabs %}
+
This `IntIterator` class takes a parameter `to` as an upper bound. It `extends Iterator[Int]` which means that the `next` method must return an Int.
## Subtyping
Where a given trait is required, a subtype of the trait can be used instead.
+
+{% tabs trait-pet-example class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=trait-pet-example %}
```scala mdoc
import scala.collection.mutable.ArrayBuffer
@@ -78,10 +132,34 @@ animals.append(dog)
animals.append(cat)
animals.foreach(pet => println(pet.name)) // Prints Harry Sally
```
+{% endtab %}
+
+{% tab 'Scala 3' for=trait-pet-example %}
+```scala
+import scala.collection.mutable.ArrayBuffer
+
+trait Pet:
+ val name: String
+
+class Cat(val name: String) extends Pet
+class Dog(val name: String) extends Pet
+
+val dog = Dog("Harry")
+val cat = Cat("Sally")
+
+val animals = ArrayBuffer.empty[Pet]
+animals.append(dog)
+animals.append(cat)
+animals.foreach(pet => println(pet.name)) // Prints Harry Sally
+```
+{% endtab %}
+
+{% endtabs %}
+
The `trait Pet` has an abstract field `name` that gets implemented by Cat and Dog in their constructors. On the last line, we call `pet.name`, which must be implemented in any subtype of the trait `Pet`.
## More resources
-* Learn more about traits in the [Scala Book](/overviews/scala-book/traits-intro.html)
-* Use traits to define [Enum](/overviews/scala-book/enumerations-pizza-class.html)
+* Learn more about traits in the [Scala Book](/scala3/book/domain-modeling-tools.html#traits)
+* Use traits to define [Enum](/scala3/book/domain-modeling-fp.html#modeling-the-data)
diff --git a/_tour/tuples.md b/_tour/tuples.md
index 3f684f63bb..19166098fb 100644
--- a/_tour/tuples.md
+++ b/_tour/tuples.md
@@ -18,62 +18,106 @@ Tuples are especially handy for returning multiple values from a method.
A tuple with two elements can be created as follows:
+{% tabs tuple-construction %}
+
+{% tab 'Scala 2 and 3' for=tuple-construction %}
```scala mdoc
-val ingredient = ("Sugar" , 25)
+val ingredient = ("Sugar", 25)
```
+{% endtab %}
-This creates a tuple containing a `String` element and an `Int` element.
+{% endtabs %}
-The inferred type of `ingredient` is `(String, Int)`, which is shorthand
-for `Tuple2[String, Int]`.
+This creates a tuple containing a `String` element and an `Int` element.
-To represent tuples, Scala uses a series of classes: `Tuple2`, `Tuple3`, etc., through `Tuple22`.
-Each class has as many type parameters as it has elements.
+The inferred type of `ingredient` is `(String, Int)`.
## Accessing the elements
-One way of accessing tuple elements is by position. The individual
-elements are named `_1`, `_2`, and so forth.
+{% tabs tuple-indexed-access class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=tuple-indexed-access %}
+One way of accessing tuple elements is their positions.
+The individual elements are named `_1`, `_2`, and so forth.
```scala mdoc
println(ingredient._1) // Sugar
println(ingredient._2) // 25
```
+{% endtab %}
+
+{% tab 'Scala 3' for=tuple-indexed-access %}
+One way of accessing tuple elements is their positions.
+The individual elements are accessed with `tuple(0)`, `tuple(1)`, and so forth.
+
+```scala
+println(ingredient(0)) // Sugar
+println(ingredient(1)) // 25
+```
+{% endtab %}
+
+{% endtabs %}
## Pattern matching on tuples
A tuple can also be taken apart using pattern matching:
+{% tabs tuple-extraction %}
+
+{% tab 'Scala 2 and 3' for=tuple-extraction %}
```scala mdoc
val (name, quantity) = ingredient
-println(name) // Sugar
+println(name) // Sugar
println(quantity) // 25
```
+{% endtab %}
+
+{% endtabs %}
Here `name`'s inferred type is `String` and `quantity`'s inferred type
is `Int`.
Here is another example of pattern-matching a tuple:
+{% tabs tuple-foreach-patmat %}
+
+{% tab 'Scala 2 and 3' for=tuple-foreach-patmat %}
```scala mdoc
val planets =
List(("Mercury", 57.9), ("Venus", 108.2), ("Earth", 149.6),
("Mars", 227.9), ("Jupiter", 778.3))
-planets.foreach{
+planets.foreach {
case ("Earth", distance) =>
println(s"Our planet is $distance million kilometers from the sun")
case _ =>
}
```
+{% endtab %}
+
+{% endtabs %}
-Or, in `for` comprehension:
+Or, in a `for` comprehension:
+{% tabs tuple-for-extraction class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=tuple-for-extraction %}
```scala mdoc
val numPairs = List((2, 5), (3, -7), (20, 56))
for ((a, b) <- numPairs) {
println(a * b)
}
```
+{% endtab %}
+
+{% tab 'Scala 3' for=tuple-for-extraction %}
+```scala
+val numPairs = List((2, 5), (3, -7), (20, 56))
+for (a, b) <- numPairs do
+ println(a * b)
+```
+{% endtab %}
+
+{% endtabs %}
## Tuples and case classes
@@ -82,4 +126,4 @@ Users may sometimes find it hard to choose between tuples and case classes. Case
## More resources
-* Learn more about tuples in the [Scala Book](/overviews/scala-book/tuples.html)
+* Learn more about tuples in the [Scala Book](/scala3/book/taste-collections.html#tuples)
diff --git a/_tour/type-inference.md b/_tour/type-inference.md
index 271906fe3c..3b5ea38cc0 100644
--- a/_tour/type-inference.md
+++ b/_tour/type-inference.md
@@ -12,26 +12,47 @@ The Scala compiler can often infer the type of an expression so you don't have t
## Omitting the type
+{% tabs type-inference_1 %}
+{% tab 'Scala 2 and 3' for=type-inference_1 %}
```scala mdoc
val businessName = "Montreux Jazz Café"
```
+{% endtab %}
+{% endtabs %}
+
The compiler can detect that `businessName` is a String. It works similarly with methods:
+{% tabs type-inference_2 %}
+{% tab 'Scala 2 and 3' for=type-inference_2 %}
```scala mdoc
def squareOf(x: Int) = x * x
```
+{% endtab %}
+{% endtabs %}
+
The compiler can infer that the return type is an `Int`, so no explicit return type is required.
For recursive methods, the compiler is not able to infer a result type. Here is a program which will fail the compiler for this reason:
+{% tabs type-inference_3 class=tabs-scala-version %}
+{% tab 'Scala 2' for=type-inference_3 %}
```scala mdoc:fail
def fac(n: Int) = if (n == 0) 1 else n * fac(n - 1)
```
+{% endtab %}
+{% tab 'Scala 3' for=type-inference_3 %}
+```scala
+def fac(n: Int) = if n == 0 then 1 else n * fac(n - 1)
+```
+{% endtab %}
+{% endtabs %}
It is also not compulsory to specify type parameters when [polymorphic methods](polymorphic-methods.html) are called or [generic classes](generic-classes.html) are instantiated. The Scala compiler will infer such missing type parameters from the context and from the types of the actual method/constructor parameters.
Here are two examples:
+{% tabs type-inference_4 %}
+{% tab 'Scala 2 and 3' for=type-inference_4 %}
```scala mdoc
case class MyPair[A, B](x: A, y: B)
val p = MyPair(1, "scala") // type: MyPair[Int, String]
@@ -39,6 +60,8 @@ val p = MyPair(1, "scala") // type: MyPair[Int, String]
def id[T](x: T) = x
val q = id(1) // type: Int
```
+{% endtab %}
+{% endtabs %}
The compiler uses the types of the arguments of `MyPair` to figure out what type `A` and `B` are. Likewise for the type of `x`.
@@ -46,9 +69,13 @@ The compiler uses the types of the arguments of `MyPair` to figure out what type
The compiler never infers method parameter types. However, in certain cases, it can infer anonymous function parameter types when the function is passed as argument.
+{% tabs type-inference_5 %}
+{% tab 'Scala 2 and 3' for=type-inference_5 %}
```scala mdoc
Seq(1, 3, 4).map(x => x * 2) // List(2, 6, 8)
```
+{% endtab %}
+{% endtabs %}
The parameter for map is `f: A => B`. Because we put integers in the `Seq`, the compiler knows that `A` is `Int` (i.e. that `x` is an integer). Therefore, the compiler can infer from `x * 2` that `B` is type `Int`.
@@ -58,14 +85,22 @@ It is generally considered more readable to declare the type of members exposed
Also, type inference can sometimes infer a too-specific type. Suppose we write:
+{% tabs type-inference_6 %}
+{% tab 'Scala 2 and 3' for=type-inference_6 %}
```scala
var obj = null
```
+{% endtab %}
+{% endtabs %}
We can't then go on and make this reassignment:
+{% tabs type-inference_7 %}
+{% tab 'Scala 2 and 3' for=type-inference_7 %}
```scala mdoc:fail
obj = new AnyRef
```
+{% endtab %}
+{% endtabs %}
It won't compile, because the type inferred for `obj` was `Null`. Since the only value of that type is `null`, it is impossible to assign a different value.
diff --git a/_tour/unified-types.md b/_tour/unified-types.md
index 2bae3732db..a6f0e9c0dd 100644
--- a/_tour/unified-types.md
+++ b/_tour/unified-types.md
@@ -25,6 +25,8 @@ In Scala, all values have a type, including numerical values and functions. The
Here is an example that demonstrates that strings, integers, characters, boolean values, and functions are all of type `Any` just like every other object:
+{% tabs unified-types-1 %}
+{% tab 'Scala 2 and 3' for=unified-types-1 %}
```scala mdoc
val list: List[Any] = List(
"a string",
@@ -36,6 +38,8 @@ val list: List[Any] = List(
list.foreach(element => println(element))
```
+{% endtab %}
+{% endtabs %}
It defines a value `list` of type `List[Any]`. The list is initialized with elements of various types, but each is an instance of `scala.Any`, so you can add them to the list.
@@ -53,23 +57,35 @@ true
Value types can be cast in the following way:
+Note that `Long` to `Float` conversion is deprecated in new versions of Scala, because of the potential precision lost.
+
For example:
+{% tabs unified-types-2 %}
+{% tab 'Scala 2 and 3' for=unified-types-2 %}
```scala mdoc
val x: Long = 987654321
-val y: Float = x // 9.8765434E8 (note that some precision is lost in this case)
+val y: Float = x.toFloat // 9.8765434E8 (note that some precision is lost in this case)
val face: Char = '☺'
val number: Int = face // 9786
```
+{% endtab %}
+{% endtabs %}
+
Casting is unidirectional. This will not compile:
-```
+{% tabs unified-types-3 %}
+{% tab 'Scala 2 and 3' for=unified-types-3 %}
+```scala
val x: Long = 987654321
-val y: Float = x // 9.8765434E8
+val y: Float = x.toFloat // 9.8765434E8
val z: Long = y // Does not conform
```
+{% endtab %}
+{% endtabs %}
+
You can also cast a reference type to a subtype. This will be covered later in the tour.
diff --git a/_tour/upper-type-bounds.md b/_tour/upper-type-bounds.md
index 8c4b5815c7..e49f86dc3f 100644
--- a/_tour/upper-type-bounds.md
+++ b/_tour/upper-type-bounds.md
@@ -13,6 +13,8 @@ redirect_from: "/tutorials/tour/upper-type-bounds.html"
In Scala, [type parameters](generic-classes.html) and [abstract type members](abstract-type-members.html) may be constrained by a type bound. Such type bounds limit the concrete values of the type variables and possibly reveal more information about the members of such types. An _upper type bound_ `T <: A` declares that type variable `T` refers to a subtype of type `A`.
Here is an example that demonstrates upper type bound for a type parameter of class `PetContainer`:
+{% tabs upper-type-bounds class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds %}
```scala mdoc
abstract class Animal {
def name: String
@@ -39,11 +41,47 @@ class PetContainer[P <: Pet](p: P) {
val dogContainer = new PetContainer[Dog](new Dog)
val catContainer = new PetContainer[Cat](new Cat)
```
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds %}
+```scala
+abstract class Animal:
+ def name: String
+abstract class Pet extends Animal
+
+class Cat extends Pet:
+ override def name: String = "Cat"
+
+class Dog extends Pet:
+ override def name: String = "Dog"
+
+class Lion extends Animal:
+ override def name: String = "Lion"
+
+class PetContainer[P <: Pet](p: P):
+ def pet: P = p
+
+val dogContainer = PetContainer[Dog](Dog())
+val catContainer = PetContainer[Cat](Cat())
+```
+{% endtab %}
+{% endtabs %}
+
+{% tabs upper-type-bounds_error class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds_error %}
```scala mdoc:fail
// this would not compile
val lionContainer = new PetContainer[Lion](new Lion)
```
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds_error %}
+```scala
+// this would not compile
+val lionContainer = PetContainer[Lion](Lion())
+```
+{% endtab %}
+{% endtabs %}
+
The `class PetContainer` takes a type parameter `P` which must be a subtype of `Pet`. `Dog` and `Cat` are subtypes of `Pet` so we can create a new `PetContainer[Dog]` and `PetContainer[Cat]`. However, if we tried to create a `PetContainer[Lion]`, we would get the following Error:
`type arguments [Lion] do not conform to class PetContainer's type parameter bounds [P <: Pet]`
diff --git a/_tour/variances.md b/_tour/variances.md
index 69f371e81e..14f40fb893 100644
--- a/_tour/variances.md
+++ b/_tour/variances.md
@@ -10,20 +10,34 @@ previous-page: generic-classes
redirect_from: "/tutorials/tour/variances.html"
---
-Variance is the correlation of subtyping relationships of complex types and the subtyping relationships of their component types. Scala supports variance annotations of type parameters of [generic classes](generic-classes.html), to allow them to be covariant, contravariant, or invariant if no annotations are used. The use of variance in the type system allows us to make intuitive connections between complex types, whereas the lack of variance can restrict the reuse of a class abstraction.
+Variance lets you control how type parameters behave with regard to subtyping. Scala supports variance annotations of type parameters of [generic classes](generic-classes.html), to allow them to be covariant, contravariant, or invariant if no annotations are used. The use of variance in the type system allows us to make intuitive connections between complex types.
+{% tabs variances_1 %}
+{% tab 'Scala 2 and 3' for=variances_1 %}
```scala mdoc
class Foo[+A] // A covariant class
class Bar[-A] // A contravariant class
class Baz[A] // An invariant class
```
+{% endtab %}
+{% endtabs %}
-### Covariance
+### Invariance
-A type parameter `T` of a generic class can be made covariant by using the annotation `+T`. For some `class List[+T]`, making `T` covariant implies that for two types `A` and `B` where `B` is a subtype of `A`, then `List[B]` is a subtype of `List[A]`. This allows us to make very useful and intuitive subtyping relationships using generics.
+By default, type parameters in Scala are invariant: subtyping relationships between the type parameters aren't reflected in the parameterized type. To explore why this works the way it does, we look at a simple parameterized type, the mutable box.
+
+{% tabs invariance_1 %}
+{% tab 'Scala 2 and 3' for=invariance_1 %}
+```scala mdoc
+class Box[A](var content: A)
+```
+{% endtab %}
+{% endtabs %}
-Consider this simple class structure:
+We're going to be putting values of type `Animal` in it. This type is defined as follows:
+{% tabs invariance_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=invariance_2 %}
```scala mdoc
abstract class Animal {
def name: String
@@ -31,111 +45,178 @@ abstract class Animal {
case class Cat(name: String) extends Animal
case class Dog(name: String) extends Animal
```
+{% endtab %}
+{% tab 'Scala 3' for=invariance_2 %}
+```scala
+abstract class Animal:
+ def name: String
-Both `Cat` and `Dog` are subtypes of `Animal`. The Scala standard library has a generic immutable `sealed abstract class List[+A]` class, where the type parameter `A` is covariant. This means that a `List[Cat]` is a `List[Animal]` and a `List[Dog]` is also a `List[Animal]`. Intuitively, it makes sense that a list of cats and a list of dogs are each lists of animals, and you should be able to use either of them for in place of `List[Animal]`.
+case class Cat(name: String) extends Animal
+case class Dog(name: String) extends Animal
+```
+{% endtab %}
+{% endtabs %}
-In the following example, the method `printAnimalNames` will accept a list of animals as an argument and print their names each on a new line. If `List[A]` were not covariant, the last two method calls would not compile, which would severely limit the usefulness of the `printAnimalNames` method.
+We can say that `Cat` is a subtype of `Animal`, and that `Dog` is also a subtype of `Animal`. That means that the following is well-typed:
+{% tabs invariance_3 %}
+{% tab 'Scala 2 and 3' for=invariance_3 %}
```scala mdoc
-def printAnimalNames(animals: List[Animal]): Unit =
- animals.foreach {
- animal => println(animal.name)
- }
-
-val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom"))
-val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex"))
+val myAnimal: Animal = Cat("Felix")
+```
+{% endtab %}
+{% endtabs %}
-// prints: Whiskers, Tom
-printAnimalNames(cats)
+What about boxes? Is `Box[Cat]` a subtype of `Box[Animal]`, like `Cat` is a subtype of `Animal`? At first sight, it looks like that may be plausible, but if we try to do that, the compiler will tell us we have an error:
-// prints: Fido, Rex
-printAnimalNames(dogs)
+{% tabs invariance_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=invariance_4 %}
+```scala mdoc:fail
+val myCatBox: Box[Cat] = new Box[Cat](Cat("Felix"))
+val myAnimalBox: Box[Animal] = myCatBox // this doesn't compile
+val myAnimal: Animal = myAnimalBox.content
```
+{% endtab %}
+{% tab 'Scala 3' for=invariance_4 %}
+```scala
+val myCatBox: Box[Cat] = Box[Cat](Cat("Felix"))
+val myAnimalBox: Box[Animal] = myCatBox // this doesn't compile
+val myAnimal: Animal = myAnimalBox.content
+```
+{% endtab %}
+{% endtabs %}
-### Contravariance
+Why could this be a problem? We can get the cat from the box, and it's still an Animal, isn't it? Well, yes. But that's not all we can do. We can also replace the cat in the box with a different animal
-A type parameter `A` of a generic class can be made contravariant by using the annotation `-A`. This creates a subtyping relationship between the class and its type parameter that is similar, but opposite to what we get with covariance. That is, for some `class Writer[-A]`, making `A` contravariant implies that for two types `A` and `B` where `A` is a subtype of `B`, `Writer[B]` is a subtype of `Writer[A]`.
+{% tabs invariance_5 %}
+{% tab 'Scala 2 and 3' for=invariance_5 %}
+```scala
+ myAnimalBox.content = Dog("Fido")
+```
+{% endtab %}
+{% endtabs %}
-Consider the `Cat`, `Dog`, and `Animal` classes defined above for the following example:
+There now is a Dog in the Animal box. That's all fine, you can put Dogs in Animal boxes, because Dogs are Animals. But our Animal Box is a Cat Box! You can't put a Dog in a Cat box. If we could, and then try to get the cat from our Cat Box, it would turn out to be a dog, breaking type soundness.
-```scala mdoc
-abstract class Printer[-A] {
- def print(value: A): Unit
-}
+{% tabs invariance_6 %}
+{% tab 'Scala 2 and 3' for=invariance_6 %}
+```scala
+ val myCat: Cat = myCatBox.content //myCat would be Fido the dog!
```
+{% endtab %}
+{% endtabs %}
-A `Printer[A]` is a simple class that knows how to print out some type `A`. Let's define some subclasses for specific types:
+From this, we have to conclude that `Box[Cat]` and `Box[Animal]` can't have a subtyping relationship, even though `Cat` and `Animal` do.
-```scala mdoc
-class AnimalPrinter extends Printer[Animal] {
- def print(animal: Animal): Unit =
- println("The animal's name is: " + animal.name)
-}
+### Covariance
-class CatPrinter extends Printer[Cat] {
- def print(cat: Cat): Unit =
- println("The cat's name is: " + cat.name)
-}
-```
+The problem we ran in to above, is that because we could put a Dog in an Animal Box, a Cat Box can't be an Animal Box.
-If a `Printer[Cat]` knows how to print any `Cat` to the console, and a `Printer[Animal]` knows how to print any `Animal` to the console, it makes sense that a `Printer[Animal]` would also know how to print any `Cat`. The inverse relationship does not apply, because a `Printer[Cat]` does not know how to print any `Animal` to the console. Therefore, we should be able to use a `Printer[Animal]` in place of `Printer[Cat]`, if we wish, and making `Printer[A]` contravariant allows us to do exactly that.
+But what if we couldn't put a Dog in the box? Then, we could just get our Cat back out without a problem, and it would adhere to the subtyping relationship. It turns out that that's possible to do.
+{% tabs covariance_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=covariance_1 %}
```scala mdoc
-def printMyCat(printer: Printer[Cat], cat: Cat): Unit =
- printer.print(cat)
+class ImmutableBox[+A](val content: A)
+val catbox: ImmutableBox[Cat] = new ImmutableBox[Cat](Cat("Felix"))
+val animalBox: ImmutableBox[Animal] = catbox // now this compiles
+```
+{% endtab %}
+{% tab 'Scala 3' for=covariance_1 %}
+```scala
+class ImmutableBox[+A](val content: A)
+val catbox: ImmutableBox[Cat] = ImmutableBox[Cat](Cat("Felix"))
+val animalBox: ImmutableBox[Animal] = catbox // now this compiles
+```
+{% endtab %}
+{% endtabs %}
-val catPrinter: Printer[Cat] = new CatPrinter
-val animalPrinter: Printer[Animal] = new AnimalPrinter
+We say that `ImmutableBox` is *covariant* in `A`, and this is indicated by the `+` before the `A`.
-printMyCat(catPrinter, Cat("Boots"))
-printMyCat(animalPrinter, Cat("Boots"))
-```
+More formally, that gives us the following relationship: given some `class Cov[+T]`, then if `A` is a subtype of `B`, `Cov[A]` is a subtype of `Cov[B]`. This allows us to make very useful and intuitive subtyping relationships using generics.
-The output of this program will be:
+In the following less contrived example, the method `printAnimalNames` will accept a list of animals as an argument and print their names each on a new line. If `List[A]` were not covariant, the last two method calls would not compile, which would severely limit the usefulness of the `printAnimalNames` method.
+{% tabs covariance_2 %}
+{% tab 'Scala 2 and 3' for=covariance_2 %}
+```scala mdoc
+def printAnimalNames(animals: List[Animal]): Unit =
+ animals.foreach {
+ animal => println(animal.name)
+ }
+
+val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom"))
+val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex"))
+
+// prints: Whiskers, Tom
+printAnimalNames(cats)
+
+// prints: Fido, Rex
+printAnimalNames(dogs)
```
-The cat's name is: Boots
-The animal's name is: Boots
-```
+{% endtab %}
+{% endtabs %}
-### Invariance
+### Contravariance
-Generic classes in Scala are invariant by default. This means that they are neither covariant nor contravariant. In the context of the following example, `Container` class is invariant. A `Container[Cat]` is _not_ a `Container[Animal]`, nor is the reverse true.
+We've seen we can accomplish covariance by making sure that we can't put something in the covariant type, but only get something out. What if we had the opposite, something you can put something in, but can't take out? This situation arises if we have something like a serializer, that takes values of type A, and converts them to a serialized format.
+{% tabs contravariance_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=contravariance_1 %}
```scala mdoc
-class Container[A](value: A) {
- private var _value: A = value
- def getValue: A = _value
- def setValue(value: A): Unit = {
- _value = value
- }
+abstract class Serializer[-A] {
+ def serialize(a: A): String
}
+
+val animalSerializer: Serializer[Animal] = new Serializer[Animal] {
+ def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }"""
+}
+val catSerializer: Serializer[Cat] = animalSerializer
+catSerializer.serialize(Cat("Felix"))
```
+{% endtab %}
+{% tab 'Scala 3' for=contravariance_1 %}
+```scala
+abstract class Serializer[-A]:
+ def serialize(a: A): String
-It may seem like a `Container[Cat]` should naturally also be a `Container[Animal]`, but allowing a mutable generic class to be covariant would not be safe. In this example, it is very important that `Container` is invariant. Supposing `Container` was actually covariant, something like this could happen:
+val animalSerializer: Serializer[Animal] = new Serializer[Animal]():
+ def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }"""
+val catSerializer: Serializer[Cat] = animalSerializer
+catSerializer.serialize(Cat("Felix"))
```
-val catContainer: Container[Cat] = new Container(Cat("Felix"))
-val animalContainer: Container[Animal] = catContainer
-animalContainer.setValue(Dog("Spot"))
-val cat: Cat = catContainer.getValue // Oops, we'd end up with a Dog assigned to a Cat
-```
+{% endtab %}
+{% endtabs %}
-Fortunately, the compiler stops us long before we could get this far.
+We say that `Serializer` is *contravariant* in `A`, and this is indicated by the `-` before the `A`. A more general serializer is a subtype of a more specific serializer.
-### Other Examples
+More formally, that gives us the reverse relationship: given some `class Contra[-T]`, then if `A` is a subtype of `B`, `Contra[B]` is a subtype of `Contra[A]`.
-Another example that can help one understand variance is `trait Function1[-T, +R]` from the Scala standard library. `Function1` represents a function with one parameter, where the first type parameter `T` represents the parameter type, and the second type parameter `R` represents the return type. A `Function1` is contravariant over its parameter type, and covariant over its return type. For this example we'll use the literal notation `A => B` to represent a `Function1[A, B]`.
+### Immutability and Variance
+Immutability constitutes an important part of the design decision behind using variance. For example, Scala's collections systematically distinguish between [mutable and immutable collections](https://docs.scala-lang.org/overviews/collections-2.13/overview.html). The main issue is that a covariant mutable collection can break type safety. This is why `List` is a covariant collection, while `scala.collection.mutable.ListBuffer` is an invariant collection. `List` is a collection in package `scala.collection.immutable`, therefore it is guaranteed to be immutable for everyone. Whereas, `ListBuffer` is mutable, that is, you can change, add, or remove elements of a `ListBuffer`.
-Assume the similar `Cat`, `Dog`, `Animal` inheritance tree used earlier, plus the following:
+To illustrate the problem of covariance and mutability, suppose that `ListBuffer` was covariant, then the following problematic example would compile (in reality it fails to compile):
-```scala mdoc
-abstract class SmallAnimal extends Animal
-case class Mouse(name: String) extends SmallAnimal
+{% tabs immutability_and_variance_2 %}
+{% tab 'Scala 2 and 3' %}
+```scala mdoc:fail
+import scala.collection.mutable.ListBuffer
+
+val bufInt: ListBuffer[Int] = ListBuffer[Int](1,2,3)
+val bufAny: ListBuffer[Any] = bufInt
+bufAny(0) = "Hello"
+val firstElem: Int = bufInt(0)
```
+{% endtab %}
+{% endtabs %}
+
+If the above code was possible then evaluating `firstElem` would fail with `ClassCastException`, because `bufInt(0)` now contains a `String`, not an `Int`.
-Suppose we're working with functions that accept types of animals, and return the types of food they eat. If we would like a `Cat => SmallAnimal` (because cats eat small animals), but are given a `Animal => Mouse` instead, our program will still work. Intuitively an `Animal => Mouse` will still accept a `Cat` as an argument, because a `Cat` is an `Animal`, and it returns a `Mouse`, which is also a `SmallAnimal`. Since we can safely and invisibly substitute the former with the latter, we can say `Animal => Mouse` is a subtype of `Cat => SmallAnimal`.
+The invariance of `ListBuffer` means that `ListBuffer[Int]` is not a subtype of `ListBuffer[Any]`, despite the fact that `Int` is a subtype of `Any`, and so `bufInt` cannot be assigned as the value of `bufAny`.
### Comparison With Other Languages
Variance is supported in different ways by some languages that are similar to Scala. For example, variance annotations in Scala closely resemble those in C#, where the annotations are added when a class abstraction is defined (declaration-site variance). In Java, however, variance annotations are given by clients when a class abstraction is used (use-site variance).
+
+Scala's tendency towards immutable types makes it that covariant and contravariant types are more common than in other languages, since a mutable generic type must be invariant.
diff --git a/_uk/cheatsheets/index.md b/_uk/cheatsheets/index.md
new file mode 100644
index 0000000000..24412df349
--- /dev/null
+++ b/_uk/cheatsheets/index.md
@@ -0,0 +1,624 @@
+---
+layout: cheatsheet
+title: Scala Cheatsheet
+
+partof: cheatsheet
+
+by: Dmytro Kazanzhy
+about: Ця шпаргалка створена завдяки Brendan O'Connor, та призначена для швидкого ознайомлення з синтаксичними конструкціями Scala. Ліцензовано Brendan O'Connor за ліцензією CC-BY-SA 3.0.
+
+language: uk
+---
+
+###### Contributed by {{ page.by }}
+
+{{ page.about }}
+
+
+
+
diff --git a/_uk/getting-started/install-scala.md b/_uk/getting-started/install-scala.md
new file mode 100644
index 0000000000..d8ae3efbd9
--- /dev/null
+++ b/_uk/getting-started/install-scala.md
@@ -0,0 +1,221 @@
+---
+layout: singlepage-overview
+title: Перші кроки
+partof: getting-started
+language: uk
+includeTOC: true
+redirect_from:
+ - /uk/scala3/getting-started.html # we deleted the scala 3 version of this page
+---
+
+Інструкції нижче стосуються як Scala 2 так, і та Scala 3.
+
+## Спробуйте Scala без інсталяції
+
+Щоб швидко почати експериментувати зі Scala, відкрийте “Scastie” у вашому браузері.
+_Scastie_ це онлайн “пісочниця”, де ви можете експериментувати з прикладами на Scala та подивитись як все працює, з доступом до всіх компіляторів Scala та доступних бібліотек.
+
+> Scastie підтримує як Scala 2 так, і Scala 3, але за замовчування
+> використовується Scala 3. Якщо ж ви шукаєте приклади на Scala 2,
+> [натисніть тут](https://scastie.scala-lang.org/MHc7C9iiTbGfeSAvg8CKAA).
+
+## Встановіть Scala на ваш комп'ютер
+
+Інсталяція Scala означає встановлення різних command-line інструментів, таких як компілятор Scala та інструменти для збірки.
+Ми радимо використовувати інсталятор "Coursier", який автоматично встановить всі необхідні залежності, але ви можете встановити окремо кожен інструмент.
+
+### За допомогою інсталятора Scala (рекомендовано)
+
+Інсталятор Scala називається [Coursier](https://get-coursier.io/docs/cli-overview), а його основна команда має назву `cs`.
+Він гарантує, що JVM та стандартні інструменти Scala встановлені на вашій системі.
+Щоб встановити його на вашій системі виконайте наступні інструкції.
+
+
+{% tabs install-cs-setup-tabs class=platform-os-options %}
+
+
+{% tab macOS for=install-cs-setup-tabs %}
+Виконайте наступну команду в терміналі, виконуючи всі спливаючі інструкції:
+{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-brew %}
+{% altDetails cs-setup-macos-nobrew "Якщо ви не використовуєте Homebrew:" %}
+{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.macOS-x86-64 %}
+{% endaltDetails %}
+{% endtab %}
+
+
+
+{% tab Linux for=install-cs-setup-tabs %}
+Виконайте наступну команду в терміналі, виконуючи всі спливаючі інструкції:
+{% include code-snippet.html language='bash' codeSnippet=site.data.setup-scala.linux-x86-64 %}
+{% endtab %}
+
+
+
+{% tab Windows for=install-cs-setup-tabs %}
+Завантажте та запустіть [the Scala installer for Windows]({{site.data.setup-scala.windows-link}})
+інсталятор на основі Coursier, виконуючи всі спливаючі інструкції.
+{% endtab %}
+
+
+
+{% tab Other for=install-cs-setup-tabs defaultTab %}
+
+Дотримуйтесь документації від Coursier з того,
+[як встановити і запустити `cs setup`](https://get-coursier.io/docs/cli-installation).
+{% endtab %}
+
+
+{% endtabs %}
+
+
+
+{% altDetails testing-your-setup 'Перевірити налаштування' %}
+Перевірте ваші налаштування виконавши команду `scala -version`, яка має вивести:
+```bash
+$ scala -version
+Scala code runner version: 1.4.3
+Scala version (default): {{site.scala-3-version}}
+```
+Якщо це не спрацювало, необхідно завершити сеанс та зайти в систему знову (або перезавантажити), щоб зміни застосувались на вашій системі.
+{% endaltDetails %}
+
+
+
+Разом з менеджментом JVM-ів, `cs setup` також встановлює корисні command-line інструменти:
+
+| Команда | Опис |
+|---------------|----------------------------------------------------------------------------------------|
+| `scalac` | компілятор Scala |
+| `scala` | інтерактивне середовище Scala та інструмент для запуску скриптів |
+| `scala-cli` | [Scala CLI](https://scala-cli.virtuslab.org), інтерактивні інструменти для Scala |
+| `sbt`, `sbtn` | Інструмент збірки [sbt](https://www.scala-sbt.org/) |
+| `amm` | [Ammonite](https://ammonite.io/) розширене інтерактивне середовище (REPL) |
+| `scalafmt` | [Scalafmt](https://scalameta.org/scalafmt/) призначений для форматування коду на Scala |
+
+Для більш детальної інформації про `cs`, прочитайте
+[документацію coursier-cli](https://get-coursier.io/docs/cli-overview).
+
+> `cs setup` встановлює компілятор Scala 3 та інтерактивне середовище за замовчування (команди `scalac` та
+> `scala` відповідно). Незалежно від того, чи збираєтеся ви використовувати Scala 2 чи 3,
+> тому що більшість проєктів використовує інструменти для збірки,
+> які використовують правильні версії Scala незалежно від того, яка встановлена "глобально".
+> Однак, ви завжди можете запустити певну версію Scala за допомогою
+> ```
+> $ cs launch scala:{{ site.scala-version }}
+> $ cs launch scalac:{{ site.scala-version }}
+> ```
+> Якщо ви надаєте перевагу Scala 2 за замовчуванням, ви можете примусово встановити певну версію:
+> ```
+> $ cs install scala:{{ site.scala-version }} scalac:{{ site.scala-version }}
+> ```
+
+### ...або вручну
+
+Вам необхідно лише два інструменти, для того, щоб скомпілювати, запустити, протестувати й упакувати Scala проєкт: Java 8 або 11, і sbt.
+Щоб встановити їх вручну:
+
+1. Якщо Java 8 або 11 не встановлені, необхідно завантажити
+ Java з [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html),
+ або [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Перевірте [сумісність JDK](/overviews/jdk-compatibility/overview.html) для Scala/Java.
+1. Встановіть [sbt](https://www.scala-sbt.org/download.html)
+
+## Створити проєкт "Hello World" з sbt
+
+Після встановлення sbt ви готові до створення проєкту на Scala, який ми розглянемо в подальших розділах.
+
+Щоб створити проєкт, ви можете використати або термінал, або IDE.
+Якщо ви знайомі з командним рядком, ми рекомендуємо такий підхід.
+
+### За допомогою командного рядка
+
+Інструмент sbt призначений для збірки проєкту на Scala. sbt компілює, запускає,
+та тестує ваш код на Scala. (Також він публікує бібліотеки та виконує багато інших задач.)
+
+Щоб створити новий Scala проєкт за допомогою sbt:
+
+1. Перейдіть (`cd`) в пусту директорію.
+1. Виконайте команду `sbt new scala/scala3.g8`, щоб створити проєкт на Scala 3, або `sbt new scala/hello-world.g8`, щоб створити проєкт на Scala 2.
+ Команда завантажує шаблон проєкту з GitHub.
+ Також, створює директорію `target`, яку ви можете проігнорувати.
+1. Коли буде запропоновано, оберіть назву програми `hello-world`. В результаті буде створено проєкт "hello-world".
+1. Подивимося, що щойно було створено:
+
+```
+- hello-world
+ - project (sbt uses this for its own files)
+ - build.properties
+ - build.sbt (sbt's build definition file)
+ - src
+ - main
+ - scala (весь ваш код на Scala буде тут)
+ - Main.scala (Точка входу в програму) <-- це все, що потрібно наразі
+```
+
+Більше документації про sbt можна знайти у [Книзі по Scala](/scala3/book/tools-sbt.html) (див. [тут](/overviews/scala-book/scala-build-tool-sbt.html) версію для Scala 2)
+та в офіційній [документації](https://www.scala-sbt.org/1.x/docs/index.html) sbt
+
+### За допомогою IDE
+
+Ви можете пропустити подальші кроки та перейти до [Створення Scala проєкту з IntelliJ і sbt](/uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html)
+
+
+## Відкрити проєкт hello-world
+
+Використаймо IDE, щоб відкрити проєкт. Найбільш популярними є IntelliJ та VSCode.
+Обидва з них мають багатий функціонал, але ви також можете використати [багато інших редакторів.](https://scalameta.org/metals/docs/editors/overview.html)
+
+### За допомогою IntelliJ
+
+1. Завантажте та встановіть [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
+1. Встановіть плагін Scala дотримуючись [інструкції з встановлення плагінів в IntelliJ](https://www.jetbrains.com/help/idea/managing-plugins.html)
+1. Відкрийте файл `build.sbt` та оберіть *Відкрити як проєкт* (*Open as a project*)
+
+### За допомогою VSCode та metals
+
+1. Завантажте [VSCode](https://code.visualstudio.com/Download)
+1. Встановіть розширення Metals з [the Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals)
+1. Відкрийте директорію, що містить файл `build.sbt` (це має бути директорія `hello-world` якщо ви виконали попередні інструкції). Коли буде запропоновано, оберіть *Імпортувати збірку* (*Import build*).
+
+>[Metals](https://scalameta.org/metals) це “Сервер мови Scala” який забезпечує можливість написання коду на Scala в VS Code та інших редакторах на кшталт [Atom, Sublime Text, and more](https://scalameta.org/metals/docs/editors/overview.html), використовуючи Language Server Protocol.
+>
+> Під капотом, Metals комунікує з інструментом збірки використовуючи
+> [Build Server Protocol (BSP)](https://build-server-protocol.github.io/). Більш детально про те, як працює Metals, можна подивитись на [“Write Scala in VS Code, Vim, Emacs, Atom and Sublime Text with Metals”](https://www.scala-lang.org/2019/04/16/metals.html).
+
+### Внесення змін в початковий код
+
+Перегляньте ці два файли у вашому IDE:
+
+- _build.sbt_
+- _src/main/scala/Main.scala_
+
+Коли ви будете запускати ваш проєкт у наступному кроці, то будуть використані конфігурації з _build.sbt_ для запуску коду в _src/main/scala/Main.scala_.
+
+## Запустити Hello World
+
+Якщо вам зручно користуватися IDE, ви можете запустити код в _Main.scala_ з вашого IDE.
+
+В іншому випадку ви можете запустити програму через термінал, виконавши такі дії:
+
+1. `cd` в `hello-world`.
+1. Запустіть `sbt`. Це відкриє консоль sbt.
+1. Наберіть `~run`. Символ `~` опціональний і змушує sbt повторно запускатися після кожного збереження файлу,
+ що забезпечує швидкий цикл редагування/запуск/налагодження. sbt також створить директорію `target`, яку ви можете проігнорувати.
+
+Коли ви закінчите експериментувати з вашим проєктом, натисніть `[Enter]` щоб перервати команду `run`.
+Потім наберіть `exit` або затисніть `[Ctrl+D]` щоб вийти з sbt та повернутись до вашого командного рядка.
+
+## Наступні кроки
+
+Після того, як ви закінчите наведені вище посібники, спробуйте пройти:
+
+* [Книга по Scala](/scala3/book/introduction.html) (версія по Scala 2 [тут](/overviews/scala-book/introduction.html)), яка містить коротких ознайомчих уроків з основних можливостей Scala.
+* [Тур по Scala](/tour/tour-of-scala.html) for bite-sized introductions to Scala's features.
+* [Навчальні ресурси](/online-courses.html), що містять інтерактивні онлайн путівники та курси.
+* [Наш список деяких популярних книжок по Scala](/books.html).
+* [Посібник з міграції](/scala3/guides/migration/compatibility-intro.html) допомагає перевести ваш наявний проєкт зі Scala 2 на Scala 3.
+
+## Отримати допомогу
+Існує безліч поштових розсилок та чатів в режимі реального часу, якщо ви захочете зв'язатися з іншими користувачами Scala. Перейдіть на сторінку нашої [спільноти](https://scala-lang.org/community/), щоб побачити перелік можливих способів та попросити про допомогу.
+
diff --git a/_uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md b/_uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md
new file mode 100644
index 0000000000..9a9d303f47
--- /dev/null
+++ b/_uk/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.md
@@ -0,0 +1,100 @@
+---
+title: Створення проєкту на Scala з IntelliJ і sbt
+layout: singlepage-overview
+partof: building-a-scala-project-with-intellij-and-sbt
+language: uk
+disqus: true
+previous-page: /uk/getting-started/intellij-track/getting-started-with-scala-in-intellij
+next-page: /uk/testing-scala-in-intellij-with-scalatest
+---
+
+В цьому посібнику ми побачимо як будувати Scala проєкти використовуючи [sbt](https://www.scala-sbt.org/1.x/docs/index.html).
+sbt — популярний інструмент для компіляції, запуску та тестування проєктів Scala будь-якої складності.
+Використання інструменту збірки, такого як sbt (або Maven/Gradle), стає необхідним, коли ви створюєте проєкти із залежностями або кількома файлами коду.
+Ми припускаємо, що ви завершили [перший посібник](./getting-started-with-scala-in-intellij.html).
+
+## Створення проєкту
+У цьому розділі ми покажемо вам, як створити проєкт в IntelliJ. Однак, якщо вам
+комфортніше працювати у терміналі, ми рекомендуємо подивитись [початок роботи зі Scala і sbt у командному рядку](/uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html)
+і потім повернутися сюди до розділу «Написання коду на Scala».
+
+1. Якщо ви ще не створили проєкт у терміналі, запустіть IntelliJ та оберіть "Створити новий проєкт (Create New Project)"
+ * На панелі зліва оберіть Scala, а на панелі справа оберіть sbt
+ * Натисніть **Next**
+ * Назвіть ваш проєкт "SbtExampleProject"
+1. Якщо ви вже створили проєкт через термінал, запустіть IntelliJ, оберіть *Імпортувати проєкт (Import Project)* та відкрийте файл `build.sbt` вашого проєкту
+1. Впевніться, що **версія JDK** 1.8 або вище, та **версія sbt** 0.13.13 та вище
+1. Натисніть **Use auto-import**, щоб залежності автоматично завантажились
+1. Натисніть **Finish**
+
+## Розуміння структури директорій
+Завдяки sbt створюються директорії, які можуть бути корисні у разі розробки складніших проєктів.
+Поки що ви можете проігнорувати більшість із них, але ось для чого це все:
+
+```
+- .idea (IntelliJ files)
+- project (plugins and additional settings for sbt)
+- src (source files)
+ - main (application code)
+ - java (Java source files)
+ - scala (Scala source files) <-- This is all we need for now
+ - scala-2.12 (Scala 2.12 specific files)
+ - test (unit tests)
+- target (generated files)
+- build.sbt (build definition file for sbt)
+```
+
+
+## Написання коду на Scala
+1. На панелі **Project** зліва розкрийте `SbtExampleProject` => `src` => `main`
+1. Натисніть праву кнопку миші, `scala` та оберіть **New** => **Package**
+1. Назвіть пакет `example` та натисніть **OK** (або просто натисніть клавішу Enter або Return).
+1. Натисніть праву кнопку миші на пакет `example` та оберіть **New** => **Scala class** (якщо ви не бачите цю опцію, натисніть праву кнопку миші на `SbtExampleProject`, натисніть **Add Frameworks Support**, оберіть **Scala** та продовжить)
+1. Назвіть клас `Main` та змініть **Kind** на `Object`.
+1. Змініть код у класі на наступний:
+
+```
+@main def run() =
+ val ages = Seq(42, 75, 29, 64)
+ println(s"The oldest person is ${ages.max}")
+```
+
+Примітка: IntelliJ має власну реалізацію компілятора Scala, тому іноді ваш код є правильним, навіть якщо IntelliJ вказує інше.
+Ви завжди можете перевірити у командному рядку, чи може sbt запустити ваш проєкт.
+
+## Запуск проєкту
+1. З меню **Run** оберіть **Edit configurations**
+1. Натисніть кнопку **+** та оберіть **sbt Task**.
+1. Назвіть його `Run the program`.
+1. В полі **Tasks** наберіть `~run`. Опція `~` змушує sbt перебудовувати та перезапускати проєкт, коли ви зберігаєте зміни у файлі проєкту.
+1. Натисніть **OK**.
+1. В меню **Run** натисніть **Run 'Run the program'**.
+1. В коді змініть `75` на `61` та подивіться оновлений результат в консолі.
+
+## Додавання залежностей
+Давайте ненадовго змістимо фокус на використання опублікованих бібліотек для забезпечення додаткової функціональності ваших програм.
+1. Відкрийте `build.sbt` та додайте наступний рядок:
+
+```
+libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2"
+```
+
+Тут `libraryDependencies` є набором залежностей та використовуючи `+=`,
+ми додаємо залежність [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) до набору залежностей,
+які необхідні для sbt та які завантажаться при його запуску. Тепер в будь-якому Scala файлі ви можете використати
+класи, об'єкти тощо з scala-parser-combinators через звичайний "import".
+
+Більше опублікованих бібліотек можна знайти на
+[Scaladex](https://index.scala-lang.org/) - індекс бібліотек Scala, місце куди ви можете зайти, щоб скопіювати інформацію про бібліотеку
+та додати у ваш `build.sbt` файл.
+
+## Наступні кроки
+
+Перейдіть до наступного навчального матеріалу з серії _початок роботи з IntelliJ_, та дізнайтесь про [тестування Scala в IntelliJ зі ScalaTest](testing-scala-in-intellij-with-scalatest.html).
+
+**або**
+
+* [Книга по Scala](/scala3/book/introduction.html), що є набором коротких вступних уроків з основних особливостей.
+* [Тур по Scala](/tour/tour-of-scala.html) серія коротких оглядових статей про можливості Scala.
+* Продовжить вчити Scala інтерактивно виконуючи
+ [вправи зі Scala](https://www.scala-exercises.org/scala_tutorial).
\ No newline at end of file
diff --git a/_uk/getting-started/intellij-track/getting-started-with-scala-in-intellij.md b/_uk/getting-started/intellij-track/getting-started-with-scala-in-intellij.md
new file mode 100644
index 0000000000..2d44b3ef34
--- /dev/null
+++ b/_uk/getting-started/intellij-track/getting-started-with-scala-in-intellij.md
@@ -0,0 +1,77 @@
+---
+title: Перші кроки зі Scala в IntelliJ
+layout: singlepage-overview
+partof: getting-started-with-scala-in-intellij
+language: uk
+disqus: true
+next-page: /uk/building-a-scala-project-with-intellij-and-sbt
+---
+
+У цьому посібнику буде розглянемо як створити мінімальний проєкт Scala за допомогою IntelliJ IDE з плагіном Scala.
+У цьому посібнику IntelliJ завантажить для вас Scala.
+
+## Встановлення
+1. Впевніться, що ви вже встановили Java 8 JDK (також відому як 1.8)
+ * Запустіть `javac -version` у командному рядку і впевніться, що бачите
+ `javac 1.8.___`
+ * Якщо у вас не встановлена версія 1.8 або вище, [встановіть JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
+1. Далі, завантажте та встановіть [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
+1. Після того, як ви запустили IntelliJ, ви можете завантажити й встановити плагін Scala за інструкцією
+ [як встановлювати плагіни IntelliJ](https://www.jetbrains.com/help/idea/installing-updating-and-uninstalling-repository-plugins.html) (шукайте "Scala" в меню плагінів.)
+
+Під час створення проєкту встановиться остання версія Scala.
+Примітка: якщо ви хочете відкрити наявний проєкт Scala, ви можете натиснути **Open** під час запуску IntelliJ.
+
+## Створення проєкту
+1. Запустіть IntelliJ та натисніть **File** => **New** => **Project**
+1. На панелі зліва оберіть Scala, а на панелі справа - IDEA.
+1. Назвіть проєкт **HelloWorld**
+1. Припускаємо, що ви вперше створюєте проєкт Scala за допомогою IntelliJ,
+ вам потрібно буде встановити Scala SDK. В полі праворуч від Scala SDK натисніть **Create**.
+1. Оберіть останню версію (наприклад, {{ site.scala-version }}) та натисніть **Download**. Це може зайняти декілька хвилин, але наступні проєкти зможуть використати той же SDK.
+1. Після того як створена SDK та ви повернулись до вікна "New Project", натисніть **Finish**.
+
+
+## Написання коду
+
+1. Зліва, на панелі **Project** клацніть кнопкою миші на `src` та оберіть **New** => **Scala class**.
+ Якщо ви не бачите **Scala class**, клацніть правою кнопкою миші на **HelloWorld** та оберіть **Add Framework Support...**, натисніть **Scala** та продовжить.
+ Якщо ви бачите **Error: library is not specified**, ви можете або натиснути на кнопку завантаження або обрати шлях бібліотеки вручну.
+ Якщо ви бачите тільки **Scala Worksheet** спробуйте розкрити директорію `src` та піддиректорію `main` та клацніть правою кнопкою миші на теку `scala`.
+1. Назвіть клас `Hello` та змініть його **Kind** на `object`.
+1. Змініть код класу на наступний:
+
+```
+object Hello extends App {
+ println("Hello, World!")
+}
+```
+
+## Запуск
+* Клацніть правою кнопкою миші `Hello` та оберіть **Run 'Hello'**.
+* Готово!
+
+## Експерименти зі Scala
+Хорошим способом випробувати код є Scala Worksheets
+
+1. Зліва, на панелі проєкту, клацніть правою кнопкою миші на `src` та оберіть **New** => **Scala Worksheet**.
+2. Назвіть робочий лист Scala "Mathematician".
+3. Впишіть наступний код в робочий лист:
+
+```
+def square(x: Int) = x * x
+
+square(2)
+```
+
+Коли ви змінюєте свій код, ви побачите, як він виконується на панелі справа.
+Якщо ви не бачите правої панелі, клацніть правою кнопкою миші на робочому аркуші Scala на панелі проєкту та натисніть Evaluate Worksheet.
+
+
+## Наступні кроки
+
+Тепер ви знаєте, як створити простий проєкт Scala, який можна використовувати,
+щоб почати вивчати мову. У наступному уроці ми познайомимося з важливим інструментом збірки під назвою sbt,
+який можна використовувати як для простих проєктів, так і продакшн програм.
+
+Наступне: [Створення проєкту на Scala з IntelliJ і sbt](building-a-scala-project-with-intellij-and-sbt.html)
diff --git a/_uk/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md b/_uk/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md
new file mode 100644
index 0000000000..b2e1a9f801
--- /dev/null
+++ b/_uk/getting-started/intellij-track/testing-scala-in-intellij-with-scalatest.md
@@ -0,0 +1,70 @@
+---
+title: Тестування Scala в IntelliJ зі ScalaTest
+layout: singlepage-overview
+partof: testing-scala-in-intellij-with-scalatest
+language: uk
+disqus: true
+previous-page: /uk/building-a-scala-project-with-intellij-and-sbt
+---
+
+Існує кілька бібліотек і методологій тестування для Scala,
+але в цьому посібнику ми продемонструємо один популярний варіант для фреймворку ScalaTest,
+що називається [FunSuite](https://www.scalatest.org/getting_started_with_fun_suite).
+
+Ми припускаємо, що ви знаєте [як створити проєкт з IntelliJ](building-a-scala-project-with-intellij-and-sbt.html).
+
+## Налаштування
+1. Створіть sbt проєкт в IntelliJ.
+1. Додайте залежність ScalaTest:
+ 1. Додайте залежність ScalaTest у файл `build.sbt` вашого проєкту:
+ ```
+ libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.19" % Test
+ ```
+ 1. Ви побачите сповіщення "build.sbt was changed", оберіть **auto-import**.
+ 1. Ці дві дії призведуть до того, що `sbt` завантажить бібліотеку ScalaTest.
+ 1. Зачекайте завершення синхронізації `sbt`; інакше `AnyFunSuite` та `test()` не розпізнаються.
+1. На панелі проєкту розкрийте `src` => `main`.
+1. Клацніть правою кнопкою миші на `scala` та оберіть **New** => **Scala class**.
+1. Назвіть його `CubeCalculator` та змініть **Kind** на `object` та натисніть Enter або двічі клацніть на `object`.
+1. Замініть код на наступний:
+ ```
+ object CubeCalculator:
+ def cube(x: Int) =
+ x * x * x
+ ```
+
+## Створення тесту
+1. Зліва на панелі проєкту розкрийте `src` => `test`.
+1. Клацніть правою кнопкою миші на `scala` та оберіть **New** => **Scala class**.
+1. Назвіть клас `CubeCalculatorTest` та натисніть Enter або двічі клацніть на `class`.
+1. Замініть код на наступний:
+ ```
+ import org.scalatest.funsuite.AnyFunSuite
+
+ class CubeCalculatorTest extends AnyFunSuite:
+ test("CubeCalculator.cube") {
+ assert(CubeCalculator.cube(3) === 27)
+ }
+ ```
+1. У початковому коді клацніть правою кнопкою миші на `CubeCalculatorTest` та оберіть **Run 'CubeCalculatorTest'**.
+
+## Розуміння коду
+
+Переглянемо кожний рядок окремо.
+
+* `class CubeCalculatorTest` означає, що ми тестуємо об'єкт `CubeCalculator`
+* `extends AnyFunSuite` використовуємо функціональність класу AnyFunSuite з ScalaTest, насамперед функцію `test`
+* `test` функція з AnyFunSuite, що збирає результати тверджень (assertions) у тілі функції.
+* `"CubeCalculator.cube"` назва тесту. Ви можете обрати будь-яку назву, але існує домовленість називати "ClassName.methodName".
+* `assert` приймає булеву умову і визначає, пройшов тест чи не пройшов.
+* `CubeCalculator.cube(3) === 27` перевіряє чи дорівнює результат функції `cube` значенню 27.
+ Оператор `===` є частиною ScalaTest та надає чисті повідомлення про помилки.
+
+## Додати інший тест-кейс
+1. Додайте інший тестовий блок з власним `assert`, що перевіряє значення куба `0`.
+1. Виконайте `sbt test` знову, двічі клацнувши правою кнопкою миші на `CubeCalculatorTest` та обравши 'Run **CubeCalculatorTest**'.
+
+## Висновок
+Ви побачили один шлях тестування вашого Scala коду. Більше про
+FunSuite ScalaTest на [офіційному вебсайті](https://www.scalatest.org/getting_started_with_fun_suite).
+Ви можете проглянути інші фреймворки для тестування такі як [ScalaCheck](https://www.scalacheck.org/) та [Specs2](https://etorreborre.github.io/specs2/).
diff --git a/_uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md b/_uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md
new file mode 100644
index 0000000000..58adf6baf9
--- /dev/null
+++ b/_uk/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.md
@@ -0,0 +1,84 @@
+---
+title: Початок роботи зі Scala і sbt у командному рядку
+layout: singlepage-overview
+partof: getting-started-with-scala-and-sbt-on-the-command-line
+language: uk
+disqus: true
+next-page: /uk/testing-scala-with-sbt-on-the-command-line
+---
+
+У цьому посібнику ви дізнаєтесь, як створити проєкт Scala шаблон.
+Ви можете використовувати це як відправну точку для власного проєкту.
+Ми використаємо [sbt](https://www.scala-sbt.org/1.x/docs/index.html), що де-факто є основним інструментом збірки для Scala.
+sbt компілює, запускає, та тестує ваші проєкти поміж інших корисних задач.
+Ми припускаємо, що ви знаєте, як користуватися терміналом.
+
+## Встановлення
+1. Впевніться, що ви вже встановили Java 8 JDK (також відому як 1.8)
+ * Запустіть `javac -version` у командному рядку і впевніться, що бачите
+ `javac 1.8.___`
+ * Якщо у вас не встановлена версія 1.8 або вище, [встановіть JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
+1. Встановіть sbt
+ * [Mac](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Mac.html)
+ * [Windows](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Windows.html)
+ * [Linux](https://www.scala-sbt.org/1.x/docs/Installing-sbt-on-Linux.html)
+
+## Створити проєкт
+1. Перейдіть (`cd`) у пусту директорію.
+1. Виконайте наступну команду `sbt new scala/hello-world.g8`.
+Це завантажує шаблон 'hello-world' з GitHub.
+Також буде створена директорія `target`, яку можна ігнорувати.
+1. Коли буде запропоновано, назвіть застосунок `hello-world`. Це створить проєкт з назвою "hello-world".
+1. А тепер подивимось що було згенеровано:
+
+```
+- hello-world
+ - project (sbt uses this to install and manage plugins and dependencies)
+ - build.properties
+ - src
+ - main
+ - scala (All of your scala code goes here)
+ - Main.scala (Entry point of program) <-- this is all we need for now
+ - build.sbt (sbt's build definition file)
+```
+
+Після збірки вашого проєкту, sbt створить більше `target` директорій для згенерованих файлів.
+
+## Запуск проєкту
+1. Перейдіть (`cd`) у `hello-world`.
+1. Виконайте `sbt`. Це запустить sbt консоль.
+1. Наберіть `~run`. Символ `~` є опціональним та означає перебудову при кожному збереженні файлу,
+ що дає можливість пришвидшити цикл редагування/запуск/відлагодження.
+
+## Модифікація коду
+1. Відкрийте файл `src/main/scala/Main.scala` у вашому текстовому редакторі.
+1. Змініть "Hello, World!" на "Hello, New York!"
+1. Якщо ви не зупинили роботу sbt, ви побачите як на консолі з'явиться "Hello, New York!".
+1. Ви можете продовжити робити зміни та бачити результати на консолі.
+
+## Додання залежностей
+Давайте ненадовго змістимо фокус на використання опублікованих бібліотек для забезпечення додаткової функціональності ваших програм.
+
+1. Відкрийте `build.sbt` та додайте наступний рядок:
+
+```
+libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" % "1.1.2"
+```
+
+Тут `libraryDependencies` є набором залежностей та використовуючи `+=`,
+ми додаємо залежність [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) до набору залежностей,
+які необхідні для sbt та які завантажаться при його запуску. Тепер в будь-якому Scala файлі ви можете використати
+класи, об'єкти тощо з scala-parser-combinators через звичайний "import".
+
+Більше опублікованих бібліотек можна знайти на
+[Scaladex](https://index.scala-lang.org/) - індекс бібліотек Scala, місце куди ви можете зайти, щоб скопіювати інформацію про бібліотеку
+та додати у ваш `build.sbt` файл.
+
+## Наступні кроки
+
+Перейдіть до наступного посібника з серії _початок роботи з sbt_, та дізнайтесь про [тестування Scala з sbt та ScalaTest в командному рядку](testing-scala-with-sbt-on-the-command-line.html).
+
+**або**
+
+- Продовжить вивчати Scala інтерактивно нам [Вправи зі Scala](https://www.scala-exercises.org/scala_tutorial).
+- Дізнайтеся про можливості Scala у коротких статтях, переглянувши наш [Тур по Scala]({{ site.baseurl }}/tour/tour-of-scala.html).
diff --git a/_uk/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md b/_uk/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md
new file mode 100644
index 0000000000..fc0a6e62ac
--- /dev/null
+++ b/_uk/getting-started/sbt-track/testing-scala-with-sbt-on-the-command-line.md
@@ -0,0 +1,104 @@
+---
+title: Тестування Scala з sbt та ScalaTest в командному рядку
+layout: singlepage-overview
+partof: testing-scala-with-sbt-on-the-command-line
+language: uk
+disqus: true
+previous-page: /uk/getting-started-with-scala-and-sbt-on-the-command-line
+---
+
+Існує кілька бібліотек і методологій тестування для Scala,
+але в цьому посібнику ми продемонструємо один популярний варіант для фреймворку ScalaTest,
+що називається [AnyFunSuite](https://www.scalatest.org/scaladoc/3.2.2/org/scalatest/funsuite/AnyFunSuite.html).
+
+Ми припускаємо, що ви знаєте [як створити проєкт Scala за допомогою sbt](getting-started-with-scala-and-sbt-on-the-command-line.html).
+
+## Налаштування
+1. Створіть десь новий каталог через командний рядок.
+1. Перейдіть (`cd`) в директорію та запустіть `sbt new scala/scalatest-example.g8`
+1. Назвіть проєкт `ScalaTestTutorial`.
+1. Проєкт вже має ScalaTest як залежність у файлі `build.sbt`.
+1. Перейдіть (`cd`) в директорію та запустіть `sbt test`. Це запустить тестове середовище `CubeCalculatorTest` з єдиним тестом `CubeCalculator.cube`.
+
+```
+sbt test
+[info] Loading global plugins from /Users/username/.sbt/0.13/plugins
+[info] Loading project definition from /Users/username/workspace/sandbox/my-something-project/project
+[info] Set current project to scalatest-example (in build file:/Users/username/workspace/sandbox/my-something-project/)
+[info] CubeCalculatorTest:
+[info] - CubeCalculator.cube
+[info] Run completed in 267 milliseconds.
+[info] Total number of tests run: 1
+[info] Suites: completed 1, aborted 0
+[info] Tests: succeeded 1, failed 0, canceled 0, ignored 0, pending 0
+[info] All tests passed.
+[success] Total time: 1 s, completed Feb 2, 2017 7:37:31 PM
+```
+
+## Розуміння тестів
+1. Відкрийте два файли в текстовому редакторі:
+ * `src/main/scala/CubeCalculator.scala`
+ * `src/test/scala/CubeCalculatorTest.scala`
+1. У файлі `CubeCalculator.scala`, визначте функцію `cube`.
+1. У файлі `CubeCalculatorTest.scala`, ви побачите, що клас, що названий так само як і об'єкт, що ми тестуємо.
+
+```
+ import org.scalatest.funsuite.AnyFunSuite
+
+ class CubeCalculatorTest extends AnyFunSuite {
+ test("CubeCalculator.cube") {
+ assert(CubeCalculator.cube(3) === 27)
+ }
+ }
+```
+
+Переглянемо кожний рядок окремо.
+
+* `class CubeCalculatorTest` означає, що ми тестуємо об'єкт `CubeCalculator`
+* `extends AnyFunSuite` використовуємо функціональність класу AnyFunSuite з ScalaTest, насамперед функцію `test`
+* `test` функція з AnyFunSuite, що збирає результати тверджень (assertions) у тілі функції.
+* `"CubeCalculator.cube"` назва тесту. Ви можете обрати будь-яку назву, але існує домовленість називати "ClassName.methodName".
+* `assert` приймає булеву умову і визначає, пройшов тест чи не пройшов.
+* `CubeCalculator.cube(3) === 27` перевіряє чи дорівнює результат функції `cube` значенню 27.
+ Оператор `===` є частиною ScalaTest та надає чисті повідомлення про помилки.
+
+## Додати інший тест-кейс
+1. Додайте інший тестовий блок з власним `assert`, що перевіряє значення куба '0'.
+
+ ```
+ import org.scalatest.funsuite.AnyFunSuite
+
+ class CubeCalculatorTest extends AnyFunSuite {
+ test("CubeCalculator.cube 3 should be 27") {
+ assert(CubeCalculator.cube(3) === 27)
+ }
+
+ test("CubeCalculator.cube 0 should be 0") {
+ assert(CubeCalculator.cube(0) === 0)
+ }
+ }
+ ```
+
+1. Виконайте `sbt test` знову, щоб побачити результати.
+
+ ```
+ sbt test
+ [info] Loading project definition from C:\projects\scalaPlayground\scalatestpractice\project
+ [info] Loading settings for project root from build.sbt ...
+ [info] Set current project to scalatest-example (in build file:/C:/projects/scalaPlayground/scalatestpractice/)
+ [info] Compiling 1 Scala source to C:\projects\scalaPlayground\scalatestpractice\target\scala-2.13\test-classes ...
+ [info] CubeCalculatorTest:
+ [info] - CubeCalculator.cube 3 should be 27
+ [info] - CubeCalculator.cube 0 should be 0
+ [info] Run completed in 257 milliseconds.
+ [info] Total number of tests run: 2
+ [info] Suites: completed 1, aborted 0
+ [info] Tests: succeeded 2, failed 0, canceled 0, ignored 0, pending 0
+ [info] All tests passed.
+ [success] Total time: 3 s, completed Dec 4, 2019 10:34:04 PM
+ ```
+
+## Висновок
+Ви побачили один шлях тестування вашого Scala коду. Більше про
+FunSuite ScalaTest на [офіційному вебсайті](https://www.scalatest.org/getting_started_with_fun_suite).
+Ви можете проглянути інші фреймворки для тестування такі як [ScalaCheck](https://www.scalacheck.org/) та [Specs2](https://etorreborre.github.io/specs2/).
diff --git a/_uk/index.md b/_uk/index.md
new file mode 100644
index 0000000000..6242b6e807
--- /dev/null
+++ b/_uk/index.md
@@ -0,0 +1,105 @@
+---
+layout: landing-page
+title: Документація
+language: uk
+partof: documentation
+discourse: true
+more-resources-label: Додаткові Матеріали
+
+
+# Content masthead links
+
+
+sections:
+ - title: "Перші кроки..."
+ links:
+ - title: "Початок роботи"
+ description: "Встанови Scala на свій комп'ютер і почни писати код Scala!"
+ icon: "fa fa-rocket"
+ link: /uk/getting-started/install-scala.html
+ - title: "Екскурсія по Скала"
+ description: "Короткі введення в основні особливості мови."
+ icon: "fa fa-flag"
+ link: /tour/tour-of-scala.html
+ - title: "Книга по Scala 3"
+ description: "Вивчи Scala, прочитавши серію коротких уроків."
+ icon: "fa fa-book-open"
+ link: /scala3/book/introduction.html
+ - title: "Онлайн курси"
+ description: "MOOC для вивчення Scala для початківців і досвідчених програмістів."
+ icon: "fa fa-cloud"
+ link: /online-courses.html
+ - title: "Книги"
+ description: "Друковані та цифрові книги по Scala."
+ icon: "fa fa-book"
+ link: /books.html
+ - title: "Посібники"
+ description: "Путівник з серії кроків для створення програм на Scala."
+ icon: "fa fa-tasks"
+ link: /tutorials.html
+
+ - title: "Для досвічених"
+ links:
+ - title: "API"
+ description: "Документація API для кожної версії Scala."
+ icon: "fa fa-file-alt"
+ link: /api/all.html
+ - title: "Посібники та огляди"
+ description: "Поглиблена документація, що покриває багато особливостей Scala."
+ icon: "fa fa-database"
+ link: /uk/overviews/index.html
+ - title: "Довідник по стилю"
+ description: "Поглиблений посібник з написання ідіоматичного коду на Scala."
+ icon: "fa fa-bookmark"
+ link: /style/index.html
+ - title: "Шпаргалка"
+ description: "Зручна шпаргалка з основ синтаксису Scala."
+ icon: "fa fa-list"
+ link: /uk/cheatsheets/index.html
+ - title: "Питання-Відповіді"
+ description: "Відповіді на часті запитання про Scala."
+ icon: "fa fa-question-circle"
+ link: /tutorials/FAQ/index.html
+ - title: "Специфікація мови"
+ description: "Специфікація формальної мови Scala."
+ icon: "fa fa-book"
+ link: https://scala-lang.org/files/archive/spec/2.13/
+ - title: "Довідник про мову"
+ description: "Довідкова інформація про мову Scala 3."
+ icon: "fa fa-book"
+ link: https://docs.scala-lang.org/scala3/reference
+
+ - title: "Дослідіть Scala 3"
+ links:
+ - title: "Посібник з міграції"
+ description: "Посібник, що допоможе перейти від Scala 2 до Scala 3."
+ icon: "fa fa-suitcase"
+ link: /scala3/guides/migration/compatibility-intro.html
+ - title: "Нове у Scala 3"
+ description: "Огляд нових функцій у Scala 3."
+ icon: "fa fa-star"
+ link: /uk/scala3/new-in-scala3.html
+ - title: "Новий Scaladoc для Scala 3"
+ description: "Основні характеристики нових функцій у Scaladoc."
+ icon: "fa fa-star"
+ link: /uk/scala3/scaladoc.html
+ - title: "Доповіді"
+ description: "Онлайн доповіді про Scala 3."
+ icon: "fa fa-play-circle"
+ link: /uk/scala3/talks.html
+
+ - title: "Еволюція Scala"
+ links:
+ - title: "SIPs"
+ description: "Процес удосконалення Scala (Scala Improvement Process). Еволюція мови та компілятора."
+ icon: "fa fa-cogs"
+ link: /sips/index.html
+ - title: "Внесок у Scala"
+ description: "Повний посібник із участі в проекті Scala."
+ icon: "fa fa-cogs"
+ link: /contribute/
+ - title: "Посібник з внесення змін у Scala 3"
+ description: "Посібник з компілятора Scala 3 та вирішення проблем."
+ icon: "fa fa-cogs"
+ link: /scala3/guides/contribution/contribution-intro.html
+---
diff --git a/_uk/overviews/index.md b/_uk/overviews/index.md
new file mode 100644
index 0000000000..355fc560fa
--- /dev/null
+++ b/_uk/overviews/index.md
@@ -0,0 +1,8 @@
+---
+layout: overviews
+partof: overviews
+title: Документація
+language: uk
+---
+
+
diff --git a/_uk/scala3/guides/tasty-overview.md b/_uk/scala3/guides/tasty-overview.md
new file mode 100644
index 0000000000..53eed66f34
--- /dev/null
+++ b/_uk/scala3/guides/tasty-overview.md
@@ -0,0 +1,164 @@
+---
+layout: singlepage-overview
+title: Огляд TASTy
+partof: tasty-overview
+language: uk
+scala3: true
+versionSpecific: true
+---
+Створіть файл вихідного коду Scala 3 _Hello.scala_:
+
+```scala
+@main def hello = println("Hello, world")
+```
+
+і скомпілюйте файл з `scalac`:
+
+```bash
+$ scalac Hello.scala
+```
+
+ви помітите, що серед інших отриманих файлів, `scalac` створює файли з розширенням _.tasty_:
+
+```bash
+$ ls -1
+Hello$package$.class
+Hello$package.class
+Hello$package.tasty
+Hello.scala
+hello.class
+hello.tasty
+```
+
+Виникає питання: «Що таке tasty?»
+
+
+
+## Що таке TASTy?
+
+TASTy це акронім терміну, _Типізоване абстрактне синтаксичне дерево (Typed Abstract Syntax Trees)_.
+Це високорівневий формат для Scala 3, і в цьому документі ми називатимемо його як _Tasty_.
+
+Перше, що важливо знати, це те, що файли Tasty генеруються компілятором `scalac`,
+та містять _всю_ інформацію про ваш вихідний код, включаючи синтаксичну структуру вашої програми,
+і _повну_ інформацію про типи, позицію та навіть документацію.
+Файли Tasty містять набагато більше інформації, ніж файли _.class_, які створюються для роботи на JVM. (Детальніше далі.)
+
+У Scala 3 процес компіляції виглядає так:
+
+```text
+ +-------------+ +-------------+ +-------------+
+$ scalac | Hello.scala | -> | Hello.tasty | -> | Hello.class |
+ +-------------+ +-------------+ +-------------+
+ ^ ^ ^
+ | | |
+ Ваш вихідний Файл TASTy Файл класу
+ код для scalac для JVM
+ (містить повну (неповна
+ інформацію) інформація)
+```
+
+Ви можете переглянути вміст файлу _.tasty_ у зрозумілій формі, запустивши на ньому компілятор із прапорцем `-print-tasty`.
+Ви також можете переглянути вміст, декомпільований у формі, подібній до вихідного коду Scala, використовуючи прапор `-decompile`.
+```bash
+$ scalac -print-tasty hello.tasty
+$ scalac -decompile hello.tasty
+```
+
+### Проблеми з файлами _.class_
+
+Через проблему [стирання типів][erasure], файли _.class_ містять неповне представлення про ваш код.
+Простий спосіб продемонструвати це приклад з `List`.
+
+_Стирання типів_ означає, що коли ви пишете наступний код Scala:
+
+```scala
+val xs: List[Int] = List(1, 2, 3)
+```
+
+цей код компілюється у файл _.class_, який має бути сумісним із JVM. Результатом цієї вимоги сумісності код всередині цього файлу класу — який ви можете побачити за допомогою команди `javap` — виглядає так:
+
+```java
+public scala.collection.immutable.List xs();
+```
+
+Результат команди `javap` показує Java-уявлення того, що міститься у файлі класу. Зверніть увагу, що `xs` більше _не_ визначений як `List[Int]`; він по суті представлений як `List[java.lang.Object]`. Щоб ваш код Scala працював із JVM, тип `Int` має бути стертим.
+
+Далі, коли ви отримуєте елемент вашого `List[Int]` у вашому Scala коді, наприклад:
+
+```scala
+val x = xs(0)
+```
+
+отриманий файл класу матиме операцію перетворення для цього рядка коду, яку ви можете уявити так:
+
+```
+int x = (Int) xs.get(0) // Java-подібно
+val x = xs.get(0).asInstanceOf[Int] // більш Scala-подібно
+```
+
+Знову ж таки, це зроблено для сумісності, щоб ваш код Scala міг працювати на JVM.
+Однак, інформація про те, що ми вже мали список цілих чисел, втрачається у файлах класу.
+Це створює проблеми під час спроби збірки Scala програми з уже скомпільованою бібліотекою.
+Для цього нам потрібно більше інформації, ніж зазвичай міститься у файлах класу.
+
+Ця дискусія охоплює лише тему стирання типу.
+Існують подібні проблеми для кожної іншої конструкції Scala, про які JVM не знає, включно з union, intersection, trait with parameters та багатьма іншими відмінностями Scala 3.
+
+### На допомогу приходить TASTy
+Таким чином, на відміну від відсутньої інформації про вихідні типи у _.class_ файлах або тільки публічного API (як у «Pickle» форматі Scala 2.13), формат TASTy зберігає повне абстрактне синтаксичне дерево (AST) після перевірки типів.
+Зберігання всього AST має багато переваг: воно дає можливість окремої компіляції, перекомпіляції для іншої версії JVM, статичного аналізу програм і багато іншого.
+
+### Ключові моменти
+
+Отже, це перший висновок з цього розділу: типи, які ви вказуєте у своєму коді Scala, не зовсім точно представлені у файлах _.class_.
+
+Другим ключовим моментом є розуміння того, що існують відмінності між інформацією, яка доступна під час _компіляції_ та _виконання_:
+
+- Під **час компіляції**, `scalac` читає та аналізує ваш код, він знає, що `xs` є `List[Int]`
+- Коли компілятор записує ваш код у файл класу, він записує `xs` як `List[Object]`, та додає інформацію про перетворення усюди, де йде звернення до `xs`
+- Потім під **час виконання** — коли ваш код працює в JVM — JVM не знає, що ваш список є `List[Int]`
+
+Зі Scala 3 та Tasty, є ще одна важлива примітка про час компіляції:
+
+- Коли ви пишете код на Scala 3, що використовує інші Scala 3 бібліотеки, `scalac` більше не має читати їх _.class_ файли;
+ він може прочитати їх _.tasty_ файли, які, як згадувалось, є _точним_ представленням вашого коду.
+ Це важливо для забезпечення окремої компіляції та сумісності між Scala 2.13 і Scala 3.
+
+
+## Переваги Tasty
+
+Як ви можете зрозуміти, доступ до повного представлення вашого коду має [багато переваг][benefits]:
+
+- Компілятор використовує його для підтримки окремої компіляції.
+- Сервер мови, що базується на _Мовному серверному протоколі (Language Server Protocol)_ використовує його для підтримки гіперпосилань, завершення команд, документації, та таких глобальних операцій як, пошук звернень та перейменування.
+- Tasty створює чудову основу для нового покоління [макросів основаних на рефлексії][macros].
+- Оптимізатори та аналізатори можуть використовувати його для глибокого аналізу коду та розширеної генерації коду.
+
+У відповідній примітці, Scala 2.13.6 має програму для читання TASTy, а компілятор Scala 3 також може читати формат 2.13 «Pickle».
+У [сторінці з classpath сумісності][compatibility-ref] посібнику з міграції на Scala 3 пояснюється перевага можливості крос-компіляції.
+
+
+
+## Більше інформації
+
+Підсумовуючи, Tasty — це високорівневий формат обміну для Scala 3, а файли _.tasty_ містять повне представлення вашого вихідного коду, що надає до переваги, описані у попередніх розділах.
+Щоб дізнатися більше, перегляньте ці ресурси:
+
+- У [цьому відео](https://www.youtube.com/watch?v=YQmVrUdx8TU), Jamie Thompson зі Scala Center детально розповідає про те, як працює Tasty, та його переваги
+- Статті з [Бінарної сумісності для авторів бібліотек][binary] розглядаються теми бінарної сумісності, сумісності джерел та модель виконання JVM
+- [Подальша сумісність для Scala 3](https://www.scala-lang.org/blog/2020/11/19/scala-3-forward-compat.html) демонструє методи використання Scala 2.13 і Scala 3 в одному проєкті
+
+Ці статті містять додаткову інформацію про макроси Scala 3:
+
+- [Бібліотеки макросів Scala](https://scalacenter.github.io/scala-3-migration-guide/docs/macros/macro-libraries.html)
+- [Макроси: плани для Scala 3](https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html)
+- [Довідник по рефлексії цитат (Quotes Reflect)][quotes-reflect]
+- [Довідник по макросах](/scala3/guides/macros)
+
+[benefits]: https://www.scala-lang.org/blog/2018/04/30/in-a-nutshell.html
+[erasure]: https://www.scala-lang.org/files/archive/spec/2.13/03-types.html#type-erasure
+[binary]: {% link _overviews/tutorials/binary-compatibility-for-library-authors.md %}
+[compatibility-ref]: {% link _overviews/scala3-migration/compatibility-classpath.md %}
+[quotes-reflect]: {{ site.scala3ref }}/metaprogramming/reflection.html
+[macros]: {{ site.scala3ref }}/metaprogramming/macros.html
diff --git a/_uk/scala3/new-in-scala3.md b/_uk/scala3/new-in-scala3.md
new file mode 100644
index 0000000000..0b00d60ca5
--- /dev/null
+++ b/_uk/scala3/new-in-scala3.md
@@ -0,0 +1,139 @@
+---
+layout: singlepage-overview
+title: Нове в Scala 3
+scala3: true
+language: uk
+---
+Нова версія Scala 3 принесла багато покращень і нові можливості.
+Тут наведено короткий огляд найважливіших змін.
+Якщо ви хочете розібратись детальніше глибше, у вашому розпорядженні є наступні посилання:
+
+- [Книга по Scala 3]({% link _overviews/scala3-book/introduction.md %}) націлений на розробників-початківців мови Scala.
+- [Конспект синтаксису][syntax-summary] надає формальний опис нового синтаксису.
+- [Довідник з мови][reference] дає детальний опис змін від Scala 2 до Scala 3.
+- [Посібник з міграції][migration] надає вам всю інформацію, необхідну для переходу від Scala 2 до Scala 3.
+- [Посібник для внесення змін в Scala 3][contribution] глибше занурюється в компілятор, включаючи посібник із розв'язання проблем.
+
+## Що нового в Scala 3
+Scala 3 - це повне перероблення мови Scala. Було змінено багато аспектів
+системи типів на більш принципові. Хоч це і надає нові можливості (наприклад, об’єднання типів),
+але в першу чергу це означає, що у вашій роботі стає менше системи типів та [наведення типів][type-inference].
+Також значно покращено процес перевантаження.
+
+### Нове і яскраве: Синтаксис
+Окрім багатьох (невеликих) очищень, синтаксис Scala 3 пропонує такі покращення:
+
+- Новий «тихий» синтаксис для керуючих структур, таких як `if`, `while` та `for` ([новий синтаксис керуючих структур][syntax-control])
+- Ключеве слово `new` тепер опціональне (_або_ [creator applications][creator])
+- [Опціональні дужки][syntax-indentation] привертають до стилю програмування на основі відступів
+- Зміна [символу підстановки типів][syntax-wildcard] з `_` на `?`.
+- Імплісіти (та їх синтаксис) були [ґрунтовно переглянуті][implicits].
+
+### Впертість: контекстні абстракції
+Одним з основних концептів Scala було (і залишається певною мірою)
+надання користувачам невеликого набору потужних можливостей, які можна комбінувати
+заради великої (а іноді навіть непередбачуваної) виразності. Наприклад, _implicits_
+використовувалися для моделювання контекстної абстракції, для вираження обчислення
+на рівні типів, моделювання типів-класів, виконання неявних приведень, кодування
+розширення методів та багато іншого.
+Базуючись на цих прикладах використання, Scala 3 використовує дещо інший підхід
+і фокусується на **намірі**, а не на **механізмі**.
+Замість того, щоб пропонувати одну дуже потужну функцію, Scala 3 пропонує кілька
+спеціальних мовних конструкцій, що дозволяють програмістам прямо висловлювати свої наміри:
+
+- **Абстрагування над контекстною інформацією**. [Ключове слово using][contextual-using] дозволяє програмістам абстрагуватися від інформації, яка доступна в контексті виклику і повинна передаватися неявно. Конструкція using є удосконаленням implicit зі Scala 2 та може бути визначена за типом, звільняючи сигнатури функцій від термів, на які ніколи не посилаються явно.
+
+- **Надання екземплярів класів типів**. [Наведені екземпляри][contextual-givens] дозволяють програмістам визначати _канонічне значення_ певного типу. Це робить програмування з класами типів простішим без витоку деталей реалізації.
+
+- **Ретроспективне розширення класів**. У Scala 2 методи розширення повинні бути закодовані за допомогою неявних перетворень або неявних класів. На відміну від цього, у Scala 3 [методи розширення][contextual-extension] тепер безпосередньо вбудовані в мову, що призводить до кращих повідомлень про помилки та покращеного виведення типу.
+
+- **Відображення одного типу як іншого**. Неявні перетворення були [перероблені][contextual-conversions] з нуля як екземпляри класу типів `Conversion`.
+
+- **Контекстні абстракції вищого порядку**. _Абсолютно нова_ можливість [контекстних функцій][contextual-functions] робить контекстні абстракції first-class citizen. Вони є важливим інструментом для авторів бібліотек і дозволяють стисло виразити домен-специфічні мови.
+
+- **Дієвий відгук від компілятора**. Якщо неявний параметр не може бути розв'язаний компілятором, то надаються [пропозиції імпорту](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html), що можуть розв'язувати проблему.
+
+### Скажи що маєш на увазі: покращення системи типів
+Окрім значно покращеного виведення типів, система типів Scala 3 також пропонує багато нових функцій, надаючи вам потужні інструменти для статичного вираження інваріантів у типах:
+
+- **Перерахування**. [Enum][enums] був перероблений, щоб добре поєднуватися з кейс-класами та сформувати новий стандарт для вираження [алгебраїчних типів даних][enums-adts].
+
+- **Непрозорі типи**. Сховайте деталі реалізації за [псевдонімом непрозорого типу][types-opaque] без зниження перфомансу! Непрозорі типи замінюють класи значень і дозволяють налаштувати бар'єр абстракції без додаткових накладних витрат.
+
+- **Типи перетину та об'єднання**. Нові засади системи типів призвели до введення нових можливостей системи типів: екземпляр [типу Intersection][types-intersection], як `A & B`, є екземпляром _обох_ типів і `A` і `B`. Екземпляр [типу Union][types-union], як `A | B`, є екземпляром _або_ `A` або `B`. Обидві конструкції дозволяють програмістам гнучко обмежувати типи поза межами ієрархії наслідування.
+
+- **Залежні типи функцій**. Scala 2 вже дозволяє типам результату залежати від (значення) аргументів. У Scala 3 тепер можна абстрагуватися над цим шаблоном і виразити [залежні типи функцій][types-dependent]. В типі `type F = (e: Entry) => e.Key` результат _залежить_ від аргументу!
+
+- **Поліморфні типи функцій**. Як і типи функцій залежності, Scala 2 підтримувала методи, які дозволяють параметри типу, але не дозволяла абстрагуватися над цими методами. У Scala 3, [поліморфні типи функцій][types-polymorphic], наприклад `[A] => List[A] => List[A]` абстрагується над функцією, що приймає _аргумент типу_ на додачу до аргументів значень.
+
+- **Лямбда типу**. Те, що виражалося з використанням [плагіна компілятора](https://github.com/typelevel/kind-projector) в Scala 2 тепер є першокласною особливістю в Scala 3: Лямбда типу — це функції рівня типів, які можна передавати як аргументи типу (вищого роду) без визначення допоміжного типу.
+
+- **Відповідність типів**. Замість того, щоб кодувати обчислення на рівні типу з використанням імплісітів, Scala 3 пропонує пряму підтримку [відповідності за типами][types-match]. Інтеграція обчислень на рівні типів у процес перевірки типів дозволяє покращити повідомлення про помилки та усуває необхідність у складному кодуванні.
+
+
+### Переосмислено: об'єктно-орієнтоване програмування
+Scala завжди була на межі між функціональним програмуванням та об'єктноорієнтованим програмуванням -- і Scala 3 розширює межі в обох напрямках!
+Вищезгадані зміни в системі типів і перероблення контекстних абстракцій роблять _функціональне програмування_ легшим, ніж раніше.
+Водночас наступні нові функції дозволяють добре структурувати _об'єктноорієнтовані проєкти_ та підтримують найкращі практики.
+
+- **Pass it on**. Трейти наближаються до класів і тепер також можуть приймати [параметри][oo-trait-parameters], що робить їх ще більш потужними як інструмент для модульної декомпозиції.
+- **План розширення**. Класи розширення, які не призначені для наслідування, є давньою проблемою в об'єктноорієнтованому програмуванні. Для розв'язання цього питання, [відкриті класи][oo-open] вимагають у розробників бібліотек _явно_ позначити класи як відкриті.
+- **Приховати деталі реалізації**. Утилітні трейти, які іноді реалізують поведінку, не повинні входити до складу виведених типів. У Scala 3, такі трейти можуть бути позначені як [прозорі][oo-transparent] приховуючи наслідування від користувача (у виведених типах).
+- **Композиція понад спадковістю**. Це поняття широко згадується, але є важким у реалізації. Але не з [export][oo-export] у Scala 3's: симетричні до імпорту, експорти дозволяють користувачеві визначати псевдоніми для вибраних членів об'єкта.
+- **Більше без NPE**. Scala 3 безпечніша, ніж будь-коли: [явний null][oo-explicit-null] виводить `null` з ієрархії типів, допомагаючи статично виловлювати помилки; додаткові перевірки для [безпечної ініціалізації][oo-safe-init] виявляють доступ до неініціалізованих об'єктів.
+
+
+### Батарейки в комплекті: метапрограмування
+Хоча макроси в Scala 2 були лише експериментальною функцією, Scala 3 поставляється з потужним арсеналом інструментів для метапрограмування.
+[Посібник по макросах]({% link _overviews/scala3-macros/tutorial/index.md %}) містить детальну інформацію про різні об'єкти. Зокрема, Scala 3 пропонує наступні можливості для метапрограмування:
+
+- **Inline**. Як відправна точка, [inline][meta-inline] дозволяє редукувати значення та методи під час компіляції. Ця проста функція вже охоплює багато варіантів використання і в той же час є точкою входу для більш розширених функцій.
+- **Операції під час компіляції**. Пакет [`scala.compiletime`][meta-compiletime] містить додаткову функціональність, яку можна використовувати для реалізації вбудованих методів.
+- **Цитування блоків коду**. Scala 3 додає нову можливість [квазі-цитування][meta-quotes] коду, що надає зручний інтерфейс високого рівня для побудови та аналізу коду. Побудувати код для додавання одиниці до одиниці так само просто, як і `'{ 1 + 1 }`.
+- **API рефлексії**. Для більш просунутих випадків використання [quotes.reflect][meta-reflection] забезпечує більш детальний контроль для перевірки та створення дерев програм.
+
+Якщо ви хочете дізнатися більше про метапрограмування в Scala 3, пропонуємо подивитись на наш [посібник][meta-tutorial].
+
+
+[enums]: {{ site.scala3ref }}/enums/enums.html
+[enums-adts]: {{ site.scala3ref }}/enums/adts.html
+
+[types-intersection]: {{ site.scala3ref }}/new-types/intersection-types.html
+[types-union]: {{ site.scala3ref }}/new-types/union-types.html
+[types-dependent]: {{ site.scala3ref }}/new-types/dependent-function-types.html
+[types-lambdas]: {{ site.scala3ref }}/new-types/type-lambdas.html
+[types-polymorphic]: {{ site.scala3ref }}/new-types/polymorphic-function-types.html
+[types-match]: {{ site.scala3ref }}/new-types/match-types.html
+[types-opaque]: {{ site.scala3ref }}/other-new-features/opaques.html
+
+[type-inference]: {{ site.scala3ref }}/changed-features/type-inference.html
+[overload-resolution]: {{ site.scala3ref }}/changed-features/overload-resolution.html
+[reference]: {{ site.scala3ref }}/overview.html
+[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html
+[migration]: {% link _overviews/scala3-migration/compatibility-intro.md %}
+[contribution]: {% link _overviews/scala3-contribution/contribution-intro.md %}
+
+[implicits]: {{ site.scala3ref }}/contextual
+[contextual-using]: {{ site.scala3ref }}/contextual/using-clauses.html
+[contextual-givens]: {{ site.scala3ref }}/contextual/givens.html
+[contextual-extension]: {{ site.scala3ref }}/contextual/extension-methods.html
+[contextual-conversions]: {{ site.scala3ref }}/contextual/conversions.html
+[contextual-functions]: {{ site.scala3ref }}/contextual/context-functions.html
+
+[syntax-summary]: {{ site.scala3ref }}/syntax.html
+[syntax-control]: {{ site.scala3ref }}/other-new-features/control-syntax.html
+[syntax-indentation]: {{ site.scala3ref }}/other-new-features/indentation.html
+[syntax-wildcard]: {{ site.scala3ref }}/changed-features/wildcards.html
+
+[meta-tutorial]: {% link _overviews/scala3-macros/tutorial/index.md %}
+[meta-inline]: {% link _overviews/scala3-macros/tutorial/inline.md %}
+[meta-compiletime]: {% link _overviews/scala3-macros/tutorial/compiletime.md %}
+[meta-quotes]: {% link _overviews/scala3-macros/tutorial/quotes.md %}
+[meta-reflection]: {% link _overviews/scala3-macros/tutorial/reflection.md %}
+
+[oo-explicit-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html
+[oo-safe-init]: {{ site.scala3ref }}/other-new-features/safe-initialization.html
+[oo-trait-parameters]: {{ site.scala3ref }}/other-new-features/trait-parameters.html
+[oo-open]: {{ site.scala3ref }}/other-new-features/open-classes.html
+[oo-transparent]: {{ site.scala3ref }}/other-new-features/transparent-traits.html
+[oo-export]: {{ site.scala3ref }}/other-new-features/export.html
diff --git a/_uk/scala3/scaladoc.md b/_uk/scala3/scaladoc.md
new file mode 100644
index 0000000000..66a6d12805
--- /dev/null
+++ b/_uk/scala3/scaladoc.md
@@ -0,0 +1,89 @@
+---
+layout: singlepage-overview
+title: Нові можливості в Scaladoc
+partof: scala3-scaladoc
+language: uk
+scala3: true
+---
+
+Нова версія Scala 3 поставляється з абсолютно новою реалізацією генератора документації _Scaladoc_, переписаною з нуля.
+У цій статті ви можете знайти огляд нових функцій, які є або будуть представлені в Scaladoc.
+Для загальної довідки відвідайте [посібник Scaladoc]({% link _overviews/scala3-scaladoc/index.md %}).
+
+## Нові можливості
+
+### Синтаксис Markdown
+
+Найбільшою зміною, внесеною в нову версію Scaladoc, є зміна мови за замовчуванням для docstrings. Поки що Scaladoc підтримував лише синтаксис Wikidoc.
+Новий Scaladoc все ще може аналізувати застарілий синтаксис `Wikidoc`, однак Markdown вибрано як основну мову для форматування коментарів.
+Щоб повернутися до `Wikidoc`, можна передати глобальний прапор перед запуском `doc` або визначити його для конкретних коментарів за допомогою директиви `@syntax wiki`.
+
+Щоб отримати додаткову інформацію про те, як використовувати повну силу документації, перегляньте [Scaladoc docstrings][scaladoc-docstrings]
+
+
+### Статичні вебсайти
+
+Scaladoc також забезпечує простий спосіб створення **статичних сайтів** як для документації, так і для публікацій у блозі, подібно до того, як це робить Jekyll.
+Завдяки цій функції ви можете зберігати свою документацію разом зі згенерованим API Scaladoc дуже зручним способом.
+
+Щоб отримати додаткову інформацію про те, як налаштувати генерацію статичних сайтів, перегляньте абзац [Статична документація][static-documentation]
+
+
+
+### Публікації в блозі
+
+Дописи в блозі – це особливий тип статичних сайтів. У посібнику Scaladoc ви можете знайти додаткову інформацію про те, як працювати з [публікаціями в блозі][built-in-blog].
+
+
+
+### Посилання на соціальні мережі
+
+Крім того, Scaladoc надає простий спосіб налаштувати [посилання на соціальні мережі][social-links], наприклад Twitter чи Discord.
+
+{: style="width: 180px"}
+
+## Експериментальні особливості
+
+На поточний час (травень 2021 р.) перелічені нижче функції не можуть бути випущені разом із Scaladoc, однак ми будемо раді почути ваші відгуки.
+Кожна функція має власний розділ на сайті учасників scala-lang, де ви можете поділитися своїми думками.
+
+### Компіляція фрагментів
+
+Одним з експериментальних особливостей Scaladoc є компілятор фрагментів (snippets compiler).
+Цей інструмент дозволить вам компілювати фрагменти, які ви додаєте до docstring, щоб перевірити, чи вони насправді поводяться належним чином.
+Ця функція дуже схожа на інструменти `tut` або `mdoc`, але буде поставлятися разом із Scaladoc для легкого налаштування та інтеграції у ваш проєкт.
+Зробити фрагменти інтерактивними, наприклад, дозволити користувачам редагувати та компілювати їх у браузері, наразі розглядається.
+
+Вітрина:
+* Приховування коду 
+* Виявлення помилок компіляції 
+* Включення фрагментів 
+
+Для більш детальної інформації дивіться [Посібники](/scala3/guides/scaladoc/snippet-compiler.html), або перейдіть у [тред Scala Contributors](https://contributors.scala-lang.org/t/snippet-validation-in-scaladoc-for-scala-3/4976)
+
+### Пошук, оснований на типах
+
+Пошук функцій за їх символьними назвами може зайняти багато часу.
+Саме тому новий Scaladoc дозволяє шукати методи та поля за їх типами.
+
+Тому для декларації:
+```
+extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ...
+```
+Замість того, щоб шукати `span`, ми можемо шукати `IArray[A] => (A => Boolean) => (IArray[A], IArray[A])`.
+
+Щоб скористатися цією функцією, просто введіть підпис функції, яку ви шукаєте, на панелі пошуку scaladoc. Ось як це працює:
+
+
+
+Ця функція забезпечується пошуковою системою [Inkuire](https://github.com/VirtusLab/Inkuire), яка працює для Scala 3 і Kotlin. Щоб бути в курсі розвитку цього інструменту, підпишіться на оновлення [репозиторію Inkuire](https://github.com/VirtusLab/Inkuire).
+
+Для отримання додаткової інформації дивіться [Посібники](/scala3/guides/scaladoc/search-engine.html)
+
+Зауважте, що ця функція все ще знаходиться на стадії розробки, тому вона може зазнати значних змін.
+Якщо ви зіткнулися з помилкою або маєте ідею щодо покращення, не соромтеся створювати проблему на [Inkuire](https://github.com/VirtusLab/Inkuire/issues/new) або [dotty](https://github.com/scala/scala3/issues/new).
+
+[scaladoc-docstrings]: {% link _overviews/scala3-scaladoc/docstrings.md %}
+[static-documentation]: {% link _overviews/scala3-scaladoc/static-site.md %}
+[built-in-blog]: {% link _overviews/scala3-scaladoc/blog.md %}
+[social-links]: {% link _overviews/scala3-scaladoc/settings.md %}#-social-links
diff --git a/_uk/scala3/talks.md b/_uk/scala3/talks.md
new file mode 100644
index 0000000000..01087ab671
--- /dev/null
+++ b/_uk/scala3/talks.md
@@ -0,0 +1,90 @@
+---
+layout: singlepage-overview
+title: Розмови
+partof: scala3-talks
+language: uk
+scala3: true
+versionSpecific: true
+---
+
+Серія "Поговорімо про Scala 3"
+-------------------------------
+
+[Поговорімо про Scala 3](https://www.youtube.com/playlist?list=PLTx-VKTe8yLxYQfX_eGHCxaTuWvvG28Ml) є серією
+коротких (близько 15 хвилин) розмов про Scala 3. Він охоплює різноманітні теми, наприклад, як почати, як застосувати
+переваги нових функцій мови, або як перейти з Scala 2.
+
+Talks on Scala 3
+----------------
+- (ScalaDays 2019, Lausanne) [Тур по Scala 3](https://www.youtube.com/watch?v=_Rnrx2lo9cw)
+ від [Martin Odersky](http://x.com/odersky)
+
+- (ScalaDays 2016, Berlin) [Попереду дорога Scala](https://www.youtube.com/watch?v=GHzWqJKFCk4)
+ від [Martin Odersky](http://x.com/odersky)
+ [\[слайди\]](http://www.slideshare.net/Odersky/scala-days-nyc-2016)
+
+- (JVMLS 2015) [Compilers are Databases](https://www.youtube.com/watch?v=WxyyJyB_Ssc)
+ від [Martin Odersky](http://x.com/odersky)
+ [\[слайди\]](http://www.slideshare.net/Odersky/compilers-are-databases)
+
+- (Scala World 2015) [Dotty: Досліджуємо майбутнє Scala](https://www.youtube.com/watch?v=aftdOFuVU1o)
+ від [Dmitry Petrashko](http://x.com/darkdimius)
+ [\[слайди\]](https://d-d.me/scalaworld2015/#/).
+ Розповідь Дмітрія охоплює багато нових функцій, які приносить Dotty, наприклад типи Intersection та Union, покращена ініціалізація lazy val тощо.
+ Дмітрій також розповідає внутрішню архітектуру Dotty і, зокрема, високий рівень контекстуальних абстракцій Dotty. Ви
+ ознайомитесь з багатьма базовими поняттями, такими як «Denotations» та їх особливостями.
+
+Deep Dive with Scala 3
+----------------------
+- (ScalaDays 2019, Lausanne) [Метапрограмування in Dotty](https://www.youtube.com/watch?v=ZfDS_gJyPTc)
+ від [Nicolas Stucki](https://github.com/nicolasstucki).
+
+- (ScalaDays 2019, Lausanne) [Future-proofing в Scala: проміжна репрезентація TASTY](https://www.youtube.com/watch?v=zQFjC3zLYwo)
+ від [[Guillaume Martres](http://guillaume.martres.me/)](http://guillaume.martres.me/).
+
+- (Mar 21, 2017) [Dotty Internals 1: Trees та Symbols](https://www.youtube.com/watch?v=yYd-zuDd3S8)
+ від [Dmitry Petrashko](http://x.com/darkdimius)
+ [\[meeting notes\]](https://dotty.epfl.ch/docs/internals/dotty-internals-1-notes.html).
+ Це запис зустрічі EPFL та Waterloo, де були представлені перші нотатки про Dotty: Trees та Symbols.
+
+- (Mar 21, 2017) [Dotty Internals 2: Types](https://www.youtube.com/watch?v=3gmLIYlGbKc)
+ від [Martin Odersky](http://x.com/odersky) та [Dmitry Petrashko](http://x.com/darkdimius).
+ Це запис зустрічі EPFL та Waterloo, де були представлено як представлені типи всередині Dotty.
+
+- (Jun 15, 2017) [Dotty Internals 3: Denotations](https://youtu.be/9iPA7zMRGKY)
+ від [Martin Odersky](http://x.com/odersky) та [Dmitry Petrashko](http://x.com/darkdimius).
+ Це запис зустрічі EPFL та Waterloo, де були представлена денотація в Dotty.
+
+- (JVM Language Summit) [Як зробити компілятор Dotty швидким](https://www.youtube.com/watch?v=9xYoSwnSPz0)
+ від [Dmitry Petrashko](http://x.com/darkdimius).
+ Дмітрій дає високорівневий вступ до того, що було зроблено для створення Dotty .
+
+- (Typelevel Summit Oslo, May 2016) [Dotty та типи: поки що історія](https://www.youtube.com/watch?v=YIQjfCKDR5A)
+ від [Guillaume Martres](http://guillaume.martres.me/)
+ [\[слайди\]](http://guillaume.martres.me/talks/typelevel-summit-oslo/).
+ Гійом зосередився на деяких практичних вдосконаленнях системи типів, які робить Dotty. Це новий алгоритм параметру типу,
+ який здатний робити висновки про безпеку типів для більшої кількості ситуацій ніж scalac.
+
+- (flatMap(Oslo) 2016) [AutoSpecialization в Dotty](https://vimeo.com/165928176)
+ від [Dmitry Petrashko](http://x.com/darkdimius)
+ [\[слайди\]](https://d-d.me/talks/flatmap2016/#/).
+ Компонувальник Dotty аналізує вашу програму та її залежності, щоб застосувати нову схему спеціалізації.
+ Віна ґрунтується на нашому досвіді з Specialization, Miniboxing та Valhalla Project,
+ і різко зменшує розмір байт-коду. І, що найкраще, це завжди ввімкнено, відбувається за кулісами без анотацій,
+ що призводить до прискорення понад 20 разів. Крім того, він «просто працює» на колекціях Scala.
+
+- (ScalaSphere 2016) [Hacking on Dotty: жива демонстрація](https://www.youtube.com/watch?v=0OOYGeZLHs4)
+ від [Guillaume Martres](http://guillaume.martres.me/)
+ [\[слайди\]](http://guillaume.martres.me/talks/dotty-live-demo/).
+ Прийоми Гійома для Dotty: демонстрація в реальному часі, під час якої він створює просту фазу компілятора для відстеження викликів методів під час виконання.
+
+- (Scala By the Bay 2016) [Dotty: що це і як працює](https://www.youtube.com/watch?v=wCFbYu7xEJA)
+ від [Guillaume Martres](http://guillaume.martres.me/)
+ [\[слайди\]](http://guillaume.martres.me/talks/dotty-tutorial/#/).
+ Гійом демонструє високорівневе представлення пайплайну компіляції в Dotty.
+
+- (ScalaDays 2015, Amsterdam) [Як зробити ваші програми на Scala меншими та швидшими за допомогою компонувальника Dotty](https://www.youtube.com/watch?v=xCeI1ArdXM4)
+ від [Dmitry Petrashko](http://x.com/darkdimius)
+ [\[слайди\]](https://d-d.me/scaladays2015/#/).
+ Дмитрій представляє алгоритм аналізу графу виклик у Dotty та переваги продуктивності, які ми можемо отримати з точки зору кількості методів,
+ розміру байт-коду, розміру коду JVM і кількість об'єктів, виділених в кінці.
diff --git a/_zh-cn/glossary/index.md b/_zh-cn/glossary/index.md
index dc82232e3f..055eff8026 100644
--- a/_zh-cn/glossary/index.md
+++ b/_zh-cn/glossary/index.md
@@ -16,381 +16,381 @@ language: zh-cn
-* #### 代数数据类型（algebraic data type）
-通过提供若干个带有独立构造器的备选项来定义的类型。它一般通过模式匹配的方式来结构类型，在规约语言和函数式编程语言中常见到这个概念。Scala可通过案例类来模拟代数数据类型。
+* ### 代数数据类型（algebraic data type）
+通过提供若干个带有独立构造器的备选项来定义的类型。它一般通过模式匹配的方式来结构类型，在规约语言和函数式编程语言中常见到这个概念。Scala可通过样例类来模拟代数数据类型。
-* #### 备选项（alternative）
+* ### 备选项（alternative）
match表达式的一个分支，形如 “`case` _pattern_ => _expression_”。备选项的别名是 _案例_（_case_）。
-* #### 注解（annotation）
+* ### 注解（annotation）
注解一般出现在源码中，并附加到语法的某个部分。注解对于计算机来说都是可处理的，所以可以用来有效的增加Scala扩展。
-* #### 匿名类（anonymous class）
+* ### 匿名类（anonymous class）
匿名类是由Scala编译器根据一种new表达式生成的合成子类，这种new表达式由类名或特质名后面紧跟一对花括号组成。花括号内包含了匿名子类的构造体，可为空，不过一旦跟在new后面名称指向的特质或类包含了抽象成员，则这些抽象成员就必须在其匿名子类的构造体内具化，即在花括号内要实现这些成员。
-* #### 匿名函数（anonymous function）
+* ### 匿名函数（anonymous function）
[函数字面量](#函数字面量function-literal)的另一种叫法。
-* #### 应用（apply）
+* ### 应用（apply）
方法、函数或闭包应用于参数，意思是说通过这些实参来调用方法、函数或闭包。
-* #### 实参（argument）
+* ### 实参（argument）
在函数调用过程中实参被传给函数的各个参数，其中参数就是指向实参的变量，实参则是调用发生时被传入的对象。另外，应用程序都可以获取被传入单例对象的main方法且类型为`Array[String]`的实参（来自命令行）。
-* #### 赋值（assign）
+* ### 赋值（assign）
可把对象赋值给变量，之后，变量就会指向对象。
-* #### 辅助构造器（auxiliary constructor）
+* ### 辅助构造器（auxiliary constructor）
在类定义体花括号里面定义的所有附加构造器，其形似名为`this`但无结果类型的方法定义。
-* #### 块（block）
+* ### 块（block）
被花括号围起来的一个或多个表达式和声明。求值块的时候，块内所有表达式和声明会被顺序处理，然后会返回最后一个表达式的值作为其自身的值。块通常被用来作为构造体，诸如函数、[for表达式](#for表达式for-expression)、`while`循环以及其他任何需要把语句组织到一起的地方，都会用到块。更正式点说，块是一个只其副作用和结果值对外可见的封装构造体。因此，类或对象的花括号是不会形成块的，因其内部定义字段和方法均对外可见。这样的花括号形成的是模板。
-* #### 绑定变量（bound variable）
+* ### 绑定变量（bound variable）
表达式的绑定变量是定义和使用都在表达式内部的变量。例如，在函数字面量表达式`(x: Int) => (x, y)`里面，`x`和`y`都被用到了，但只有`x`被绑定了，因为它在表达式中被定义为一个`Int`变量，并且它也是表达式所描述函数的唯一实参。
-* #### 传名参数（by-name parameter）
+* ### 传名参数（by-name parameter）
参数类型前面带有`=>`的参数，如`(x: => Int)`。传名参数对应的实参求值不在方法被调用前，而是在每次方法通过名称引用到参数的时候。参数若不是传名的，则定是传值的。
-* #### 传值参数（by-value parameter）
+* ### 传值参数（by-value parameter）
参数类型前面不带`=>`的参数，如`(x: Int)`。传值参数对应的实参是在方法调用前被求值的。传值参数是相对传名参数而言的。
-* #### 类（class）
+* ### 类（class）
通过关键字`class`来定义的类，可抽象可具体，且在实例化时可用类型和值对其进行参数化处理。比如`new Array[String](2)`，被实例化的类是`Array`，产生的值类型为`Array[String]`。带有类型参数的类被称为 _类型构造器_ ，也可说成是类型具有类属性，如：类型`Array[String]`具有的类属性是`Array`。
-* #### 闭包（closure）
+* ### 闭包（closure）
可以捕获自由变量，或者说"关闭"函数创建时可见变量的函数对象。
-* #### 伴生类（companion class）
+* ### 伴生类（companion class）
和定义在相同源文件中的单例对象共享同一个名称的类，这样的类就叫做那个单例对象的伴生类。
-* #### 伴生对象（companion object）
+* ### 伴生对象（companion object）
和定义在相同源文件中的类共享同一个名称的单例对象。伴生对象和伴生类具备访问彼此私有成员的能力。另外，类不管被用在何处，其伴生对象中定义的任何隐式转换都在其作用域内。
-* #### 逆变（contravariant）
+* ### 逆变（contravariant）
逆变标注可应用于类或特质的类型参数上，把减号（-）置于类型参数前即可。标注为逆变后类或特质的子类型将逆向（向相反的方向）协变于类型标注的参数。比如，`Function1`的第一个类型参数就是逆变的，所以`Function1[Any, Any]`是`Function1[String, Any]`的子类。
-* #### 协变（covariant）
-协变标注可应用于类或特质的类型参数上，把加号（+）置于类型参数前即可。标注为协变后类或特质的子类型将正向（向相同的方向）协变于类型标注的参数。比如，`List`的类型参数是协变的，所以`List[String]`是`List[Any]`的子类。
+* ### 协变（covariant）
+协变标注可应用于类或特质的类型参数上，把加号（+）置于类型参数前即可。标注为协变后类或特质的子类型将正向（向相同的方向）协变于类型标注的参数。比如，`List`的类型参数是协变的，所以`List[String]`是`List[Any]`的子类。
-* #### 柯里化（currying）
+* ### 柯里化（currying）
把函数写成多个参数列表的方式。例如：`def f(x: Int)(y: Int)`是一个带有两个参数列表的柯里化函数。应用柯里化函数时需传入若干个实参列表，像`f(3)(4)`这样。不过也可以写成柯里化函数的 _部分应用_（partial application），像`f(3)`这样。
-* #### 声明（declare）
+* ### 声明（declare）
可以通过 _声明_ 抽象的字段、方法或类型来赋给实体一个名称，但是没有具体实现。声明和定义最关键的差异就是定义会为命名实体创建具体实现，而声明则不会。
-* #### 定义（define）
+* ### 定义（define）
在Scala程序中若提到 _定义_ 什么东西，就是说给它赋个名称并给出实现。可以定义的东西包括类、特质、单例对象、字段、方法、局部函数、局部变量等。由于提到定义常常会涉及到某种具体实现，故而抽象成员应为声明而非定义。
-* #### 直接子类（direct subclass）
+* ### 直接子类（direct subclass）
类是其 _直接子类_ 的直接超类。
-* #### 直接超类（direct superclass）
+* ### 直接超类（direct superclass）
从某个类直接衍生出类或特质，或者说在继承层级结构最接近自己的上层的某个类，这样的类就是直接超类。若类`Child`的可选的extends子句中含有类`Parent`，则`Parent`就是`Child`的直接超类。若`Child`的可选extends子句中含有特质，则特质的直接超类也是`Child`的直接超类。若`Child`没有extends子句，则`AnyRef`就是`Child`的直接超类。若类的直接超类带有类型参数，比如`Child extends Parent[String]`，`Child`的直接超类依旧是`Parent`，而不是`Parent[String]`。另一方面，`Parent[String]`应该叫做`Child`的直接超类型。参见[超类型](#超类型supertype)了解更多关于类和类型间的区别。
-* #### 相等性（equality）
+* ### 相等性（equality）
在没有条件限制的情况下使用时，_相等性_ 就是`==`所表达的两个值之间的关系。参见[引用相等性](#引用相等性reference-equality)。
-* #### 存在类型（existential type）
+* ### 存在类型（existential type）
存在类型包含未知类型变量的引用。比如：`Array[T] forSome { type T }`是个存在类型，是`T`的数组，而`T`是某个完全未知的类型，关于`T`唯一能够假定的是它是确定存在的。尽管这个假定很虚，但是至少意味着`Array[T] forSome { type T }`确实是个数组，而不是香蕉什么的东西。
-* #### 表达式（expression）
+* ### 表达式（expression）
任何能够得到结果的Scala代码，也可说成表达式求值为某个结果或结果为某个值。
-* #### 过滤器（filter）
+* ### 过滤器（filter）
[for表达式](#for表达式for-expression)中的`if`及跟在其后的布尔表达式。在`for(i <- 1 to 10; if i % 2 == 0)`中，过滤器为"`if i % 2 == 0`"。`if`右边的值就是[过滤器表达式](#过滤器表达式filter-expression)，也称为守卫。
-* #### 过滤器表达式（filter expression）
+* ### 过滤器表达式（filter expression）
过滤器表达式就是[for表达式](#for表达式for-expression)里面跟在`if`后面的布尔表达式。`for( i <- 1 to 10 ; if i % 2 == 0)`的过滤器表达式为"`i % 2 == 0`"。
-* #### 头等函数（first-class function）
+* ### 头等函数（first-class function）
Scala支持 _头等函数_ ，意味着可以通过函数字面量语法来表达函数。如：`(x: Int) => x + 1`，并且函数可由对象来表达，叫做[函数值](#函数值function-value)。
-* #### for推解式（for comprehension）
+* ### for推解式（for comprehension）
_for推解式_ 是[for表达式](#for表达式for-expression)的一种，一般用来创建新的集合。对`for`推解式的每次迭代，[yield](#产生yield)子句都会定义新集合的一个元素。比如：`for (i <- (0 until 2); j <- (2 until 4)) yield (i, j)`将返回集合`Vector((0,2), (0,3), (1,2), (1,3))`。
-* #### for表达式（for expression）
+* ### for表达式（for expression）
_for表达式_ 要么是个[for循环](#for循环for-loop)，可以迭代一个或多个集合，要么是个[for推解式](#for推解式for-comprehension)，可以从一个或多个集合的元素中推解出一个新的集合。`for`表达式建于[生成器](#生成器generator)、[过滤器](#过滤器filter)、变量定义和[yield](#产生yield)子句（针对[for推解式](#for推解式for-comprehension)）基础之上，
-* #### for循环（for loop）
+* ### for循环（for loop）
_for循环_ 是[for表达式](#for表达式for-expression)的一种，一般用来循环迭代一个或多个集合。因为`for`循环返回unit，所以经常被用来产生副作用。比如：`for (i <- 0 until 100) println(i)`打印数字0到99。
-* #### 自由变量（free variable）
+* ### 自由变量（free variable）
一个表达式的 _自由变量_ 指的是在表达式中使用但不定义在其中的变量。例如，在函数字面量表达式`(x: Int) => (x, y)`中，变量`x`和`y`都被用到了，但只有`y`是自由变量，因其未在表达式中定义。
-* #### 函数（function）
+* ### 函数（function）
_函数_ 可通过一列实参来[调用](#调用invoke)然后产生结果。函数一般具有参数列表、函数体和结果类型。作为类、特质或单例对象的函数叫做[方法](#方法method)。定义在其他函数内部的函数叫做[局部函数](#局部函数local-function)。结果类型为`Unit`的函数叫做[过程](#过程procedure)。源码里面的匿名函数叫做[函数字面量](#函数字面量function-literal)。运行时，函数字面量被实例化为对象，叫做[函数值](#函数值function-value)。
-* #### 函数字面量（function literal）
+* ### 函数字面量（function literal）
在Scala源码中的无名函数，通过函数字面量语法来特别对待。比如：`(x: Int, y: Int) => x + y`。
-* #### 函数值（function value）
+* ### 函数值（function value）
可以像其他函数一样被调用的函数对象。函数值的类一般是继承了`scala`包中的`FunctionN`（比如`Function0`，`Function1`等）这类特质的其中之一，且在源码中常通过[函数字面量](#函数字面量function-literal)语法来表示。当函数值的apply方法被调用时就说这个函数值被调用。捕获自由变量的函数值为[闭包](#闭包closure)。
-* #### 函数式风格（functional style）
+* ### 函数式风格（functional style）
_函数式风格_ 编程注重函数和求值结果而非操作发生的顺序。这种风格的特征是可传递函数值给循环方法、不可变数据、方法无副作用，是像Haskell和Erlang等这些语言的主要范式，与[命令式风格](#命令式风格imperative-style)相对应。
-* #### 生成器（generator）
+* ### 生成器（generator）
生成器在[for表达式](#for表达式for-expression)中定义一个命名的val变量并赋予其一系列值。比如：`for(i <- 1 to 10)`的生成器是"`i <- 1 to 10`"，`<-`右边的值是[生成器表达式](#生成器表达式generator-expression)。
-* #### 生成器表达式（generator expression）
+* ### 生成器表达式（generator expression）
生成器表达式在[for表达式](#for表达式for-expression)中生成一些列值。比如：`for(i <- 1 to 10)`的生成器表达式是"`1 to 10`"。
-* #### 泛型类（generic class）
+* ### 泛型类（generic class）
带有类型参数的类。例如，因`scala.List`带一类型参数，故其为泛型类。
-* #### 泛型特质（generic trait）
+* ### 泛型特质（generic trait）
带有类型参数的特质。例如，因`scala.collection.Set`带一类型参数，故其为泛型特质。
-* #### 守卫（guard）
+* ### 守卫（guard）
参见[过滤器](#过滤器filter).
-* #### 辅助函数（helper function）
+* ### 辅助函数（helper function）
目的是为一个或多个其他邻近函数提供服务的函数。辅助函数常实现为局部函数。
-* #### 辅助方法（helper method）
+* ### 辅助方法（helper method）
作为类成员的[辅助函数](#辅助函数helper-function)。辅助方法常为私有方法。
-* #### 不可变（immutable）
+* ### 不可变（immutable）
若对象的值在任何对客户端可见的方式下创建后不会被修改则称对象是 _不可变_ 的。对象既可以是不可变的，也可以是可变的。
-* #### 命令式风格（imperative style）
+* ### 命令式风格（imperative style）
_命令式风格_ 编程强调严谨的操作序列以令效用能在正确的顺序发生。这种风格的特征是循环迭代、适当变更数据、方法有副作用，是像C, C++, C#和Java等这些语言的主要范式，与[函数式风格](#函数式风格functional-style)相对应。
-* #### 初始化（initialize）
+* ### 初始化（initialize）
变量在Scala源码中被定义时，必须用对象对其进行初始化。
-* #### 实例（instance）
+* ### 实例（instance）
_实例_ ，或叫类实例，是个对象，是个仅在运行时存在的概念
-* #### 实例化（instantiate）
+* ### 实例化（instantiate）
_实例化_ 类是根据类创建一个新对象，是仅在运行时发生的动作。
-* #### 不变性（invariant）
+* ### 不变性（invariant）
_不变性_ 用在两个地方。首先在数据结构组织良好的情况下它可以表示某个属性始终为真。比如，若排序二叉树具有右子节点，则其各节点就会在其右子节点前完成排序，这就属于排序二叉树的不变性。其次有时不变性也作为非协变的同义词，如："类`Array`在类型参数上具备不变性"。
-* #### 调用（invoke）
+* ### 调用（invoke）
在实参上 _调用_ 方法、函数或闭包，意即其方法体会在指定实参上执行。
-* #### Java虚拟机（JVM）
+* ### Java虚拟机（JVM）
_JVM_ 是Java虚拟机(#runtime)的缩写，或叫[运行时](#运行时runtime)，是运行Scala程序的宿主。
-* #### 字面量（literal）
+* ### 字面量（literal）
`1`，`"One"`，和`(x: Int) => x + 1`是 _字面量_ 的例子，字面量是描述对象的便捷方式，便捷在这种方式正好反映了所创建对象的结构。
-* #### 局部函数（local function）
+* ### 局部函数（local function）
_局部函数_ 是块内`def`定义的，作为对比，同为`def`定义的作为类、特质或单例对象的成员则被称作[方法](#方法method)。
-* #### 局部变量（local variable）
+* ### 局部变量（local variable）
_局部变量_ 是块内`val`或`var`定义的。尽管函数参数和[局部变量](#局部变量local-variable)类似，但并不叫局部变量，而是去掉"局部"直接叫"参数"或"变量"。
-* #### 成员（member）
+* ### 成员（member）
_成员_ 是类、特质或单例对象模板中被命名的元素。成员可通过所有者名称，点及其简名访问。例如，定义在类的最顶层字段和方法是这个类的成员。定义在类中的特质是包围它的类的成员。类中通过type关键字定义的类型是这个类的成员。类是其定义所在的包的成员。相比之下，局部变量或局部函数就不是包围他们的块的成员。
-* #### 消息（message）
+* ### 消息（message）
Actor是通过给彼此之间发送 _消息_ 来进行通信的。发送消息不会打断接收者正在处理的事情，接收者可一直等到当前活动结束且其不变性被重建之后。
-* #### 元编程（meta-programming）
+* ### 元编程（meta-programming）
元编程程序是指其输入是其自身程序的程序。编译器都是元程序，像`scaladoc`这样的工具也是。要用注解做任何事都需要元编程程序。
-* #### 方法（method）
+* ### 方法（method）
_方法_ 就是类、特质或单例对象的成员函数。
-* #### 混入（mixin）
+* ### 混入（mixin）
_混入_ 就是特质用在混入组合时的名称。换言之，在"`trait Hat`"里面，`Hat`仅为特质，而"`new Cat extends AnyRef with Hat`"里面的`Hat`就可叫混入。用作动词时，"混"和"入"（"mix in"）是两个词。比如，可 _混_ 特质 _入_ 至类或其他特质。
-* #### 混入组合（mixin composition）
+* ### 混入组合（mixin composition）
把特质混入类或其他特质的过程。_混入组合_ 与传统的多重继承不同之处在于父级引用的类型不是在特质定义时已知的，而是在每次特质每次混入到类或其他特质时才被重新确定。
-* #### 修饰符（modifier）
+* ### 修饰符（modifier）
用来以某种方式限定类、特质、字段或方法等的定义的关键字。比如，`private`修饰符表明被定义的类、特质、字段或方法是私有的。
-* #### 多重定义（multiple definitions）
+* ### 多重定义（multiple definitions）
通过使用类似这样的语法`val v1, v2, v3 = exp`，同一个表达式根据 _多重定义_ 概念可被赋值给多个变量。
-* #### 非协变（nonvariant）
+* ### 非协变（nonvariant）
类或特质的类型参数默认是 _非协变_ 的，故而参数变化并不会子类化相应的类或特质。比如，因类`Array`非协变于其类型参数，故`Array[String]`既非`Array[Any]`之子类，亦非其超类。
-* #### 操作（operation）
+* ### 操作（operation）
在Scala中，每个 _操作_ 都是一个方法调用。方法也可以 _操作符符号_ 的方式被调用，像在`b + 2`里面符号`+`就是一个 _操作符_。
-* #### 参数（parameter）
+* ### 参数（parameter）
函数可带有零至多个 _参数_，每个参数都有名称和类型。参数与实参之间的区别在于函数调用时实参指向具体的对象，参数则是指向这些传入实参的变量。
-* #### 无参函数（parameterless function）
+* ### 无参函数（parameterless function）
不带参数的函数，其定义时没有任何空括号。无参函数可不带括号调用，这种方式符合[统一访问原则](#统一访问原则uniform-access-principle)，就是在客户端不改变任何代码的情况下把`def`改成`val`。
-* #### 无参方法（parameterless method）
+* ### 无参方法（parameterless method）
_无参方法_ 就是作为类、特质或单例对象成员的无参函数。
-* #### 参数化字段（parametric field）
+* ### 参数化字段（parametric field）
定义为类参数的字段。
-* #### 偏应用函数（部分应用函数）（partially applied function）
+* ### 偏应用函数（部分应用函数）（partially applied function）
用在表达式中，省掉某些参数的函数。例如：若函数`f`的类型为`Int => Int => Int`，则`f`和`f(1)`就是 _偏应用函数_。
-* #### 路径依赖类型（path-dependent type）
+* ### 路径依赖类型（path-dependent type）
类似`swiss.cow.Food`的一种类型，`swiss.cow`部分形成一个对象引用的路径。这种类型的含义对于用来访问它的路径是敏感的，比如，`swiss.cow.Food`和`fish.Food`这两个是不同的类型。
-* #### 模式（pattern）
+* ### 模式（pattern）
在`match`表达式的某个备选项中，_模式_ 跟在`case`关键字后，先于 _模式守卫_ 或`=>`符号二者之一。
-* #### 模式守卫（pattern guard）
+* ### 模式守卫（pattern guard）
在`match`表达式的某个备选项中，_模式守卫_ 可跟在某个[模式](#模式pattern)后面。比如，"`case x if x % 2 == 0 => x + 1`"中的模式守卫为"`if x % 2 == 0`"。带有模式守卫的备选项（case）仅当其模式匹配了并且模式守卫为真的时候才会被选中。
-* #### 断言（predicate）
+* ### 断言（predicate）
断言是结果类型为`Boolean`的函数。
-* #### 主构造器（primary constructor）
+* ### 主构造器（primary constructor）
类的主要构造器，会调用超类构造器，如果有必要，也会初始化字段进行传值，并且会执行类的花括号内定义的的顶层（top-level）代码。字段仅由不传给超类构造器的值参数做初始化，那些类构造体内因未用到而被优化掉的除外。
-* #### 过程（procedure）
+* ### 过程（procedure）
_过程_ 是结果类型为`Unit`的函数，其存在的理由仅为产生副作用。
-* #### 可重新赋值（reassignable）
+* ### 可重新赋值（reassignable）
变量可以是可重新赋值的，也可以不是可重新赋值的。`var`是可重新赋值的，而`val`则不是。
-* #### 递归的（recursive）
+* ### 递归的（recursive）
若函数可调用自身就说它是 _递归的_。若函数调用自身的唯一位置是函数的最后一个表达式，则函数是[尾递归](#尾递归tail-recursive)的。
-* #### 引用（reference）
+* ### 引用（reference）
_引用_ 是指针的Java抽象，可唯一确定存在JVM堆中的对象。引用类型变量持有对象的引用，因为引用类型（`AnyRef`的实例）是存在JVM堆上的Java对象实现的。相比之下，值类型变量有时会持有一个（装箱类型的）引用，也有时（当对象表示基础类型值的时候）不会。一般说来，Scala变量[指向](#指向refers)对象。术语"指向"比"持有引用"更加抽象。如果类型为`scala.Int`的变量当前代表Java基础类型`int`的值，则这个变量仍然指向`Int`对象，但并不涉及任何引用。
-* #### 引用相等性（reference equality）
+* ### 引用相等性（reference equality）
_引用相等性_ 意思是两个引用指向同一个Java对象。引用相等性仅针对引用类型有意义，是可以通过调用`AnyRef`中的`eq`来确定的（在Java程序中，引用相等性通过在Java[引用类型](#引用类型reference-type)上调用`==`来确定）。
-* #### 引用类型（reference type）
+* ### 引用类型（reference type）
_引用类型_ 是`AnyRef`的子类。在运行时，引用类型的实例常驻JVM堆中。
-* #### 引用透明（referential transparency）
+* ### 引用透明（referential transparency）
独立于临时上下文且无副作用的函数属性。对于特定输入，引用透明函数的调用可由其结果替换而不改变程序语义。
-* #### 指向（refers）
+* ### 指向（refers）
运行的Scala程序中的变量常 _指向_ 某个对象。变量即使被赋为`null`，概念上也是指向`Null`对象。在运行时，对象可由Java对象或基础类型值来实现，不过Scala允许程序员在更高层次抽象代码以他们设想的方式运行。参见[引用](#引用reference).
-* #### 精化类型（refinement type）
+* ### 精化类型（refinement type）
通过提供基础类型及其构造体花括号内若干成员而形成的类型。花括号内的成员精细化了基础类型所体现的类型。比如，"食草动物"（animal that eats grass）的类型为`Animal { type SuitableFood = Grass }`。
A type formed by supplying a base type a number of members inside curly braces. The members in the curly braces refine the types that are present in the base type. For example, the type of “animal that eats grass” is `Animal { type SuitableFood = Grass }`.
-* #### 结果（result）
+* ### 结果（result）
Scala程序中的表达式会产生 _结果_。Scala中的每个表达式的结果都是对象。
-* #### 结果类型（result type）
+* ### 结果类型（result type）
方法的 _结果类型_ 是调用方法所产生的值的类型。（在Java中，这个概念被称为返回类型）
-* #### 返回（return）
+* ### 返回（return）
Scala程序中的函数会 _返回_ 值，可把这个值叫做函数的[结果](#结果result)。也可以说函数 _结果是_ 某个值。Scala中的每个函数结果都是一个对象。
-* #### 运行时（runtime）
+* ### 运行时（runtime）
正在运行Scala程序的宿主Java虚拟机，或宿主[JVM](#java虚拟机jvm)。运行时这个概念包含了Java虚拟机规范中定义的虚拟机以及Java API和标准Scala API的运行时库。在运行时的这个阶段，意味着程序正在运行中，与编译时是相对的概念。
-* #### 运行时类型（runtime type）
+* ### 运行时类型（runtime type）
对象在运行时的类型。相比之下，[静态类型](#静态类型static-type)指的是表达式在编译时的类型。多数运行时类型都是无类型参数的裸类，比如，`"Hi"`的运行时类型是`String`，`(x: Int) => x + 1`的运行时类型是`Function1`。运行时类型可通过`isInstanceOf`来检测。
-* #### 脚本（script）
+* ### 脚本（script）
包含顶层定义和语句，可直接通过`scala`命令来跑而无需显式编译的文件就是脚本，脚本结尾必须是表达式，而不能是定义。
-* #### 选择器（selector）
+* ### 选择器（selector）
`match`表达式中被匹配的值。比如，在"`s match { case _ => }`"中，选择器是`s`。
-* #### 自身类型（self type）
+* ### 自身类型（self type）
特质的 _自身类型_ 是特质中用到的接收者`this`的假想类型。任何混入特质的具体类必须要确保其类型符合特质的自身类型。自身类型常被用来把大类分解为若干个特质（[Programming in Scala](https://www.artima.com/shop/programming_in_scala)第29章有述）。
-* #### 半结构化数据（semi-structured data）
+* ### 半结构化数据（semi-structured data）
XML数据就是半结构化的，因其相比于普通的二进制文件或文本文件更加结构化，而又不像编程语言的数据结构具备完全结构化。
-* #### 序列化（serialization）
+* ### 序列化（serialization）
可把对象 _序列化_ 成字节流，以便将其保存至文件或通过网络传输。之后可对字节流进行 _反序列化_ （可发生在不同计算机上）来获取和原始被序列化的对象一样的对象。
-* #### 遮掩（shadow）
+* ### 遮掩（shadow）
局部变量的重新声明会 _遮掩_ 作用域内相同名称的变量声明。
-* #### 签名（signature）
+* ### 签名（signature）
_签名_ 是[类型签名](#类型签名type-signature)的简写。
-* #### 单例对象（singleton object）
+* ### 单例对象（singleton object）
由object关键字定义的对象。每个单例对象有且仅有一个实例。与某个类共享名称且与这个类定义在同一源文件中的单例对象，叫这个类的[伴生对象](#伴生对象companion-object)，类则叫单列对象的[伴生类](#伴生类companion-class)。无伴随类的单例对象叫[独立对象](#独立对象standalone-object)。
-* #### 独立对象（standalone object）
+* ### 独立对象（standalone object）
没有[伴生类](#伴生类companion-class)的[单例对象](#单例对象singleton-object)。
-* #### 语句（statement）
+* ### 语句（statement）
指的是表达式、定义或包导入等这些可放到Scala源码的模板或块中的东西。
-* #### 静态类型（static type）
+* ### 静态类型（static type）
参见[类型](#类型type)。
-* #### 结构类型（structural type）
+* ### 结构类型（structural type）
也是一种[精化类型](#精化类型refinement-type)，只是精化的目标是未在基类型中的成员。比如`{ def close(): Unit }`就是结构类型，因其基类型是`AnyRef`，而`AnyRef`并无名为`close`的成员。
-* #### 子类（subclass）
+* ### 子类（subclass）
一个类是其所有[超类](#超类superclass)和[超特质](#超特质supertrait)的 _子类_。
-* #### 子特质（subtrait）
+* ### 子特质（subtrait）
一个特质是其所有[超特质](#超特质supertrait)的 _子特质_。
-* #### 子类型（subtype）
+* ### 子类型（subtype）
Scala编译器允许任何类型在需要该类型的地方使用其 _子类型_ 作为替代。对不带类型参数的类和特质来说，子类型的关系会反映子类的关系。比如，若类`Cat`是抽象类`Animal`的子类，且也不带类型参数，则类型`Cat`就是类型`Animal`的子类型。同样，若特质`Apple`是特质`Fruit`的子特质且无类型参数，则类型`Apple`就是类型`Fruit`的子类型。而对于带有类型参数的类和特质来说，协变就起作用了。比如，由于抽象类`List`被声明为在其长类型参数上是协变的（例，`List`被声明为`List[+A]`），`List[Cat]`是`List[Animal]`的子类型，`List[Apple]`是`List[Fruit]`的子类型。尽管这些类型的类都是`List`，但其子类型的关系依旧是存在的。对比来看，因为`Set`未被声明在其类型参数上是协变的（例，`Set`被声明为`Set[A]`，不带加号），所以`Set[Cat]`并不是`Set[Animal]`的子类型。子类型应该正确实现其超类型的契约，以便应用里氏替换原则（Liskov Substitution Principle），不过编译器仅会在类型检查级别核验此属性。
-* #### 超类（superclass）
+* ### 超类（superclass）
一个类的 _超类_ 包括其直接超类，其直接超类的直接超类，等等一直到`Any`。
-* #### 超特质（supertrait）
+* ### 超特质（supertrait）
类或特质的 _超特质_，如果有的话，就包括所有直接混入类或特质或其任意超类的特质，以及这些特质的所有超特质。
-* #### 超类型（supertype）
+* ### 超类型（supertype）
类型是其所有子类型的 _超类型_。
-* #### 合成类（synthetic class）
+* ### 合成类（synthetic class）
合成类是编译器自动生成的而不是程序员手写的。
-* #### 尾递归（tail recursive）
+* ### 尾递归（tail recursive）
函数是 _尾递归_ 的，仅当函数调用自身的地方是函数的最后一条操作。
-* #### 目标类型化（target typing）
+* ### 目标类型化（target typing）
_目标类型化_ 是参考所需类型来进行类型推导的一种形式。比如在`nums.filter((x) => x > 0)`中，Scala编译器能推导出`x`的类型是`nums`的元素类型，因为`filter`方法会在`nums`的每个元素上调用函数。
-* #### 模板（template）
+* ### 模板（template）
_模板_ 是类、特质或单例对象定义体，它定义了类、特质或对象的类型签名，行为以及初始状态。
-* #### 特质（trait）
+* ### 特质（trait）
_特质_ 通过`trait`关键字定义，是像抽象类一样不带任何值参数，并且可通过被称为[混入组合](#混入组合mixin-composition)的过程"混入到"类或其他特质。当某个特质被混入到其他类或特质，它就被叫做[混入](#混入mixin)。特质可通过一个或多个类型参数化。用类型来参数化后，特质就形成了类型。比如，`Set`是带有单类型参数的特质，而`Set[Int]`却是一个类型。`Set`也被说成是类型`Set[Int]`的"特质"。
-* #### 类型（type）
+* ### 类型（type）
Scala程序中每个变量和表达式都有编译时确定的 _类型_。类型可以在运行时限定变量能指向的值和表达式所能产生的值。如果有必要从对象的[运行时类型](#运行时类型runtime-type)的角度对变量和表达式的类型进行区分的话，他们也被称为 _静态类型_。换句话说，"类型"这个词本身意味着静态类型。类型与类是区分开的因为带有类型参数的类可以构成许多类型。比如，`List`是类不是类型，`List[T]`则是一个带有自由类型参数的类型，`List[Int]`和`List[String]`也是类型（称为实类型因为他们没有自由类型参数）。类型可以有"[类](#类class)"或"[特质](#特质trait)"，比如类型`List[Int]`的类是`List`，类型`Set[String]`的特质是`Set`。
-* #### 类型约束（type constraint）
+* ### 类型约束（type constraint）
有些[注解](#注解annotation)是 _类型约束_，意味着他们会对类型能够包含的取值增加额外的限制或约束。比如，`@positive`可以是类型`Int`的类型约束，用来限制32位整型的取值为正的整数。类型约束虽然不会被标准Scala编译器检查，但相应的必须可被额外的工具或编译器插件检查。
-* #### 类型构造器（type constructor）
+* ### 类型构造器（type constructor）
带类型参数的类或特质。
-* #### 类型参数（type parameter）
+* ### 类型参数（type parameter）
必须被填入类型的泛型类或泛型方法的参数。比如，类`List`定义为"`class List[T] { . . . `"，对象`Predef`的一个成员方法`identity`定义为"`def identity[T](x:T) = x`"，二者定义中的`T`就是类型参数。
-* #### 类型签名（type signature）
+* ### 类型签名（type signature）
方法的 _类型签名_ 包括名称，参数（如果有的话）的数量、顺序和类型，以及结果类型。类、特质或单例对象的类型签名包括名称，所有成员和构造器的类型签名，及其声明的继承和混入关系。
-* #### 统一访问原则（uniform access principle）
+* ### 统一访问原则（uniform access principle）
_统一访问原则_ 指的是变量和无参函数应以相同的语法来访问。Scala通过不允许在无参函数的调用点放置括号来支持该原则。这样的话，无参函数定义就可以改成`val`而不影响客户端代码，_反之亦然_。
-* #### 不可达（unreachable）
+* ### 不可达（unreachable）
在Scala层面，对象可以是 _不可达_ 的，此时其所占据的内存可被运行时回收。不可达并不一定意味着未被引用。引用类型（`AnyRef`的实例）被实现为驻于JVM堆上的对象。当引用类型的实例不可达后，它也确实不被引用了，且可被垃圾回收。值类型（`AnyVal`的实例）可被实现为驻于堆中的基础类型值或Java包装类型实例（如`java.lang.Integer`）。值类型实例可在指向他们的变量的整个生命周期内被装箱（从基础类型值转成包装类型对象）或拆箱（从包装类型对象转成基础类型值）。若表现为JVM堆上的包装类型对象的值类型实例不可达，那就确实不会被引用并且可被垃圾回收。但是若正在表现为基础类型值的值类型不可达，则其仍可被引用，因为此时它并不会以作为对象驻于JVM堆上。运行时可回收不可达对象所占据的内存，但是假如一个Int在运行时被实现为Java基础类型int，在一个运行中的方法的栈帧上占据了一些内存，则这个对象的内存将在方法运行完成且栈帧弹出时才被回收。引用类型的内存，比如`Strings`，可在不可达之后由JVM的垃圾收集器回收。
-* #### 未引用（unreferenced）
+* ### 未引用（unreferenced）
参见[不可达](#不可达unreachable)。
-* #### 值（value）
+* ### 值（value）
Scala中的任何计算或表达式的结果都是一个 _值_，而Scala中的每个值都是一个对象。值这个术语本质上是指对象在内存中（在JVM堆或栈上）的镜像。
-* #### 值类型（value type）
+* ### 值类型（value type）
_值类型_ 是`AnyVal`的任意子类，像`Int`，`Double`或`Unit`。该术语具有Scala源码级别的意味。在运行时，对应于Java基础类型的值类型实例可由基础类型值或包装类型实例来实现，比如`java.lang.Integer`。在值类型实例的整个生命周期内，运行时可将其在基础类型和包装类型间来回转换（如，对其装箱和拆箱）。
-* #### 变量（variable）
+* ### 变量（variable）
指向对象的命名实体。变量要么是`val`，要么是 `var`，`val`变量和`var`变量在定义时都必须被初始化，但仅`var`变量可被重新赋值来指向不同对象。
-* #### 型变（variance）
+* ### 型变（variance）
类或特质的类型参数可用 _型变_ 标号来做标记，即[协变](#协变covariant)（+）或[逆变](#逆变contravariant)（-）。这样的型变标号表明了泛型类或特质的子类化是如何开展的，比如，泛型类`List`在其类型参数上是协变的，因此`List[String]`就是`List[Any]`的子类型。默认情况下，即缺少标号`+`或`-`的类型参数是[非协变](#非协变nonvariant)的。
-* #### 产生（yield）
+* ### 产生（yield）
表达式可以 _产生_ 结果。`yield`关键字指定了[for推解式](#for推解式for-comprehension)的结果。
diff --git a/_zh-cn/index.md b/_zh-cn/index.md
index e6658a19af..53df7a316e 100644
--- a/_zh-cn/index.md
+++ b/_zh-cn/index.md
@@ -1,70 +1,110 @@
---
-layout: inner-page-documentation
-title: 文档
+layout: landing-page
language: zh-cn
-partof: documentation
-discourse: true
-# Content masthead links
+title: 学习 Scala
+namespace: root
+discourse: true
+partof: documentation
more-resources-label: 更多资源
-sections:
+redirect_from:
+ - /scala3/
+ - /scala3/index.html
+sections:
- title: "第一步..."
links:
- title: "快速开始"
- description: "在电脑上安装Scala然后开始写些Scala代码吧！"
+ description: "在电脑上安装 Scala 然后开始写些 Scala 代码吧！"
icon: "fa fa-rocket"
link: /getting-started.html
- - title: "Scala之旅"
+ - title: "scala之旅"
description: "核心语言特性简介"
icon: "fa fa-flag"
- link: /tour/tour-of-scala.html
- - title: "Java程序员Scala入门"
- description: "为具有Java背景的程序员准备的Scala简介"
- icon: "fa fa-coffee"
- link: /tutorials/scala-for-java-programmers.html
- more-resources:
- - title: 在线课程、练习和博客
- url: /learn.html
+ link: /zh-cn/tour/tour-of-scala.html
+ - title: "Scala 3 册子"
+ description: "通过一系列小课程来学习 Scala。"
+ icon: "fa fa-book"
+ link: /zh-cn/scala3/book/introduction.html
+ - title: "Scala 工具箱"
+ description: "发送 HTTP 请求，写文件，运行进程，解析 JSON... "
+ icon: "fa fa-toolbox"
+ link: /toolkit/introduction.html
+ - title: "在线课程"
+ description: "新手和有经验的程序员在 MOOCS 学习 Scala。"
+ icon: "fa fa-cloud"
+ link: /online-courses.html
- title: 书籍
- url: /books.html
+ description: "有关 Scala 的印刷和数字化的书籍。"
+ icon: "fa fa-book"
+ link: /books.html
+ - title: 教程
+ description: "通过一系列步骤，手把手教你创建 Scala 应用。"
+ icon: "fa fa-tasks"
+ link: /tutorials.html
- - title: "回归用户"
+ - title: "回归用户"
links:
- - title: "API"
- description: "各个Scala版本的API文档"
- icon: "fa fa-file-text"
+ - title: "api"
+ description: "各个 Scala 版本的 api 文档"
+ icon: "fa fa-file-alt"
link: /api/all.html
- - title: "总览"
- description: "涵盖Scala各种特性的深度分析文档"
+ - title: "导引和总览"
+ description: "涵盖 Scala 各种特性的深度分析文档"
icon: "fa fa-database"
- link: /overviews/index.html
+ link: /zh-cn/overviews/index.html
- title: "风格引导"
- description: "深度指导如何写出地道的Scala代码"
+ description: "深度指导如何写出地道的 Scala 代码"
icon: "fa fa-bookmark"
link: /style/index.html
- title: "速查"
- description: "包含Scala基础语法的速查手册"
+ description: "包含 Scala 基础语法的速查手册"
icon: "fa fa-list"
- link: /cheatsheets/index.html
- - title: "Scala常见问题"
- description: "Scala语言特性的常见问题及答案"
+ link: /zh-cn/cheatsheets/index.html
+ - title: "Scala 常见问题"
+ description: "Scala 语言特性的常见问题及答案。"
icon: "fa fa-question-circle"
link: /tutorials/FAQ/index.html
- - title: "语言规范"
- description: "Scala正式语言规范"
+ - title: "语言规范 v2.x"
+ description: "Scala 2 正式的语言规范。"
+ icon: "fa fa-book"
+ link: https://scala-lang.org/files/archive/spec/2.13/
+ - title: "语言规范 v3.x"
+ description: "Scala 3 正式的语言规范。"
+ icon: "fa fa-book"
+ link: https://scala-lang.org/files/archive/spec/3.4/
+ - title: "Scala 3 语言参考"
+ description: "Scala 3 语言参考"
icon: "fa fa-book"
- link: https://scala-lang.org/files/archive/spec/2.12/
+ link: https://docs.scala-lang.org/scala3/reference
- - title: "Scala进展"
+ - title: "探索 Scala 3"
links:
- - title: "SIPs"
- description: "Scala改进过程（Scala Improvement Process），语言及编译器进展"
+ - title: "迁移指引"
+ description: "一份帮你从 Scala 2 迁移到 Scala 3 的指引。"
+ icon: "fa fa-suitcase"
+ link: /scala3/guides/migration/compatibility-intro.html
+ - title: "Scala 3 中的新东西"
+ description: "Scala 3 中令人兴奋的新特性概览"
+ icon: "fa fa-star"
+ link: /zh-cn/scala3/new-in-scala3.html
+ - title: "Scala 3 全新的 Scaladoc"
+ description: "Scaladoc 新特性重点介绍"
+ icon: "fa fa-star"
+ link: /scala3/scaladoc.html
+ - title: "演讲"
+ description: "可在线观看的关于 Scala 3 的演讲"
+ icon: "fa fa-play-circle"
+ link: /scala3/talks.html
+
+ - title: "Scala 进展"
+ links:
+ - title: "Scala 改进过程"
+ description: "描述涉及语言的过程，和所有 Scala 改进提案(SIPs)的列表。"
icon: "fa fa-cogs"
link: /sips/index.html
- - title: "SPP"
- description: "Scala平台进程（Scala Platform Process）， 社区驱动代码库的进展"
- icon: "fa fa-users"
- link: https://platform.scala-lang.org
-
+ - title: "成为 Scala OSS 贡献者"
+ description: "从头到尾：发现你如何帮助 Scala 开源生态系统。"
+ icon: "fa fa-code-branch"
+ link: /contribute/
---
diff --git a/_zh-cn/overviews/collections/overview.md b/_zh-cn/overviews/collections/overview.md
index aa88b30158..d5bf0f71fa 100644
--- a/_zh-cn/overviews/collections/overview.md
+++ b/_zh-cn/overviews/collections/overview.md
@@ -13,7 +13,7 @@ Scala 集合类系统地区分了可变的和不可变的集合。可变集合
所有的集合类都可以在包`scala.collection` 或`scala.collection.mutable`，`scala.collection.immutable`，`scala.collection.generic`中找到。客户端代码需要的大部分集合类都独立地存在于3种变体中，它们位于`scala.collection`, `scala.collection.immutable`, `scala.collection.mutable`包。每一种变体在可变性方面都有不同的特征。
-`scala.collection.immutable`包是的集合类确保不被任何对象改变。例如一个集合创建之后将不会改变。因此，你可以相信一个事实，在不同的点访问同一个集合的值，你将总是得到相同的元素。。
+`scala.collection.immutable`包的集合类确保不被任何对象改变。例如一个集合创建之后将不会改变。因此，你可以相信一个事实，在不同的点访问同一个集合的值，你将总是得到相同的元素。。
`scala.collection.mutable`包的集合类则有一些操作可以修改集合。所以处理可变集合意味着你需要去理解哪些代码的修改会导致集合同时改变。
diff --git a/_zh-cn/overviews/core/actors-migration-guide.md b/_zh-cn/overviews/core/actors-migration-guide.md
deleted file mode 100644
index 72ad6c8e1b..0000000000
--- a/_zh-cn/overviews/core/actors-migration-guide.md
+++ /dev/null
@@ -1,463 +0,0 @@
----
-layout: singlepage-overview
-title: Scala Actors迁移指南
-
-partof: actor-migration
-
-language: zh-cn
----
-
-**Vojin Jovanovic 和 Philipp Haller 著**
-
-## 概述
-
-从Scala的2.11.0版本开始，Scala的Actors库已经过时了。早在Scala2.10.0的时候，默认的actor库即是Akka。
-
-为了方便的将Scala Actors迁移到Akka，我们提供了Actor迁移工具包（AMK）。通过在一个项目的类路径中添加scala-actors-migration.jar，AMK包含了一个针对Scala Actors扩展。此外，Akka 2.1包含一些特殊功能，比如ActorDSL singleton，可以实现更简单的转换功能，使Scala Actors代码变成Akka代码。本章内容的目的是用来指导用户完成迁移过程，并解释如何使用AMK。
-
-本指南包括以下内容：在“迁移工具的局限性”章节中，我们在此概述了迁移工具的主要局限性。在“迁移概述”章节中我们描述了迁移过程和谈论了Scala的变化分布，使得迁移成为一种可能。最后，在“一步一步指导迁移到Akka”章节里，我们展示了一些迁移工作的例子，以及各个步骤，如果需要从Scala Actors迁移至Akka's actors，本节是推荐阅读的。
-
-免责声明:并发代码是臭名昭著的，当出现bug时很难调试和修复。由于两个actor的不同实现，这种差异导致可能出现错误。迁移过程每一步后都建议进行完全的代码测试。
-
-## 迁移工具的局限性
-
-由于Akka和Scala的actor模型的完整功能不尽相同导致两者之间不能平滑地迁移。下面的列表解释了很难迁移的部分行为：
-
-1. 依靠终止原因和双向行为链接方法 - Scala和Akka actors有不同的故障处理和actor monitoring模型。在Scala actors模型中，如果一个相关联部分异常终止，相关联的actors终止。如果终止是显式跟踪(通过self.trapExit)，actor可以从失败的actor收到终止的原因。通过Akka这个功能不能迁移到AMK。AMK允许迁移的只是[Akka monitoring](https://doc.akka.io/docs/akka/2.1.0/general/supervision.html#What_Lifecycle_Monitoring_Means)机制。Monitoring不同于连接,因为它是单向(unindirectional)的并且终止的原因是现在已知的。如果仅仅是monitoring机制是无法满足需求的,迁移的链接必须推迟到最后一刻(步骤5的迁移)。然后,当迁移到Akka,用户必须创建一个[监督层次(supervision hierarchy)](https://doc.akka.io/docs/akka/2.1.0/general/supervision.html),处理故障。
-
-2. 使用restart方法——Akka不提供显式的重启actors，因此上述例子我们不能提供平滑迁移。用户必须更改系统,所以没有使用重启方法(restart method)。
-
-3. 使用getState方法 - Akka actors没有显式状态,此功能无法迁移。用户代码必须没有getState调用。
-
-4. 实例化后没有启动actors - Akka actors模型会在实例化后自动启动actors，所以用户不需要重塑系统来显式的在实例化后启动actors。
-
-5. mailboxSize方法不存在Akka中,因此不能迁移。这种方法很少使用,很容易被删除。
-
-## 迁移概述
-
-### 迁移工具
-
-在Scal 2.10.0 actors 是在[Scala distribution](https://www.scala-lang.org/downloads)中作为一个单独包（scala-actors.jar）存在的，并且他们的接口已被弃用。这种分布也包含在Akka actors的akka-actor.jar里。AMK同时存在Scala actors 和 akka-actor.jar之中。未来的主要版本的Scala将不包含Scala actors和AMK。
-
-开始迁移，用户需要添加scala-actors.jar和scala-actors-migration.jar来构建他们的项目。添加scala-actors.jar和scala-actors-migration.jar允许使用下面描述的AMK。这些jar位于Scala Tools库和[Scala distribution](https://www.scala-lang.org/downloads)库中。
-
-### 一步一步来迁移
-
-Actor迁移工具使用起来应该有5步骤。每一步都设计为引入的基于代码的最小变化。在前四个迁移步骤的代码中将使用Scala actors来实现，并在该步完成后运行所有的系统测试。然而,方法和类的签名将被转换为与Akka相似。迁移工具在Scal方面引入了一种新的actor类型（ActWithStash）和强制执行actors的ActorRef接口。
-
-该结果同样强制通过一个特殊的方法在ActorDSL 对象上创建actors。在这些步骤可以每次迁移一个actor。这降低了在同一时刻引入多个bug的可能性，同样降低了bug的复杂程度。
-
-在Scala方面迁移完成后，用户应该改变import语句并变成使用Akka库。在Akka方面，ActorDSL和ActWithStash允许对Scala Actors和他们的生态系的react construct进行建模。这个步骤迁移所有actors到Akka的后端，会在系统中引入bug。一旦代码迁移到Akka,用户将能够使用Akka的所有的功能的。
-
-### 一步一步指导迁移到Akka
-
-在这一章中,我们将通过actor迁移的5个步骤。在每一步之后的代码都要为可能的错误进行检测。在前4个步骤中可以一边迁移一个actor和一边测试功能。然而,最后一步迁移所有actors到Akka后它只能作为一个整体进行测试。在这个步骤之后系统应该具有和之前一样相同的功能，不过它将使用Akka actor库。
-
-### 步骤1——万物皆是Actor
-
-Scala actors库提供了公共访问多个类型的actors。他们被组织在类层次结构和每个子类提供了稍微更丰富的功能。为了进一步的使迁移步骤更容易，我们将首先更改Actor类型系统中的每一个actor。这种迁移步骤很简单，因为Actor类位于层次结构的底部，并提供了广泛的功能。
-
-来自Scala库的Actors应根据以下规则进行迁移：
-
-1. class MyServ extends Reactor[T] -> class MyServ extends Actor
-
-注意,反应器提供了一个额外的类型参数代表了类型的消息收到。如果用户代码中使用这些信息，那么一个需要：i）应用模式匹配与显式类型,或者ii）做一个向下的消息来自任何泛型T。
-
-1. class MyServ extends ReplyReactor -> class MyServ extends Actor
-
-2. class MyServ extends DaemonActor -> class MyServ extends Actor
-
-为了为DaemonActor提供配对功能，将下列代码添加到类的定义。
-
- override def scheduler: IScheduler = DaemonScheduler
-
-### 步骤2 - 实例化
-
-在Akka中,actors可以访问只有通过ActorRef接口。ActorRef的实例可以通过在ActorDSL对象上调用actor方法或者通过调用ActorRefFactory实例的actorOf方法来获得。在Scala的AMK工具包中，我们提供了Akka ActorRef和ActorDSL的一个子集，该子集实际上是Akka库的一个单例对象(singleton object)。
-
-这一步的迁移使所有actors访问通过ActorRefs。首先，我们现实如何迁移普通模式的实例化Sacla Actors。然后，我们将展示如何分别克服问题的ActorRef和Actor的不同接口。
-
-#### Actor实例化
-
-actor实例的转换规则（以下规则需要import scala.actors.migration._）：
-
-1. 构造器调用实例化
-
- val myActor = new MyActor(arg1, arg2)
- myActor.start()
-
-应该被替换
-
- ActorDSL.actor(new MyActor(arg1, arg2))
-
-2. 用于创建Actors的DSL(译注：领域专用语言(Domain Specific Language))
-
- val myActor = actor {
- // actor 定义
- }
-应该被替换
-
- val myActor = ActorDSL.actor(new Actor {
- def act() {
- // actor 定义
- }
- })
-
-3. 从Actor Trait扩展来的对象
-
- object MyActor extends Actor {
- // MyActor 定义
- }
- MyActor.start()
-应该被替换
-
- class MyActor extends Actor {
- // MyActor 定义
- }
-
- object MyActor {
- val ref = ActorDSL.actor(new MyActor)
- }
-所有的MyActor地想都应该被替换成MyActor.ref。
-
-需要注意的是Akka actors在实例化的同时开始运行。actors创建并开始在迁移的系统的情况下，actors在不同的位置以及改变这可能会影响系统的行为，用户需要更改代码，以使得actors在实例化后立即开始执行。
-
-远程actors也需要被获取作为ActorRefs。为了得到一个远程actor ActorRef需使用方法selectActorRef。
-
-#### 不同的方法签名(signatures)
-
-至此为止我们已经改变了所有的actor实例化，返回ActorRefs，然而，我们还没有完成迁移工作。有不同的接口在ActorRefs和Actors中，因此我们需要改变在每个迁移实例上触发的方法。不幸的是，Scala Actors提供的一些方法不能迁移。对下列方法的用户需要找到一个解决方案:
-
-1. getState()——Akka中的actors 默认情况下由其监管actors(supervising actors)负责管理和重启。在这种情况下,一个actor的状态是不相关的。
-
-2. restart() - 显式的重启一个Scala actor。在Akka中没有相应的功能。
-
-所有其他Actor方法需要转换为两个ActorRef中的方法。转换是通过下面描述的规则。请注意,所有的规则需要导入以下内容:
-
- import scala.concurrent.duration._
- import scala.actors.migration.pattern.ask
- import scala.actors.migration._
- import scala.concurrent._
-额外规则1-3的作用域定义在无限的时间需要一个隐含的超时。然而，由于Akka不允许无限超时，我们会使用100年。例如：
-
- implicit val timeout = Timeout(36500 days)
-
-规则：
-
-1. !!(msg: Any): Future[Any] 被？替换。这条规则会改变一个返回类型到scala.concurrent.Future这可能导致类型不匹配。由于scala.concurrent.Future比过去的返回值具有更广泛的功能，这种类型的错误可以很容易地固定在与本地修改：
-
- actor !! message -> respActor ? message
-
-2. !![A] (msg: Any, handler: PartialFunction[Any, A]): Future[A] 被？取代。处理程序可以提取作为一个单独的函数，并用来生成一个future对象结果。处理的结果应给出另一个future对象结果,就像在下面的例子:
-
- val handler: PartialFunction[Any, T] = ... // handler
- actor !! (message, handler) -> (respActor ? message) map handler
-
-3. !? (msg: Any):任何被？替换都将阻塞在返回的future对象上
-
- actor !? message ->
- Await.result(respActor ? message, Duration.Inf)
-
-4. !? (msec: Long, msg: Any): Option[Any]任何被？替换都将显式的阻塞在future对象
-
- actor !? (dur, message) ->
- val res = respActor.?(message)(Timeout(dur milliseconds))
- val optFut = res map (Some(_)) recover { case _ => None }
- Await.result(optFut, Duration.Inf)
-
-这里没有提到的公共方法是为了actors DSL被申明为公共的。他们只能在定义actor时使用，所以他们的这一步迁移是不相关的。
-
-###第3步 - 从Actor 到 ActWithStash
-
-到目前为止，所有的控制器都继承自Actor trait。我们通过指定的工厂方法来实例化控制器，所有的控制器都可以通过接口ActorRef 来进行访问。现在我们需要把所有的控制器迁移的AMK 的 ActWithStash 类上。这个类的行为方式和Scala的Actor几乎完全一致，它提供了另外一些方法，对应于Akka的Actor trait。这使得控制器更易于逐步的迁移到Akka。
-
-为了达到这个目的，所有的从Actor继承的类，按照下列的方式，需要改为继承自ActWithStash：
-
- class MyActor extends Actor -> class MyActor extends ActWithStash
-
-经过这样修改以后，代码会无法通过编译。因为ActWithStash中的receive 方法不能在act中像原来那样使用。要使代码通过编译，需要在所有的 receive 调用中加上类型参数。例如：
-
- receive { case x: Int => "Number" } ->
- receive[String] { case x: Int => "Number" }
-
-另外，要使代码通过编译，还要在act方法前加上 override关键字，并且定义一个空的receive方法。act方法需要被重写，因为它在ActWithStash 的实现中模拟了Akka的消息处理循环。需要修改的地方请看下面的例子：
-
- class MyActor extends ActWithStash {
-
- // 空的 receive 方法 (现在还没有用)
- def receive = {case _ => }
-
- override def act() {
- // 原来代码中的 receive 方法改为 react。
- }
- }
-ActWithStash 的实例中，变量trapExit 的缺省值是true。如果希望改变，可以在初始化方法中把它设置为false。
-
-远程控制器在ActWithStash 下无法直接使用，register('name, this)方法需要被替换为：
-
- registerActorRef('name, self)
-
-在后面的步骤中， registerActorRef 和 alive 方法的调用与其它方法一样。
-
-现在，用户可以测试运行，整个系统的运行会和原来一样。ActWithStash 和Actor 拥有相同的基本架构，所以系统的运行会与原来没有什么区别。
-
-### 第4步 - 去掉act 方法
-
-在这一节，我们讨论怎样从ActWithStash中去掉act方法，以及怎样修改其他方法，使它与Akka更加契合. 这一环节会比较繁杂，所以我们建议最好一次只修改一个控制器。在Scala中，控制器的行为主要是在act方法的中定义。逻辑上来说，控制器是一个并发执行act方法的过程，执行完成后过程终止。在Akka中，控制器用一个全局消息处理器来依次处理它的的消息队列中的消息。这个消息处理器是一个receive函数返回的偏函数(partial function)，该偏函数被应用与每一条消息上。
-
-因为ActWithStash中Akka方法的行为依赖于移除的act方法，所以我们首先要做的是去掉act方法。然后，我们需要按照给定的规则修改scala.actors.Actor中每个方法的。
-
-#### 怎样去除act 方法
-
-在下面的列表中，我们给出了通用消息处理模式的修改规则。这个列表并不包含所有的模式，它只是覆盖了其中一些通用的模式。然而用户可以通过参考这些规则，通过扩展简单规则，将act方法移植到Akka。
-
-嵌套调用react/reactWithin需要注意：消息处理偏函数需要做结构扩展，使它更接近Akka模式。尽管这种修改会很复杂，但是它允许任何层次的嵌套被移植。下面有相关的例子。
-
-在复杂控制流中使用receive/receiveWithin需要注意：这个移植会比较复杂，因为它要求重构act方法。在消息处理偏函数中使用react 和 andThen可以使receive的调用模型化。下面是一些简单的例子。
-
-1. 如果在act方法中有一些代码在第一个包含react的loop之前被执行，那么这些代码应该被放在preStart方法中。
-
- def act() {
- //初始化的代码放在这里
- loop {
- react { ... }
- }
- }
-应该被替换
-
- override def preStart() {
- //初始化的代码放在这里
- }
-
- def act() {
- loop {
- react{ ... }
- }
- }
-其他的模式，如果在第一个react 之前有一些代码，也可以使用这个规则。
-
-2. 当act 的形式为：一个简单loop循环嵌套react，用下面的方法。
-
- def act() = {
- loop {
- react {
- // body
- }
- }
- }
-应该被替换
-
- def receive = {
- // body
- }
-
-3. 当act包含一个loopWhile 结构，用下面的方法。
-
- def act() = {
- loopWhile(c) {
- react {
- case x: Int =>
- // do task
- if (x == 42) {
- c = false
- }
- }
- }
- }
-应该被替换
-
- def receive = {
- case x: Int =>
- // do task
- if (x == 42) {
- context.stop(self)
- }
- }
-
-4. 当act包含嵌套的react，用下面的规则：
-
- def act() = {
- var c = true
- loopWhile(c) {
- react {
- case x: Int =>
- // do task
- if (x == 42) {
- c = false
- } else {
- react {
- case y: String =>
- // do nested task
- }
- }
- }
- }
- }
-应该被替换
-
- def receive = {
- case x: Int =>
- // do task
- if (x == 42) {
- context.stop(self)
- } else {
- context.become(({
- case y: String =>
- // do nested task
- }: Receive).andThen(x => {
- unstashAll()
- context.unbecome()
- }).orElse { case x => stash(x) })
- }
- }
-
-5. reactWithin方法使用下面的修改规则：
-
- loop {
- reactWithin(t) {
- case TIMEOUT => // timeout processing code
- case msg => // message processing code
- }
- }
-应该被替换
-
- import scala.concurrent.duration._
-
- context.setReceiveTimeout(t millisecond)
- def receive = {
- case ReceiveTimeout => // timeout processing code
- case msg => // message processing code
- }
-
-6. 在Akka中，异常处理用另一种方式完成。如果要模拟Scala控制器的方式，那就用下面的方法
-
- def act() = {
- loop {
- react {
- case msg =>
- // 可能会失败的代码
- }
- }
- }
-
- override def exceptionHandler = {
- case x: Exception => println("got exception")
- }
-应该被替换
-
- def receive = PFCatch({
- case msg =>
- // 可能会失败的代码
- }, { case x: Exception => println("got exception") })
- PFCatch 的定义
-
- class PFCatch(f: PartialFunction[Any, Unit],
- handler: PartialFunction[Exception, Unit])
- extends PartialFunction[Any, Unit] {
-
- def apply(x: Any) = {
- try {
- f(x)
- } catch {
- case e: Exception if handler.isDefinedAt(e) =>
- handler(e)
- }
- }
-
- def isDefinedAt(x: Any) = f.isDefinedAt(x)
- }
-
- object PFCatch {
- def apply(f: PartialFunction[Any, Unit],
- handler: PartialFunction[Exception, Unit]) =
- new PFCatch(f, handler)
- }
-
-PFCatch并不包含在AMK之中，所以它可以保留在移植代码中，AMK将会在下一版本中被删除。当整个移植完成后，错误处理也可以改由Akka来监管。
-
-#### 修改Actor的方法
-
-当我们移除了act方法以后，我们需要替换在Akka中不存在，但是有相似功能的方法。在下面的列表中，我们给出了两者的区别和替换方法：
-
-1. exit()/exit(reason) - 需要由 context.stop(self) 替换
-
-2. receiver - 需要由 self 替换
-
-3. reply(msg) - 需要由 sender ! msg 替换
-
-4. link(actor) - 在Akka中，控制器之间的链接一部分由[supervision](https://doc.akka.io/docs/akka/2.1.0/general/supervision.html#What_Supervision_Means)来完成，一部分由[actor monitoring](https://doc.akka.io/docs/akka/2.1.0/general/supervision.html#What_Lifecycle_Monitoring_Means)来完成。在AMK中，我们只支持监测方法。因此，这部分Scala功能可以被完整的移植。
-
-linking 和 watching 之间的区别在于：watching actor总是接受结束通知。然而，不像Scala的Exit消息包含结束的原因，Akka的watching 返回Terminated(a: ActorRef)消息，只包含ActorRef。获取结束原因的功能无法被移植。在Akka中，这一步骤可以在第4步之后，通过组织控制器的监管层级 [supervision hierarchy](https://doc.akka.io/docs/akka/2.1.0/general/supervision.html)来完成。
-
-如果watching actors收到的消息不撇陪结束消息，控制器会被终止并抛出DeathPactException异常。注意就算watching actors正常的结束，也会发生这种情况。在Scala中，linked actors只要一方不正常的终止，另一方就会以相同的原因终止。
-
-如果系统不能单独的用 watch actors来 移植，用户可以像原来那样用link和exit(reason)来使用。然而，因为act()重载了Exit消息，需要做如下的修改：
-
- case Exit(actor, reason) =>
- println("sorry about your " + reason)
- ...
-应该被替换
-
- case t @ Terminated(actorRef) =>
- println("sorry about your " + t.reason)
- ...
-注意：在Scala和Akka的actor之间有另一种细微的区别：在Scala， link/watch 到已经终止的控制器不会有任何影响。在Akka中，看管已经终止的控制器会导致发送终止消息。这会在系统移植的第5 步导致不可预料的结果。
-
-### 第5步 - Akka后端的移植
-
-到目前为止，用户代码已经做好了移植到Akka actors的准备工作。现在我们可以把Scala actors迁移到Akka actor上。为了完成这一目标，需要配置build，去掉scala-actors.jar 和 scala-actors-migration.jar，把 akka-actor.jar 和 typesafe-config.jar加进来。AMK只能在Akka actor 2.1下正常工作，Akka actor 2.1已经包含在分发包 [Scala distribution](https://www.scala-lang.org/downloads)中， 可以用这样的方法配置。
-
-经过这一步骤以后，因为包名的不同和API之间的细微差别，编译会失败。我们必须将每一个导入的actor从scala 修改为Akka。下列是部分需要修改的包名：
-
- scala.actors._ -> akka.actor._
- scala.actors.migration.ActWithStash -> akka.actor.ActorDSL._
- scala.actors.migration.pattern.ask -> akka.pattern.ask
- scala.actors.migration.Timeout -> akka.util.Timeout
-
-当然，ActWithStash 中方法的声明 def receive = 必须加上前缀override。
-
-在Scala actor中，stash 方法需要一个消息做为参数。例如：
-
- def receive = {
- ...
- case x => stash(x)
- }
-
-在Akka中，只有当前处理的消息可以被隐藏(stashed)。因此，上面的例子可以替换为：
-
- def receive = {
- ...
- case x => stash()
- }
-
-#### 添加Actor System
-
-Akka actor 组织在[Actor systems](https://doc.akka.io/docs/akka/2.1.0/general/actor-systems.html)系统中。每一个被实例化的actor必须属于某一个ActorSystem。因此，要添加一个ActorSystem 实例作为每个actor 实例调用的第一个参数。下面给出了例子。
-
-为了完成该转换，你需要有一个actor system 实例。例如：
-
- val system = ActorSystem("migration-system")
-
-然后，做如下转换：
-
- ActorDSL.actor(...) -> ActorDSL.actor(system)(...)
-
-如果对actor 的调用都使用同一个ActorSystem ，那么它可以作为隐式参数来传递。例如：
-
- ActorDSL.actor(...) ->
- import project.implicitActorSystem
- ActorDSL.actor(...)
-
-当所有的主线程和actors结束后，Scala程序会终止。迁移到Akka后，当所有的主线程结束，所有的actor systems关闭后，程序才会结束。Actor systems 需要在程序退出前明确的中止。这需要通过在Actor system中调用shutdown 方法来完成。
-
-#### 远程 Actors
-
-当代码迁移到Akka，远程actors就不再工作了。 registerActorFor 和 alive 方法需要被移除。 在Akka中，远程控制通过配置独立的完成。更多细节请参考[Akka remoting documentation](https://doc.akka.io/docs/akka/2.1.0/scala/remoting.html)。
-
-#### 样例和问题
-
-这篇文档中的所有程序片段可以在[Actors Migration test suite](https://github.com/scala/actors-migration/tree/master/src/test/)中找到，这些程序做为测试文件，前缀为actmig。
-
-这篇文档和Actor移植组件由 [Vojin Jovanovic](https://people.epfl.ch/vojin.jovanovic)和[Philipp Haller](https://lampwww.epfl.ch/~phaller/)编写。
-
-如果你发现任何问题或不完善的地方，请把它们报告给 [Scala Bugtracker](https://github.com/scala/actors-migration/issues)。
diff --git a/_zh-cn/overviews/core/actors.md b/_zh-cn/overviews/core/actors.md
deleted file mode 100644
index ab584a6a0e..0000000000
--- a/_zh-cn/overviews/core/actors.md
+++ /dev/null
@@ -1,306 +0,0 @@
----
-layout: singlepage-overview
-title: The Scala Actors API
-
-partof: actors
-
-language: zh-cn
----
-
-**Philipp Haller 和 Stephen Tu 著**
-
-## 简介
-
-本指南介绍了Scala 2.8和2.9中`scala.actors`包的API。这个包的内容因为逻辑上相通，所以放到了同一个类型的包内。这个trait在每个章节里面都会有所涉及。这章的重点在于这些traits所定义的各种方法在运行状态时的行为，由此来补充现有的Scala基础API。
-
-注意：在Scala 2.10版本中这个Actors库将是过时的，并且在未来Scala发布的版本中将会被移除。开发者应该使用在`akka.actor`包中[Akka](https://akka.io/) actors来替代它。想了解如何将代码从Scala actors迁移到Akka请参考[Actors 迁移指南](https://docs.scala-lang.org/overviews/core/actors-migration-guide.html)章节。
-
-## Actor trait：Reactor, ReplyReactor和Actor
-
-### Reactor trait
-
-Reactor 是所有`actor trait`的父级trait。扩展这个trait可以定义actor，其具有发送和接收消息的基本功能。
-
-Reactor的行为通过实现其act方法来定义。一旦调用start方法启动Reactor，这个act方法便会执行，并返回这个Reactor对象本身。start方法是具有等幂性的，也就是说，在一个已经启动了的actor对象上调用它（start方法）是没有作用的。
-
-Reactor trait 有一个Msg 的类型参数，这个参数指明这个actor所能接收的消息类型。
-
-调用Reactor的!方法来向接收者发送消息。用!发送消息是异步的，这样意味着不会等待消息被接收——它在发送消息后便立刻往下执行。例如：`a ! msg`表示向`a`发送`msg`。每个actor都有各自的信箱（mailbox）作为缓冲来存放接收到的消息，直至这些消息得到处理。
-
-Reactor trait中也定义了一个forward方法，这个方法继承于OutputChannel。它和!（感叹号，发送方法）有同样的作用。Reactor的SubTrait（子特性）——特别是`ReplyReactor trait`——覆写了此方法，使得它能够隐式地回复目标。（详细地看下面的介绍）
-
-一个Reactor用react方法来接收消息。react方法需要一个PartialFunction[Msg, Unit]类型的参数，当消息到达actor的邮箱之后，react方法根据这个参数来确定如何处理消息。在下面例子中，当前的actor等待接收一个“Hello”字符串，然后打印一句问候。
-
- react {
- case "Hello" => println("Hi there")
- }
-
-调用react没有返回值。因此，在接收到一条消息后，任何要执行的代码必须被包含在传递给react方法的偏函数（partial function）中。举个例子，通过嵌套两个react方法调用可以按顺序接收到两条消息：
-
- react {
- case Get(from) =>
- react {
- case Put(x) => from ! x
- }
- }
-
-Reactor trait 也提供了控制结构，简化了react方法的代码。
-
-### 终止和执行状态
-
-当Reactor的act方法完整执行后， Reactor则随即终止执行。Reactor也可以显式地使用exit方法来终止自身。exit方法的返回值类型为Nothing，因为它总是会抛出异常。这个异常仅在内部使用，并且不应该去捕捉这个异常。
-
-一个已终止的Reactor可以通过它的restart方法使它重新启动。对一个未终止的Reactor调用restart方法则会抛出`IllegalStateException`异常。重新启动一个已终止的actor则会使它的act方法重新运行。
-
-Reactor定义了一个getState方法，这个方法可以将actor当前的运行状态作为Actor.State枚举的一个成员返回。一个尚未运行的actor处于`Actor.State.New`状态。一个能够运行并且不在等待消息的actor处于`Actor.State.Runnable`状态。一个已挂起，并正在等待消息的actor处于`Actor.State.Suspended`状态。一个已终止的actor处于`Actor.State.Terminated`状态。
-
-### 异常处理
-
-exceptionHandler成员允许定义一个异常处理程序，其在Reactor的整个生命周期均可用。
-
- def exceptionHandler: PartialFunction[Exception, Unit]
-
-exceptionHandler返回一个偏函数，它用来处理其他没有被处理的异常。每当一个异常被传递到Reactor的act方法体之外时，这个成员函数就被应用到该异常，以允许这个actor在它结束前执行清理代码。注意：`exceptionHandler`的可见性为protected。
-
-用exceptionHandler来处理异常并使用控制结构对与react的编程是非常有效的。每当exceptionHandler返回的偏函数处理完一个异常后，程序会以当前的后续闭包（continuation closure）继续执行。
-
- loop {
- react {
- case Msg(data) =>
- if (cond) // 数据处理代码
- else throw new Exception("cannot process data")
- }
- }
-
-假设Reactor覆写了exceptionHandler，在处理完一个在react方法体内抛出的异常后，程序将会执行下一个循环迭代。
-
-### ReplyReactor trait
-
-`ReplyReactor trait`扩展了`Reactor[Any]`并且增加或覆写了以下方法：
-
-！方法被覆写以获得一个当前actor对象（发送方）的引用，并且，这个发送方引用和实际的消息一起被传递到接收actor的信箱（mail box）中。接收方通过其sender方法访问消息的发送方（见下文）。
-
-forward方法被覆写以获得一个引用，这个引用指向正在被处理的消息的发送方。引用和实际的消息一起作为当前消息的发送方传递。结果，forward方法允许代表不同于当前actor对象的actor对象转发消息。
-
-增加的sender方法返回正被处理的消息的发送方。考虑到一个消息可能已经被转发，发送方可能不会返回实际发送消息的actor对象。
-
-增加的reply方法向最后一个消息的发送方回复消息。reply方法也被用作回复一个同步消息发送或者一个使用future的消息发送（见下文）。
-
-增加的!?方法提供同步消息发送。调用!?方法会引起发送方actor对象等待，直到收到一个响应，然后返回这个响应。重载的变量有两个。这个双参数变量需要额外的超时参数（以毫秒计），并且，它的返回类型是Option[Any]而不是Any。如果发送方在指定的超时期间没有收到一个响应，!?方法返回None，否则它会返回由Some包裹的响应。
-
-增加的!!方法与同步消息发送的相似点在于，它们都允许从接收方传递一个响应。然而，它们返回Future实例，而不是阻塞发送中的actor对象直到接收响应。一旦Future对象可用，它可以被用来重新获得接收方的响应，还可以在不阻塞发送方的情况下，用于获知响应是否可用。重载的变量有两个。双参数变量需要额外的PartialFunction[Any,A]类型的参数。这个偏函数用于对接收方响应进行后处理。本质上，!!方法返回一个future对象，一旦响应被接收，这个future对象把偏函数应用于响应。future对象的结果就是后处理的结果。
-
-增加的reactWithin方法允许在一段给定的时间段内接收消息。相对于react方法，这个方法需要一个额外的msec参数，用来指示在这个时间段（以毫秒计）直到匹配指定的TIMEOUT模式为止（TIMEOUT是包scala.actors中的用例对象（case object））。例如：
-
-reactWithin(2000) { case Answer(text) => // process text case TIMEOUT => println("no answer within 2 seconds") }
-
-reactWithin方法也允许以非阻塞方式访问信箱。当指定一个0毫秒的时间段时，首先会扫描信箱以找到一个匹配消息。如果在第一次扫描后没有匹配的消息，这个TIMEOUT模式将会匹配。例如，这使得接收某些消息会比其他消息有较高的优先级：
-
-reactWithin(0) { case HighPriorityMsg => // ... case TIMEOUT => react { case LowPriorityMsg => // ... } }
-
-在上述例子中，即使在信箱里有一个先到达的低优先级的消息，actor对象也会首先处理下一个高优先级的消息。actor对象只有在信箱里没有高优先级消息时才会首先处理一个低优先级的消息。
-
-另外，ReplyReactor 增加了`Actor.State.TimedSuspended`执行状态。一个使用`reactWithin`方法等待接收消息而挂起的actor对象，处在` Actor.State.TimedSuspended `状态。
-
-### Actor trait
-
-Actor trait扩展了`ReplyReactor`并增加或覆写了以下成员：
-
-增加的receive方法的行为类似react方法，但它可以返回一个结果。这可以在它的类型上反映——它的结果是多态的：def receive[R](f: PartialFunction[Any, R]): R。然而，因为actor对象挂起并等待消息时，receive方法会阻塞底层线程（underlying thread），使用receive方法使actor对象变得更加重量级。直到receive方法的调用返回，阻塞的线程将不能够执行其他actor对象。
-
-增加的link和unlink方法允许一个actor对象将自身链接到另一个actor对象，或将自身从另一个actor对象断开链接。链接可以用来监控或对另一个actor对象的终止做出反应。特别要注意的是，正如在Actor trait的API文档中的解释，链接影响调用exit方法的行为。
-
-trapExit成员允许对链接的actor对象的终止做出反应而无关其退出的原因（即，无关是否正常退出）。如果一个actor对象的trapExit成员被设置为true，则这个actor对象会因链接的actor对象而永远不会终止。相反，每当其中一个链接的actor对象个终止了，它将会收到类型为Exit的消息。这个Exit case class 有两个成员：from指终止的actor对象；reason指退出原因。
-
-### 终止和执行状态
-
-当终止一个actor对象的执行时，可以通过调用以下exit方法的变体，显式地设置退出原因：
-
- def exit(reason: AnyRef): Nothing
-当一个actor对象以符号'normal以外的原因退出，会向所有链接到它的atocr对象传递其退出原因。如果一个actor对象由于一个未捕获异常终止，它的退出原因则为一个UncaughtException case class的实例。
-
-Actor trait增加了两个新的执行状态。使用receive方法并正在等待接收消息的actor处在`Actor.State.Blocked`状态。使用receiveWithin方法并正在等待接收消息的actor处在`Actor.State.TimedBlocked`状态。
-
-## 控制结构
-
-Reactor trait定义了控制结构，它简化了无返回的react操作的编程。一般来说，一个react方法调用并不返回。如果actor对象随后应当执行代码，那么，或者显式传递actor对象的后续代码给react方法，或者可以使用下述控制结构，达到隐藏这些延续代码的目的。
-
-最基础的控制结构是andThen，它允许注册一个闭包。一旦actor对象的所有其他代码执行完毕，闭包就会被执行。
-
- actor {
- {
- react {
- case "hello" => // 处理 "hello"
- }: Unit
- } andThen {
- println("hi there")
- }
- }
-
-例如，上述actor实例在它处理了“hello”消息之后，打印一句问候。虽然调用react方法不会返回，我们仍然可以使用andThen来注册这段输出问候的代码（作为actor的延续）。
-
-注意：在react方法的调用（: Unit）中存在一种类型归属。总而言之，既然表达式的结果经常可以被忽略，react方法的结果就可以合法地作为Unit类型来处理。andThen方法无法成为Nothing类型（react方法的结果类型）的一个成员，所以在这里有必要这样做。把react方法的结果类型当作Unit，允许实现一个隐式转换的应用，这个隐式转换使得andThen成员可用。
-
-API还提供一些额外的控制结构：
-
-loop { ... }。无限循环，在每一次迭代中，执行括号中的代码。调用循环体内的react方法，actor对象同样会对消息做出反应。而后，继续执行这个循环的下次迭代。
-
-loopWhile (c) { ... }。当条件c返回true，执行括号中的代码。调用循环体中的react方法和使用loop时的效果一样。
-
-continue。继续执行当前的接下来的后续闭包（continuation closure）。在loop或loopWhile循环体内调用continue方法将会使actor对象结束当前的迭代并继续执行下次迭代。如果使用andThen注册了当前的后续代码，这个闭包会作为第二个参数传给andThen，并以此继续执行。
-
-控制结构可以在Reactor对象的act方法中，以及在act方法（传递地）调用的方法中任意处使用。对于用actor{...}这样的缩略形式创建的actor，控制结构可以从Actor对象导入。
-
-### Future
-
-ReplyReactor和Actor trait支持发送带有结果的消息（!!方法），其立即返回一个future实例。一个future即Future trait的一个实例，即可以用来重新获取一个send-with-future消息的响应的句柄。
-
-一个send-with-future消息的发送方可以通过应用future来等待future的响应。例如，使用val fut = a !! msg 语句发送消息，允许发送方等待future的结果。如：val res = fut()。
-
-另外，一个Future可以在不阻塞的情况下，通过isSet方法来查询并获知其结果是否可用。
-
-send-with-future的消息并不是获得future的唯一的方法。future也可以通过future方法计算而得。下述例子中，计算体会被并行地启动运行，并返回一个future实例作为其结果：
-
- val fut = Future { body }
- // ...
- fut() // 等待future
-
-能够通过基于actor的标准接收操作（例如receive方法等）来取回future的结果，使得future实例在actor上下文中变得特殊。此外，也能够通过使用基于事件的操作（react方法和ractWithin方法）。这使得一个actor实例在等待一个future实例结果时不用阻塞它的底层线程。
-
-通过future的inputChannel，使得基于actor的接收操作方法可用。对于一个类型为`Future[T]`的future对象而言，它的类型是`InputChannel[T]`。例如：
-
- val fut = a !! msg
- // ...
- fut.inputChannel.react {
- case Response => // ...
- }
-
-## Channel（通道）
-
-channnel可以用来对发送到同一actor的不同类型消息的处理进行简化。channel的层级被分为OutputChannel和InputChannel。
-
-OutputChannel可用于发送消息。OutputChannel的out方法支持以下操作。
-
-out ! msg。异步地向out方法发送msg。当msg直接发送给一个actor，一个发送中的actor的引用会被传递。
-
-out forward msg。异步地转发msg给out方法。当msg被直接转发给一个actor，发送中的actor会被确定。
-
-out.receiver。返回唯一的actor，其接收发送到out channel（通道）的消息。
-
-out.send(msg, from)。异步地发送msg到out，并提供from作为消息的发送方。
-
-注意：OutputChannel trait有一个类型参数，其指定了可以被发送到channel（通道）的消息类型（使用!、forward和send）。这个类型参数是逆变的：
-
- trait OutputChannel[-Msg]
-
-Actor能够从InputChannel接收消息。就像OutputChannel，InputChannel trait也有一个类型参数，用于指定可以从channel（通道）接收的消息类型。这个类型参数是协变的：
-
- trait InputChannel[+Msg]
-
-An` InputChannel[Msg] `in支持下列操作。
-
-in.receive { case Pat1 => ... ; case Patn => ... }（以及类似的 in.receiveWithin）。从in接收一个消息。在一个输入channel（通道）上调用receive方法和actor的标准receive操作具有相同的语义。唯一的区别是，作为参数被传递的偏函数具有PartialFunction[Msg, R]类型，此处R是receive方法的返回类型。
-
-in.react { case Pat1 => ... ; case Patn => ... }（以及类似的in.reactWithin）通过基于事件的react操作，从in方法接收一个消息。就像actor的react方法，返回类型是Nothing。这意味着此方法的调用不会返回。就像之前的receive操作，作为参数传递的偏函数有一个更具体的类型：PartialFunction[Msg, Unit]
-
-### 创建和共享channel
-
-channel通过使用具体的Channel类创建。它同时扩展了InputChannel和OutputChannel。使channel在多个actor的作用域（Scope）中可见，或者将其在消息中发送，都可以实现channel的共享。
-
-下面的例子阐述了基于作用域（scope）的共享。
-
- actor {
- var out: OutputChannel[String] = null
- val child = actor {
- react {
- case "go" => out ! "hello"
- }
- }
- val channel = new Channel[String]
- out = channel
- child ! "go"
- channel.receive {
- case msg => println(msg.length)
- }
- }
-
-运行这个例子将输出字符串“5”到控制台。注意：子actor对out（一个OutputChannel[String]）具有唯一的访问权。而用于接收消息的channel的引用则被隐藏了。然而，必须要注意的是，在子actor向输出channel发送消息之前，确保输出channel被初始化到一个具体的channel。通过使用“go”消息来完成消息发送。当使用channel.receive来从channel接收消息时，因为消息是String类型的，可以使用它提供的length成员。
-
-另一种共享channel的可行的方法是在消息中发送它们。下面的例子对此作了阐述。
-
- case class ReplyTo(out: OutputChannel[String])
-
- val child = actor {
- react {
- case ReplyTo(out) => out ! "hello"
- }
- }
-
- actor {
- val channel = new Channel[String]
- child ! ReplyTo(channel)
- channel.receive {
- case msg => println(msg.length)
- }
- }
-
-ReplyTo case class是一个消息类型，用于分派一个引用到OutputChannel[String]。当子actor接收一个ReplyTo消息时，它向它的输出channel发送一个字符串。第二个actor则像以前一样接收那个channel上的消息。
-
-## Scheduler
-
-scheduler用于执行一个Reactor实例（或子类型的一个实例）。Reactor trait引入了scheduler成员，其返回常用于执行Reactor实例的scheduler。
-
- def scheduler: IScheduler
-
-运行时系统通过使用在IScheduler trait中定义的execute方法之一，向scheduler提交任务来执行actor。只有在完整实现一个新的scheduler时（但没有必要），此trait的大多数其他方法才是相关的。
-
-默认的scheduler常用于执行Reactor实例，而当所有的actor完成其执行时，Actor则会检测环境。当这发生时，scheduler把它自己关闭（终止scheduler使用的任何线程）。然而，一些scheduler，比如SingleThreadedScheduler（位于scheduler包）必须要通过调用它们的shutdown方法显式地关闭。
-
-创建自定义scheduler的最简单方法是通过扩展SchedulerAdapter，实现下面的抽象成员：
-
- def execute(fun: => Unit): Unit
-
-典型情况下，一个具体的实现将会使用线程池来执行它的按名参数fun。
-
-## 远程Actor
-
-这一段描述了远程actor的API。它的主要接口是scala.actors.remote包中的RemoteActor对象。这个对象提供各种方法来创建和连接到远程actor实例。在下面的代码段中我们假设所有的RemoteActor成员都已被导入，所使用的完整导入列表如下：
-
- import scala.actors._
- import scala.actors.Actor._
- import scala.actors.remote._
- import scala.actors.remote.RemoteActor._
-
-### 启动远程Actor
-
-远程actor由一个Symbol唯一标记。在这个远程Actor所执行JVM上，这个符号对于JVM实例是唯一的。由名称'myActor标记的远程actor可按如下方法创建。
-
- class MyActor extends Actor {
- def act() {
- alive(9000)
- register('myActor, self)
- // ...
- }
- }
-
-记住：一个名字一次只能标记到一个单独的（存活的）actor。例如，想要标记一个actorA为'myActor，然后标记另一个actorB为'myActor。这种情况下，必须等待A终止。这个要求适用于所有的端口，因此简单地将B标记到不同的端口来作为A是不能满足要求的。
-
-### 连接到远程Actor
-
-连接到一个远程actor也同样简单。为了获得一个远程Actor的远程引用（运行于机器名为myMachine，端口为8000，名称为'anActor），可按下述方式使用select方法：
-
- val myRemoteActor = select(Node("myMachine", 8000), 'anActor)
-
-从select函数返回的actor具有类型AbstractActor，这个类型本质上提供了和通常actor相同的接口，因此支持通常的消息发送操作：
-
- myRemoteActor ! "Hello!"
- receive {
- case response => println("Response: " + response)
- }
- myRemoteActor !? "What is the meaning of life?" match {
- case 42 => println("Success")
- case oops => println("Failed: " + oops)
- }
- val future = myRemoteActor !! "What is the last digit of PI?"
-
-记住：select方法是惰性的，它不实际初始化任何网络连接。仅当必要时（例如，调用!时），它会单纯地创建一个新的，准备好初始化新网络连接的AbstractActor实例。
diff --git a/_zh-cn/overviews/core/futures.md b/_zh-cn/overviews/core/futures.md
index 823e72a3cd..97f64ed7aa 100644
--- a/_zh-cn/overviews/core/futures.md
+++ b/_zh-cn/overviews/core/futures.md
@@ -11,491 +11,1254 @@ language: zh-cn
## 简介
-Future提供了一套高效便捷的非阻塞并行操作管理方案。其基本思想很简单，所谓Future，指的是一类占位符对象，用于指代某些尚未完成的计算的结果。一般来说，由Future指代的计算都是并行执行的，计算完毕后可另行获取相关计算结果。以这种方式组织并行任务，便可以写出高效、异步、非阻塞的并行代码。
+Future提供了一套高效便捷的非阻塞并行操作管理方案。其基本思想很简单，所谓 [`Future`](https://www.scala-lang.org/api/current/scala/concurrent/Future.html)，指的是一类占位符对象，用于指代某些尚未完成的计算的结果。一般来说，由Future指代的计算都是并行执行的，计算完毕后可另行获取相关计算结果。以这种方式组织并行任务，便可以写出高效、异步、非阻塞的并行代码。
-默认情况下，future和promise并不采用一般的阻塞操作，而是依赖回调进行非阻塞操作。为了在语法和概念层面更加简明扼要地使用这些回调，Scala还提供了flatMap、foreach和filter等算子，使得我们能够以非阻塞的方式对future进行组合。当然，future仍然支持阻塞操作——必要时，可以阻塞等待future（不过并不鼓励这样做）。
+默认情况下，future和promise并不采用一般的阻塞操作，而是依赖回调进行非阻塞操作。为了在语法和概念层面更加简明扼要地使用这些回调，Scala还提供了 `flatMap`、`foreach` 和 `filter` 等算子，使得我们能够以非阻塞的方式对future进行组合。
+当然，future仍然支持阻塞操作——必要时，可以阻塞等待future（不过并不鼓励这样做）。
+
+
+
+典型的 future 像这样：
+
+{% tabs futures-00 %}
+{% tab 'Scala 2 and 3' for=futures-00 %}
+
+```scala
+val inverseFuture: Future[Matrix] = Future {
+ fatMatrix.inverse() // non-blocking long lasting computation
+}(executionContext)
+```
+
+{% endtab %}
+{% endtabs %}
+
+或者更习惯的用法：
+
+{% tabs futures-01 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-01 %}
+
+```scala
+implicit val ec: ExecutionContext = ...
+val inverseFuture : Future[Matrix] = Future {
+ fatMatrix.inverse()
+} // ec is implicitly passed
+```
+
+{% endtab %}
+
+{% tab 'Scala 3' for=futures-01 %}
+
+```scala
+given ExecutionContext = ...
+val inverseFuture : Future[Matrix] = Future {
+ fatMatrix.inverse()
+} // execution context is implicitly passed
+```
+
+{% endtab %}
+{% endtabs %}
+
+这两个代码片段都将 `fatMatrix.inverse()` 的执行委托给 `ExecutionContext`，并在 `inverseFuture` 中体现计算结果。
+
+## 执行上下文
+
+Future 和 Promises 围绕 [`ExecutionContext`s](https://www.scala-lang.org/api/current/scala/concurrent/ExecutionContext.html) 展开，负责执行计算。
+
+`ExecutionContext` 类似于 [Executor](https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executor.html)：
+它可以在新线程、线程池或当前线程中自由地执行计算（尽管不鼓励在当前线程中执行计算 -- 更多内容见下文）。
+
+`scala.concurrent` 包是开箱即用的，它带有 `ExecutionContext` 实现，一个全局静态线程池。
+它也可以将 `Exector` 转换为 `ExecutionContext`。
+最后，用户可以自由扩展 `ExecutionContext` trait来实现自己的执行上下文，但只有极少数情况下需要这么做。
+
+### 全局执行上下文
+
+`ExecutionContext.global` 是由 [ForkJoinPool](https://docs.oracle.com/javase/tutorial/essential/concurrency/forkjoin.html) 支持的 `ExecutionContext`。
+它应该满足大部分情况，但有几点需要注意。
+`ForkJoinPool` 管理有限数量的线程（线程的最大数量由 *parallelism level* 指定）。
+仅当每个阻塞调用都包装在 `blocking` 调用中时（更多内容见下文），并发阻塞计算的数量才能超过并行度级别。
+否则，全局执行上下文中的线程池会有饥饿死锁风险，致使任何计算无法继续进行。
+缺省情况下，`ExecutionContext.global` 将其底层ForkJoin连接池的并行级别设置为可用处理器的数量([Runtime.availableProcessors](https://docs.oracle.com/javase/7/docs/api/java/lang/Runtime.html#availableProcessors%28%29))。
+通过设置以下一个（或多个） VM 属性，来重载这个设置：
+
+ * scala.concurrent.context.minThreads - 缺省为 `Runtime.availableProcessors`
+ * scala.concurrent.context.numThreads - 可以是一个数字，或者是 “xN” 这样形式中的乘数（N）；缺省为 `Runtime.availableProcessors`
+ * scala.concurrent.context.maxThreads - 缺省为 `Runtime.availableProcessors`
+
+只要并行度的数值在 `[minThreads; maxThreads]` 范围内，它就可以给 `numThreads` 赋值。
+
+如上所述，在存在阻塞计算的情况下，`ForkJoinPool` 可以将线程数增加到超过 `parallelismLevel`。
+如 `ForkJoinPool` API 中所述，这只有在明确通知 `ForkJoinPool` 时才有可能：
+
+{% tabs futures-02 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-02 %}
+
+```scala
+import scala.concurrent.{ Future, ExecutionContext }
+import scala.concurrent.forkjoin._
+
+// the following is equivalent to `implicit val ec = ExecutionContext.global`
+import ExecutionContext.Implicits.global
+
+Future {
+ ForkJoinPool.managedBlock(
+ new ManagedBlocker {
+ var done = false
+
+ def block(): Boolean = {
+ try {
+ myLock.lock()
+ // ...
+ } finally {
+ done = true
+ }
+ true
+ }
+
+ def isReleasable: Boolean = done
+ }
+ )
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-02 %}
+
+```scala
+import scala.concurrent.{ Future, ExecutionContext }
+import scala.concurrent.forkjoin.*
+
+// the following is equivalent to `given ExecutionContext = ExecutionContext.global`
+import ExecutionContext.Implicits.global
+
+Future {
+ ForkJoinPool.managedBlock(
+ new ManagedBlocker {
+ var done = false
+
+ def block(): Boolean =
+ try
+ myLock.lock()
+ // ...
+ finally
+ done = true
+ true
+
+ def isReleasable: Boolean = done
+ }
+ )
+}
+```
+{% endtab %}
+{% endtabs %}
+
+幸运的是，并发包为这提供了便捷的方法：
+
+{% tabs blocking %}
+{% tab 'Scala 2 and 3' for=blocking %}
+
+```scala
+import scala.concurrent.Future
+import scala.concurrent.blocking
+
+Future {
+ blocking {
+ myLock.lock()
+ // ...
+ }
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+注意 `blocking` 是一个通用结构，它将会在[下面](#future-内的阻塞)作深入探讨。
+
+最后你必须记住 `ForkJoinPool` 不是设计用来长连接阻塞操作。
+即使收到 `blocking` 通知，池也可能无法像预期的那样生成新工作，而创建新工作线程时，它们的数量也可能多达 32767。
+为了给您有个概念，以下代码将使用 32000 个线程：
+
+{% tabs futures-03 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-03 %}
+
+```scala
+implicit val ec = ExecutionContext.global
+
+for (i <- 1 to 32000) {
+ Future {
+ blocking {
+ Thread.sleep(999999)
+ }
+ }
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-03 %}
+
+```scala
+given ExecutionContext = ExecutionContext.global
+
+for i <- 1 to 32000 do
+ Future {
+ blocking {
+ Thread.sleep(999999)
+ }
+ }
+```
+
+{% endtab %}
+{% endtabs %}
+
+如果您需要包装持久的阻塞操作，我们建议使用专用的 `ExecutionContext`，例如通过包装Java 的 `Executor`。
+
+### 适配 Java Executor
+
+使用 `ExecutionContext.fromExecutor` 方法，你可以把 `Executor` 包装进 `ExecutionContext`。
+例如：
+
+{% tabs executor class=tabs-scala-version %}
+{% tab 'Scala 2' for=executor %}
+
+```scala
+ExecutionContext.fromExecutor(new ThreadPoolExecutor( /* your configuration */ ))
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=executor %}
+
+```scala
+ExecutionContext.fromExecutor(ThreadPoolExecutor( /* your configuration */ ))
+```
+
+{% endtab %}
+{% endtabs %}
+
+### 同步执行上下文
+
+也许试图得到一个在当前线程中运行计算的 `ExecutionContext`：
+
+{% tabs bad-example %}
+{% tab 'Scala 2 and 3' for=bad-example %}
+
+```scala
+val currentThreadExecutionContext = ExecutionContext.fromExecutor(
+ new Executor {
+ // Do not do this!
+ def execute(runnable: Runnable) = runnable.run()
+ })
+```
+
+{% endtab %}
+{% endtabs %}
+
+应该避免这种情况，因为它会在执行 future 时引入不确定性。
+
+{% tabs bad-example-2 %}
+{% tab 'Scala 2 and 3' for=bad-example-2 %}
+
+```scala
+Future {
+ doSomething
+}(ExecutionContext.global).map {
+ doSomethingElse
+}(currentThreadExecutionContext)
+```
+
+{% endtab %}
+{% endtabs %}
+
+`doSomethingElse` 调用，可能在 `doSomething` 的线程中执行或者在主线程中执行，这样可以是同步的或者是异步的。
+正如[这里](https://blog.ometer.com/2011/07/24/callbacks-synchronous-and-asynchronous/)解释的，一个调用不能两者都是。
## Future
所谓Future，是一种用于指代某个尚未就绪的值的对象。而这个值，往往是某个计算过程的结果：
-- 若该计算过程尚未完成，我们就说该Future未就位；
-- 若该计算过程正常结束，或中途抛出异常，我们就说该Future已就位。
+1. 若该计算过程尚未完成，我们就说该Future **未就位**；
+2. 若该计算过程正常结束，或中途抛出异常，我们就说该Future **已就位**。
Future的就位分为两种情况：
-- 当Future带着某个值就位时，我们就说该Future携带计算结果成功就位。
-- 当Future因对应计算过程抛出异常而就绪，我们就说这个Future因该异常而失败。
+1. 当 `Future` 带着某个值就位时，我们就说该 future 携带计算结果**成功就位**。
+2. 当 `Future` 因对应计算过程抛出异常而就绪，我们就说这个 future因该异常而**失败**。
-Future的一个重要属性在于它只能被赋值一次。一旦给定了某个值或某个异常，future对象就变成了不可变对象——无法再被改写。
+`Future` 的一个重要属性在于它只能被赋值一次。一旦给定了某个值或某个异常，`Future` 对象就变成了不可变对象——无法再被改写。
-创建future对象最简单的方法是调用future方法，该future方法启用异步(asynchronous)计算并返回保存有计算结果的futrue，一旦该future对象计算完成，其结果就变的可用。
+创建future对象最简单的方法是调用 `Future.apply` 方法，该future方法启用异步(asynchronous)计算并返回保存有计算结果的futrue，一旦该future对象计算完成，其结果就变的可用。
-注意_Future[T]_ 是表示future对象的类型，而future是方法，该方法创建和调度一个异步计算，并返回随着计算结果而完成的future对象。
+注意 _Future[T]_ 是表示future对象的类型，而 `Future.apply` 是方法，该方法创建和调度一个异步计算，并返回随着计算结果而完成的future对象。
这最好通过一个例子予以说明。
假设我们使用某些流行的社交网络的假定API获取某个用户的朋友列表，我们将打开一个新对话(session)，然后发送一个请求来获取某个特定用户的好友列表。
- import scala.concurrent._
- import ExecutionContext.Implicits.global
+{% tabs futures-04 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-04 %}
- val session = socialNetwork.createSessionFor("user", credentials)
- val f: Future[List[Friend]] = Future {
- session.getFriends()
- }
+```scala
+import scala.concurrent._
+import ExecutionContext.Implicits.global
-以上，首先导入scala.concurrent 包使得Future类型和future构造函数可见。我们将马上解释第二个导入。
+val session = socialNetwork.createSessionFor("user", credentials)
+val f: Future[List[Friend]] = Future {
+ session.getFriends()
+}
+```
-然后我们初始化一个session变量来用作向服务器发送请求，用一个假想的 createSessionFor 方法来返回一个List[Friend]。为了获得朋友列表，我们必须通过网络发送一个请求，这个请求可能耗时很长。这能从调用getFriends方法得到解释。为了更好的利用CPU，响应到达前不应该阻塞(block)程序的其他部分执行，于是在计算中使用异步。future方法就是这样做的，它并行地执行指定的计算块，在这个例子中是向服务器发送请求和等待响应。
+{% endtab %}
+{% tab 'Scala 3' for=futures-04 %}
-一旦服务器响应，future f 中的好友列表将变得可用。
+```scala
+import scala.concurrent.*
+import ExecutionContext.Implicits.global
-未成功的尝试可能会导致一个异常(exception)。在下面的例子中，session的值未被正确的初始化，于是在future的计算中将抛出NullPointerException，future f 不会圆满完成，而是以此异常失败。
+val session = socialNetwork.createSessionFor("user", credentials)
+val f: Future[List[Friend]] = Future {
+ session.getFriends()
+}
+```
- val session = null
- val f: Future[List[Friend]] = Future {
- session.getFriends
- }
+{% endtab %}
+{% endtabs %}
-`import ExecutionContext.Implicits.global` 上面的线条导入默认的全局执行上下文(global execution context)，执行上下文执行执行提交给他们的任务，也可把执行上下文看作线程池，这对于future方法来说是必不可少的，因为这可以处理异步计算如何及何时被执行。我们可以定义自己的执行上下文，并在future上使用它，但是现在只需要知道你能够通过上面的语句导入默认执行上下文就足够了。
+以上，首先导入 `scala.concurrent` 包使得 `Future` 类型可见。
+我们将马上解释第二个导入。
-我们的例子是基于一个假定的社交网络API，此API的计算包含发送网络请求和等待响应。提供一个涉及到你能试着立即使用的异步计算的例子是公平的。假设你有一个文本文件，你想找出一个特定的关键字第一次出现的位置。当磁盘正在检索此文件内容时，这种计算可能会陷入阻塞，因此并行的执行该操作和程序的其他部分是合理的(make sense)。
+然后我们用一个假想的 `createSessionFor` 方法去初始化一个session变量，该变量用作向服务器发送请求。
+为了获得朋友列表，我们必须通过网络发送一个请求，这个请求可能耗时很长。
+这能从调用 `getFriends` 方法得到解释，该方法返回 `List[Friend]`。
+为了更好的利用CPU，响应到达前不应该阻塞(block)程序的其他部分执行，于是在计算中使用异步。`Future.apply` 方法就是这样做的，它并行地执行指定的计算块，在这个例子中是向服务器发送请求和等待响应。
- val firstOccurrence: Future[Int] = Future {
- val source = scala.io.Source.fromFile("myText.txt")
- source.toSeq.indexOfSlice("myKeyword")
- }
+一旦服务器响应，future `f` 中的好友列表将变得可用。
+
+未成功的尝试可能会导致一个异常(exception)。在下面的例子中，`session` 的值未被正确的初始化，于是在 `Future` 阻塞中的计算将抛出 `NullPointerException`。
+该future `f` 不会圆满完成，而是以此异常失败：
+
+{% tabs futures-04b %}
+{% tab 'Scala 2 and 3' for=futures-04b %}
+
+```scala
+val session = null
+val f: Future[List[Friend]] = Future {
+ session.getFriends
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+上面 `import ExecutionContext.Implicits.global` 这行，导入默认的全局执行上下文(global execution context)。
+执行上下文执行提交给他们的任务，也可把执行上下文看作线程池。
+这对于 `Future.apply` 方法来说是必不可少的，因为这可以处理异步计算如何及何时被执行。
+可以定义自己的执行上下文，并在 `Future` 上使用它，但是现在只需要知道你能够通过上面的语句导入默认执行上下文就足够了。
+
+我们的例子是基于一个假定的社交网络 API，此 API 的计算包含发送网络请求和等待响应。
+提供一个涉及到你能试着立即使用的异步计算的例子是公平的。假设你有一个文本文件，你想找出一个特定的关键字第一次出现的位置。
+当磁盘正在检索此文件内容时，这种计算可能会陷入阻塞，因此并行的执行该操作和程序的其他部分是合理的(make sense)。
+
+{% tabs futures-04c %}
+{% tab 'Scala 2 and 3' for=futures-04c %}
+
+```scala
+val firstOccurrence: Future[Int] = Future {
+ val source = scala.io.Source.fromFile("myText.txt")
+ source.toSeq.indexOfSlice("myKeyword")
+}
+```
+
+{% endtab %}
+{% endtabs %}
### Callbacks(回调函数)
-现在我们知道如何开始一个异步计算来创建一个新的future值，但是我们没有展示一旦此结果变得可用后如何来使用，以便我们能够用它来做一些有用的事。我们经常对计算结果感兴趣而不仅仅是它的副作用。
+现在我们知道如何开始一个异步计算来创建一个新的future值，但是我们没有展示一旦此结果变得可用后如何来使用，以便我们能够用它来做一些有用的事。
+我们经常对计算结果感兴趣而不仅仅是它的副作用。
-在许多future的实现中，一旦future的client对future的结果感兴趣，它不得不阻塞它自己的计算直到future完成——然后才能使用future的值继续它自己的计算。虽然这在Scala的Future API（在后面会展示）中是允许的，但是从性能的角度来看更好的办法是一种完全非阻塞的方法，即在future中注册一个回调，future完成后这个回调称为异步回调。如果当注册回调时future已经完成，则回调可能是异步执行的，或在相同的线程中循序执行。
+在许多future的实现中，一旦future的client对future的结果感兴趣，它不得不阻塞它自己的计算直到future完成——然后才能使用future的值继续它自己的计算。
+虽然这在Scala的Future API（在后面会展示）中是允许的，但是从性能的角度来看更好的办法是一种完全非阻塞的方法，即在future中注册一个回调。
+future 完成后这个回调称为异步回调。如果当注册回调时 future 已经完成，则回调可能是异步执行的，或在相同的线程中循序执行。
-注册回调最通常的形式是使用OnComplete方法，即创建一个`Try[T] => U`类型的回调函数。如果future成功完成，回调则会应用到Success[T]类型的值中，否则应用到` Failure[T] `类型的值中。
+注册回调最通常的形式是使用 `OnComplete` 方法，即创建一个``Try[T] => U` 类型的回调函数。
+如果future成功完成，回调则会应用到 `Success[T]` 类型的值中，否则应用到 `Failure[T]` 类型的值中。
- `Try[T]` 和`Option[T]`或 `Either[T, S]`相似，因为它是一个可能持有某种类型值的单子。然而，它是特意设计来保持一个值或某个可抛出(throwable)对象。`Option[T]` 既可以是一个值（如：`Some[T]`）也可以是完全无值（如：`None`），如果`Try[T]`获得一个值则它为`Success[T]` ，否则为`Failure[T]`的异常。 `Failure[T]` 获得更多的关于为什么这儿没值的信息，而不仅仅是None。同时也可以把`Try[T]`看作一种特殊版本的`Either[Throwable, T]`，专门用于左值为可抛出类型(Throwable)的情形。
+ `Try[T]` 和`Option[T]`或 `Either[T, S]`相似，因为它是一个可能持有某种类型值的单子。
+ 然而，它是特意设计来保持一个值或某个可抛出(throwable)对象。
+ `Option[T]` 既可以是一个值（如：`Some[T]`）也可以是完全无值（如：`None`），如果 `Try[T]` 获得一个值则它为 `Success[T]`，否则为 `Failure[T]` 的异常。`Failure[T]` 获得更多的关于为什么这儿没值的信息，而不仅仅是 `None`。
+ 同时也可以把 `Try[T]` 看作一种特殊版本的 `Either[Throwable, T]`，专门用于左值为可抛出类型(Throwable)的情形。
-回到我们的社交网络的例子，假设我们想要获取我们最近的帖子并显示在屏幕上，我们通过调用getRecentPosts方法获得一个返回值List[String]——一个近期帖子的列表文本：
+回到我们的社交网络的例子，假设我们想要获取我们最近的帖子并显示在屏幕上，我们通过调用 `getRecentPosts` 方法获得一个返回值 `List[String]` -- 一个近期帖子的列表文本：
- val f: Future[List[String]] = Future {
- session.getRecentPosts
- }
+{% tabs futures-05 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-05 %}
- f onComplete {
- case Success(posts) => for (post <- posts) println(post)
- case Failure(t) => println("An error has occured: " + t.getMessage)
- }
+```scala
+import scala.util.{Success, Failure}
+val f: Future[List[String]] = Future {
+ session.getRecentPosts
+}
-onComplete方法一般在某种意义上它允许客户处理future计算出的成功或失败的结果。对于仅仅处理成功的结果，onSuccess 回调使用如下（该回调以一个偏函数(partial function)为参数）：
+f.onComplete {
+ case Success(posts) => for (post <- posts) println(post)
+ case Failure(t) => println("An error has occured: " + t.getMessage)
+}
+```
- val f: Future[List[String]] = Future {
- session.getRecentPosts
- }
+{% endtab %}
+{% tab 'Scala 3' for=futures-05 %}
- f onSuccess {
- case posts => for (post <- posts) println(post)
- }
+```scala
+import scala.util.{Success, Failure}
-对于处理失败结果，onFailure回调使用如下：
+val f: Future[List[String]] = Future {
+ session.getRecentPosts()
+}
- val f: Future[List[String]] = Future {
- session.getRecentPosts
- }
+f.onComplete {
+ case Success(posts) => for post <- posts do println(post)
+ case Failure(t) => println("An error has occurred: " + t.getMessage)
+}
+```
- f onFailure {
- case t => println("An error has occured: " + t.getMessage)
- }
+{% endtab %}
+{% endtabs %}
- f onSuccess {
- case posts => for (post <- posts) println(post)
- }
+`onComplete` 方法一般在某种意义上它允许客户处理future计算出的成功或失败的结果。对于仅仅处理成功的结果，可以使用 `foreach` 回调：
-如果future失败，即future抛出异常，则执行onFailure回调。
+{% tabs futures-06 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-06 %}
-因为偏函数具有 isDefinedAt方法， onFailure方法只有在特定的Throwable类型对象中被定义才会触发。下面例子中的onFailure回调永远不会被触发：
+```scala
+val f: Future[List[String]] = Future {
+ session.getRecentPosts()
+}
- val f = Future {
- 2 / 0
- }
+for {
+ posts <- f
+ post <- posts
+} println(post)
+```
- f onFailure {
- case npe: NullPointerException =>
- println("I'd be amazed if this printed out.")
- }
+{% endtab %}
+{% tab 'Scala 3' for=futures-06 %}
+
+```scala
+val f: Future[List[String]] = Future {
+ session.getRecentPosts()
+}
+
+for
+ posts <- f
+ post <- posts
+do println(post)
+```
+
+{% endtab %}
+{% endtabs %}
+
+`Future` 提供了一个清晰的手段只用来处理失败的结果，这个手段是使用 `failed` 投影，这个投影把 `Failure[Throwable]` 转换成 `Success[Throwable]`。下面的[投影](#投影)章节提供了这样一个例子。
回到前面查找某个关键字第一次出现的例子，我们想要在屏幕上打印出此关键字的位置：
- val firstOccurrence: Future[Int] = Future {
- val source = scala.io.Source.fromFile("myText.txt")
- source.toSeq.indexOfSlice("myKeyword")
- }
+{% tabs futures-oncomplete %}
+{% tab 'Scala 2 and 3' for=futures-oncomplete %}
- firstOccurrence onSuccess {
- case idx => println("The keyword first appears at position: " + idx)
- }
+```scala
+val firstOccurrence: Future[Int] = Future {
+ val source = scala.io.Source.fromFile("myText.txt")
+ source.toSeq.indexOfSlice("myKeyword")
+}
- firstOccurrence onFailure {
- case t => println("Could not process file: " + t.getMessage)
- }
+firstOccurrence.onComplete {
+ case Success(idx) => println("The keyword first appears at position: " + idx)
+ case Failure(t) => println("Could not process file: " + t.getMessage)
+}
+```
- onComplete,、onSuccess 和 onFailure 方法都具有Unit的结果类型，这意味着不能链接使用这些方法的回调。注意这种设计是为了避免暗示而刻意为之的，因为链接回调也许暗示着按照一定的顺序执行注册回调（回调注册在同一个future中是无序的）。
+{% endtab %}
+{% endtabs %}
-也就是说，我们现在应讨论论何时调用callback。因为callback需要future的值是可用的，所有回调只能在future完成之后被调用。然而，不能保证callback在完成future的线程或创建callback的线程中被调用。反而， 回调(callback)会在future对象完成之后的一些线程和一段时间内执行。所以我们说回调(callback)最终会被执行。
+`onComplete` 和 `foreach` 方法都具有 `Unit` 的结果类型，这意味着不能链接使用这些方法的回调。注意这种设计是为了避免暗示而刻意为之的，因为链接回调也许暗示着按照一定的顺序执行注册回调（回调注册在同一个 future 中是无序的）。
-此外，回调(callback)执行的顺序不是预先定义的，甚至在相同的应用程序中callback的执行顺序也不尽相同。事实上，callback也许不是一个接一个连续的调用，但是可能会在同一时间同时执行。这意味着在下面的例子中，变量totalA也许不能在计算上下文中被设置为正确的大写或者小写字母。
+也就是说，我们现在应讨论**何时**正好在调用回调(callback)。因为回调需要 future 的值是可用的，所有回调只能在 future 完成之后被调用。
+然而，不能保证回调在完成 future 的线程或创建回调的线程中被调用。
+反而， 回调会在 future 对象完成之后的一些线程和一段时间内执行。所以我们说回调最终会被执行。
- @volatile var totalA = 0
+此外，回调(callback)执行的顺序不是预先定义的，甚至在相同的应用程序中回调的执行顺序也不尽相同。
+事实上，回调也许不是一个接一个连续的调用，但是可能会在同一时间同时执行。
+这意味着在下面的例子中，变量 `totalA` 也许不能在计算上下文中被设置为正确的大写或者小写字母 `a`。
- val text = Future {
- "na" * 16 + "BATMAN!!!"
- }
+{% tabs volatile %}
+{% tab 'Scala 2 and 3' for=volatile %}
+
+```scala
+@volatile var totalA = 0
- text onSuccess {
- case txt => totalA += txt.count(_ == 'a')
- }
+val text = Future {
+ "na" * 16 + "BATMAN!!!"
+}
- text onSuccess {
- case txt => totalA += txt.count(_ == 'A')
- }
-以上，这两个回调(callbacks)可能是一个接一个地执行的，这样变量totalA得到的预期值为18。然而，它们也可能是并发执行的，于是totalA最终可能是16或2，因为+= 是一个不可分割的操作符（即它是由一个读和一个写的步骤组成，这样就可能使其与其他的读和写任意交错执行）。
+text.foreach { txt =>
+ totalA += txt.count(_ == 'a')
+}
+
+text.foreach { txt =>
+ totalA += txt.count(_ == 'A')
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+以上，这两个回调(callbacks)可能是一个接一个地执行的，这样变量 `totalA` 得到的预期值为`18`。
+然而，它们也可能是并发执行的，于是 `totalA` 最终可能是`16`或`2`，因为 `+=` 不是一个原子性的操作符（即它是由一个读和一个写的步骤组成，这样就可能使其与其他的读和写任意交错执行）。
考虑到完整性，回调的使用情景列在这儿：
-- 在future中注册onComplete回调的时候要确保最后future执行完成之后调用相应的终止回调。
+1. 在 future 中注册 `onComplete` 回调的时候要确保最后 future 执行完成之后调用相应的终止回调。
-- 注册onSuccess或者onFailure回调时也和注册onComplete一样，不同之处在于future执行成功或失败分别调用onSuccess或onSuccess的对应的闭包。
+2. 注册 `foreach` 回调时也和注册 `onComplete` 一样，不同之处在于 future 成功完成才会调用闭包。
-- 注册一个已经完成的future的回调最后将导致此回调一直处于执行状态（1所隐含的）。
+3. 在一个已经完成的 future 上注册回调将导致此该回调最终被执行（1所隐含的）。
-- 在future中注册多个回调的情况下，这些回调的执行顺序是不确定的。事实上，这些回调也许是同时执行的，然而，特定的ExecutionContext执行可能导致明确的顺序。
+4. 在 future 中注册多个回调的情况下，这些回调的执行顺序是不确定的。事实上，这些回调也许是同时执行的。然而，特定的 `ExecutionContext` 实现可能导致明确的顺序。
-- 在一些回调抛出异常的情况下，其他的回调的执行不受影响。
+5. 在一些回调抛出异常的情况下，其他的回调的执行不受影响。
-- 在一些情况下，回调函数永远不能结束（例如，这些回调处于无限循环中），其他回调可能完全不会执行。在这种情况下，对于那些潜在的阻塞回调要使用阻塞的构造（例子如下）。
+6. 在一些情况下，回调函数永远不能结束（例如，这些回调处于无限循环中），其他回调可能完全不会执行。在这种情况下，对于那些潜在的阻塞回调要使用 `blocking` 的构造（例子如下）。
-- 一旦执行完，回调将从future对象中移除，这样更适合JVM的垃圾回收机制(GC)。
+7. 一旦执行完，回调将从 future 对象中移除，这样更适合垃圾回收机制(GC)。
### 函数组合(Functional Composition)和For解构(For-Comprehensions)
-尽管前文所展示的回调机制已经足够把future的结果和后继计算结合起来的，但是有些时候回调机制并不易于使用，且容易造成冗余的代码。我们可以通过一个例子来说明。假设我们有一个用于进行货币交易服务的API，我们想要在有盈利的时候购进一些美元。让我们先来看看怎样用回调来解决这个问题：
+尽管前文所展示的回调机制已经足够把future的结果和后继计算结合起来的。
+但是有些时候回调机制并不易于使用，且容易造成冗余的代码。
+我们可以通过一个例子来说明。假设我们有一个用于进行货币交易服务的 API，我们只想在有盈利的时候购进一些美元。让我们先来看看怎样用回调来解决这个问题：
- val rateQuote = Future {
- connection.getCurrentValue(USD)
- }
+{% tabs futures-07 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-07 %}
+
+```scala
+val rateQuote = Future {
+ connection.getCurrentValue(USD)
+}
- rateQuote onSuccess { case quote =>
- val purchase = Future {
- if (isProfitable(quote)) connection.buy(amount, quote)
- else throw new Exception("not profitable")
- }
+for (quote <- rateQuote) {
+ val purchase = Future {
+ if (isProfitable(quote)) connection.buy(amount, quote)
+ else throw new Exception("not profitable")
+ }
- purchase onSuccess {
- case _ => println("Purchased " + amount + " USD")
- }
- }
+ for (amount <- purchase)
+ println("Purchased " + amount + " USD")
+}
+```
-首先，我们创建一个名为rateQuote的future对象并获得当前的汇率。在服务器返回了汇率且该future对象成功完成了之后，计算操作才会从onSuccess回调中执行，这时我们就可以开始判断买还是不买了。所以我们创建了另一个名为purchase的future对象，用来在可盈利的情况下做出购买决定，并在稍后发送一个请求。最后，一旦purchase运行结束，我们会在标准输出中打印一条通知消息。
+{% endtab %}
+{% tab 'Scala 3' for=futures-07 %}
-这确实是可行的，但是有两点原因使这种做法并不方便。其一，我们不得不使用onSuccess，且不得不在其中嵌套purchase future对象。试想一下，如果在purchase执行完成之后我们可能会想要卖掉一些其他的货币。这时我们将不得不在onSuccess的回调中重复这个模式，从而可能使代码过度嵌套，过于冗长，并且难以理解。
+```scala
+val rateQuote = Future {
+ connection.getCurrentValue(USD)
+}
-其二，purchase只是定义在局部范围内--它只能被来自onSuccess内部的回调响应。这也就是说，这个应用的其他部分看不到purchase，而且不能为它注册其他的onSuccess回调，比如说卖掉些别的货币。
+for quote <- rateQuote do
+ val purchase = Future {
+ if isProfitable(quote) then connection.buy(amount, quote)
+ else throw Exception("not profitable")
+ }
-为解决上述的两个问题，futures提供了组合器（combinators）来使之具有更多易用的组合形式。映射（map）是最基本的组合器之一。试想给定一个future对象和一个通过映射来获得该future值的函数，映射方法将创建一个新Future对象，一旦原来的Future成功完成了计算操作，新的Future会通过该返回值来完成自己的计算。你能够像理解容器(collections)的map一样来理解future的map。
+ for amount <- purchase do
+ println("Purchased " + amount + " USD")
+```
-让我们用map的方法来重构一下前面的例子：
+{% endtab %}
+{% endtabs %}
- val rateQuote = Future {
- connection.getCurrentValue(USD)
- }
+首先，我们创建一个名为 `rateQuote` 的 future 对象并获得当前的汇率。
+在服务器返回了汇率且该 future 对象成功完成了之后，计算操作才会从 `foreach` 回调中执行，这时我们就可以开始判断买还是不买了。
+所以我们创建了另一个名为 `purchase` 的 future 对象，用来只在可盈利的情况下做出购买决定，然后发送一个请求。
+最后，一旦purchase运行结束，我们会在标准输出中打印一条通知消息。
- val purchase = rateQuote map { quote =>
- if (isProfitable(quote)) connection.buy(amount, quote)
- else throw new Exception("not profitable")
- }
+这确实是可行的，但是有两点原因使这种做法并不方便。其一，我们不得不使用 `foreach`，在其中嵌套第二个 `purchase` future 对象。试想一下，如果在 `purchase` 执行完成之后我们可能会想要卖掉一些其他的货币。这时我们将不得不在 `foreach` 回调中重复这个模式，从而可能使代码过度嵌套，过于冗长，并且难以理解。
- purchase onSuccess {
- case _ => println("Purchased " + amount + " USD")
- }
+其二，`purchase` future 不在余下的代码范围内 -- 它只能被来自 `foreach` 内部的回调响应。这也就是说，这个应用的其他部分看不到 `purchase`，而且不能为它注册其他的 `foreach` 回调，比如说卖掉些别的货币。
-通过对rateQuote的映射我们减少了一次onSuccess的回调，更重要的是避免了嵌套。这时如果我们决定出售一些货币就可以再次使用purchase方法上的映射了。
+为解决上述的两个问题， futures提供了组合器（combinators）来使之具有更多易用的组合形式。映射（map）是最基本的组合器之一。试想给定一个 future 对象和一个通过映射来获得该 future 值的函数，映射方法将创建一个新 Future 对象，一旦原来的 Future 成功完成了计算操作，新的 Future 会通过该返回值来完成自己的计算。你能够像理解容器(collections)的map一样来理解 future 的map。
-可是如果isProfitable方法返回了false将会发生些什么？会引发异常？这种情况下，purchase的确会因为异常而失败。不仅仅如此，想象一下，链接的中断和getCurrentValue方法抛出异常会使rateQuote的操作失败。在这些情况下映射将不会返回任何值，而purchase也会会自动的以和rateQuote相同的异常而执行失败。
+让我们用 `map` 组合器来重构一下前面的例子：
-总之，如果原Future的计算成功完成了，那么返回的Future将会使用原Future的映射值来完成计算。如果映射函数抛出了异常则Future也会带着该异常完成计算。如果原Future由于异常而计算失败，那么返回的Future也会包含相同的异常。这种异常的传导方式也同样适用于其他的组合器(combinators)。
+{% tabs futures-08 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-08 %}
-使之能够在For-comprehensions原则下使用，是设计Future的目的之一。也正是因为这个原因，Future还拥有flatMap，filter和foreach等组合器。其中flatMap方法可以构造一个函数，它可以把值映射到一个姑且称为g的新future，然后返回一个随g的完成而完成的Future对象。
+```scala
+val rateQuote = Future {
+ connection.getCurrentValue(USD)
+}
-让我们假设我们想把一些美元兑换成瑞士法郎。我们必须为这两种货币报价，然后再在这两个报价的基础上确定交易。下面是一个在for-comprehensions中使用flatMap和withFilter的例子：
+val purchase = rateQuote map { quote =>
+ if (isProfitable(quote)) connection.buy(amount, quote)
+ else throw new Exception("not profitable")
+}
- val usdQuote = Future { connection.getCurrentValue(USD) }
- val chfQuote = Future { connection.getCurrentValue(CHF) }
+purchase.foreach { amount =>
+ println("Purchased " + amount + " USD")
+}
+```
- val purchase = for {
- usd <- usdQuote
- chf <- chfQuote
- if isProfitable(usd, chf)
- } yield connection.buy(amount, chf)
+{% endtab %}
+{% tab 'Scala 3' for=futures-08 %}
- purchase onSuccess {
- case _ => println("Purchased " + amount + " CHF")
- }
+```scala
+val rateQuote = Future {
+ connection.getCurrentValue(USD)
+}
-purchase只有当usdQuote和chfQuote都完成计算以后才能完成-- 它以其他两个Future的计算值为前提所以它自己的计算不能更早的开始。
+val purchase = rateQuote.map { quote =>
+ if isProfitable(quote) then connection.buy(amount, quote)
+ else throw Exception("not profitable")
+}
-上面的for-comprhension将被转换为：
+purchase.foreach { amount =>
+ println("Purchased " + amount + " USD")
+}
+```
- val purchase = usdQuote flatMap {
- usd =>
- chfQuote
- .withFilter(chf => isProfitable(usd, chf))
- .map(chf => connection.buy(amount, chf))
- }
+{% endtab %}
+{% endtabs %}
+
+通过在 `rateQuote` 上使用 `map`，我们减少了一次 `foreach` 的回调，更重要的是避免了嵌套。这时如果我们决定出售一些货币就可以再次在 `purchase` 上使用 `map` 了。
+
+可是如果 `isProfitable` 方法返回了 `false` 将会发生些什么？会引发异常？
+这种情况下，`purchase` 的确会因为异常而失败。不仅仅如此，想象一下，链接的中断和 `getCurrentValue` 方法抛出异常会使 `rateQuote` 的操作失败。
+在这些情况下映射将不会返回任何值，而 `purchase` 也会自动的以和 `rateQuote` 相同的异常而失败。
+
+总之，如果原 future 成功完成了，那么返回的 future 将会使用从原 future来的映射值完成。如果映射函数抛出了异常则返回的 future 也会带着一样的异常。如果原 future 由于异常而计算失败，那么返回的 future 也会包含相同的异常。这种异常的传导语义也存在于其余的组合器(combinators)。
+
+使之能够在for-comprehensions 中使用，是设计 future 的目的之一。
+因为这个原因，future 还拥有 `flatMap` 和 `withFilter` 组合器。`flatMap` 方法获取一个函数，该函数把值映射到一个新 future `g`，然后返回一个随 `g` 的完成而完成的 future。
+
+让我们假设我们想把一些美元兑换成瑞士法郎（CHF）。我们必须为这两种货币报价，然后再在这两个报价的基础上确定交易。
+下面是一个在 for-comprehensions 中使用 `flatMap` 和 `withFilter` 的例子：
+
+{% tabs futures-09 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-09 %}
+
+```scala
+val usdQuote = Future { connection.getCurrentValue(USD) }
+val chfQuote = Future { connection.getCurrentValue(CHF) }
+
+val purchase = for {
+ usd <- usdQuote
+ chf <- chfQuote
+ if isProfitable(usd, chf)
+} yield connection.buy(amount, chf)
-这的确是比for-comprehension稍微难以把握一些，但是我们这样分析有助于您更容易的理解flatMap的操作。FlatMap操作会把自身的值映射到其他future对象上，并随着该对象计算完成的返回值一起完成计算。在我们的例子里，flatMap用usdQuote的值把chfQuote的值映射到第三个futrue对象里，该对象用于发送一定量瑞士法郎的购入请求。只有当通过映射返回的第三个future对象完成了计算，purchase才能完成计算。
+purchase foreach { amount =>
+ println("Purchased " + amount + " CHF")
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-09 %}
+
+```scala
+val usdQuote = Future { connection.getCurrentValue(USD) }
+val chfQuote = Future { connection.getCurrentValue(CHF) }
+
+val purchase = for
+ usd <- usdQuote
+ chf <- chfQuote
+ if isProfitable(usd, chf)
+yield connection.buy(amount, chf)
+
+purchase.foreach { amount =>
+ println("Purchased " + amount + " CHF")
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+`purchase` 只有当 `usdQuote` 和 `chfQuote` 都完成计算以后才能完成-- 它以其他两个 future 的计算值为前提所以它自己的计算不能更早的开始。
+
+上面的 for-comprhension 将被转换为：
+
+{% tabs for-translation %}
+{% tab 'Scala 2 and 3' for=for-translation %}
+
+```scala
+val purchase = usdQuote flatMap {
+ usd =>
+ chfQuote
+ .withFilter(chf => isProfitable(usd, chf))
+ .map(chf => connection.buy(amount, chf))
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+这的确是比for-comprehension稍微难以把握一些，但是我们这样分析有助于您更容易的理解 `flatMap` 的操作。`flatMap` 操作会把自身的值映射到其他future对象上，并随着该对象计算完成的返回值一起完成计算。
+在我们的例子里，`flatMap` 用 `usdQuote` 的值把 `chfQuote` 的值映射到第三个 futrue 对象里，该对象用于发送一定量瑞士法郎的购入请求。
+只有当通过 `map` 返回的第三个 future 对象完成，结果 future `purchase` 才能完成。
这可能有些难以置信，但幸运的是faltMap操作在for-comprhensions模式以外很少使用，因为for-comprehensions本身更容易理解和使用。
-再说说filter，它可以用于创建一个新的future对象，该对象只有在满足某些特定条件的前提下才会得到原始future的计算值，否则就会抛出一个NoSuchElementException的异常而失败。调用了filter的future，其效果与直接调用withFilter完全一样。
+`filter` 组合器可以用于创建一个新的 future 对象，该对象只有在满足某些特定条件的前提下才会得到原始future的值。否则新 future 就会有 `NoSuchElementException` 的失败。调用了 `filter` 的future，其效果与直接调用 `withFilter` 完全一样。
-作为组合器的collect同filter之间的关系有些类似容器（collections）API里的那些方法之间的关系。
+作为组合器的 `collect` 同 `filter` 之间的关系有些类似容器（collections）API里的那些方法之间的关系。
-值得注意的是，调用foreach组合器并不会在计算值可用的时候阻塞当前的进程去获取计算值。恰恰相反，只有当future对象成功计算完成了，foreach所迭代的函数才能够被异步的执行。这意味着foreach与onSuccess回调意义完全相同。
+由于 `Future` trait(译注: trait有点类似java中的接口(interface)的概念)从概念上看可以包含两种类型的返回值（计算结果和异常），所以组合器会有一个处理异常的需求。
-由于Future trait(译注: trait有点类似java中的接口(interface)的概念)从概念上看包含两种类型的返回值（计算结果和异常），所以组合器会有一个处理异常的需求。
+比方说我们准备在 `rateQuote` 的基础上决定购入一定量的货币，那么 `connection.buy` 方法需要获取购入的 `amount` 和期望的 `quote`。它返回完成购买的数量。假如 `quote` 偏偏在这个节骨眼儿改变了，那buy方法将会抛出一个 `QuoteChangedExecption`，并且不会做任何交易。如果我们想让我们的 future 对象返回`0`而不是抛出那个异常，那我们需要使用 `recover` 组合器：
-比方说我们准备在rateQuote的基础上决定购入一定量的货币，那么`connection.buy`方法需要知道购入的数量和期望的报价值，最终完成购买的数量将会被返回。假如报价值偏偏在这个节骨眼儿改变了，那buy方法将会抛出一个`QuoteChangedExecption`，并且不会做任何交易。如果我们想让我们的Future对象返回0而不是抛出那个该死的异常，那我们需要使用recover组合器：
- val purchase: Future[Int] = rateQuote map {
- quote => connection.buy(amount, quote)
- } recover {
- case QuoteChangedException() => 0
- }
+{% tabs recover %}
+{% tab 'Scala 2 and 3' for=recover %}
-这里用到的recover能够创建一个新future对象，该对象当计算完成时持有和原future对象一样的值。如果执行不成功则偏函数的参数会被传递给使原Future失败的那个Throwable异常。如果它把Throwable映射到了某个值，那么新的Future就会成功完成并返回该值。如果偏函数没有定义在Throwable中，那么最终产生结果的future也会失败并返回同样的Throwable。
+```scala
+val purchase: Future[Int] = rateQuote.map {
+ quote => connection.buy(amount, quote)
+} recover {
+ case QuoteChangedException() => 0
+}
+```
+{% endtab %}
+{% endtabs %}
-组合器recoverWith能够创建一个新future对象，当原future对象成功完成计算时，新future对象包含有和原future对象相同的计算结果。若原future失败或异常，偏函数将会返回造成原future失败的相同的Throwable异常。如果此时Throwable又被映射给了别的future，那么新Future就会完成并返回这个future的结果。recoverWith同recover的关系跟flatMap和map之间的关系很像。
+这里用到的 `recover` 能够创建一个新 future 对象，该对象当成功完成时持有和原 future 对象一样的值。如果执行不成功则偏函数的参数会被传递给使原 future 失败的那个 `Throwable` 异常。如果它把 `Throwable` 映射到了某个值，那么新的 future 就会成功完成并返回该值。
+如果偏函数没有定义在 `Throwable` 中，那么最终产生结果的 future 也会失败并返回同样的 `Throwable`。
-fallbackTo组合器生成的future对象可以在该原future成功完成计算时返回结果，如果原future失败或异常返回future参数对象的成功值。在原future和参数future都失败的情况下，新future对象会完成并返回原future对象抛出的异常。正如下面的例子中，本想打印美元的汇率，但是在获取美元汇率失败的情况下会打印出瑞士法郎的汇率：
+组合器 `recoverWith` 能够创建一个新 future 对象，当原 future 对象成功完成计算时，新 future 包含有和原 future 相同的结果。若原 future 失败或异常，偏函数将会返回造成原 future 失败的相同的 `Throwable` 异常。如果此时 `Throwable` 又被映射给了别的 future ，那么新 future 就会完成并返回这个 future 的结果。
+`recoverWith` 同 `recover` 的关系跟 `flatMap` 和 `map` 之间的关系很像。
- val usdQuote = Future {
- connection.getCurrentValue(USD)
- } map {
- usd => "Value: " + usd + "$"
- }
- val chfQuote = Future {
- connection.getCurrentValue(CHF)
- } map {
- chf => "Value: " + chf + "CHF"
- }
+`fallbackTo` 组合器生成的 future 对象可以在该原 future 成功完成计算时返回结果，如果原 future 失败或异常返回 future 参数对象的成功值。在原 future 和参数 future 都失败的情况下，新 future 对象会完成并返回原 future 对象抛出的异常。正如下面的例子中，本想打印美元的汇率，但是在获取美元汇率失败的情况下会打印出瑞士法郎的汇率：
- al anyQuote = usdQuote fallbackTo chfQuote
+{% tabs fallback-to %}
+{% tab 'Scala 2 and 3' for=fallback-to %}
- anyQuote onSuccess { println(_) }
+```scala
+val usdQuote = Future {
+ connection.getCurrentValue(USD)
+}.map {
+ usd => "Value: " + usd + "$"
+}
+val chfQuote = Future {
+ connection.getCurrentValue(CHF)
+} map {
+ chf => "Value: " + chf + "CHF"
+}
-组合器andThen的用法是出于纯粹的side-effecting目的。经andThen返回的新Future无论原Future成功或失败都会返回与原Future一模一样的结果。一旦原Future完成并返回结果，andThen后跟的代码块就会被调用，且新Future将返回与原Future一样的结果，这确保了多个andThen调用的顺序执行。正如下例所示，这段代码可以从社交网站上把近期发出的帖子收集到一个可变集合里，然后把它们都打印在屏幕上：
+val anyQuote = usdQuote.fallbackTo(chfQuote)
- val allposts = mutable.Set[String]()
+anyQuote.foreach { println(_) }
+```
- Future {
- session.getRecentPosts
- } andThen {
- case Success(posts) => allposts ++= posts
- } andThen {
- case _ =>
- clearAll()
- for (post <- allposts) render(post)
- }
+{% endtab %}
+{% endtabs %}
-综上所述，Future的组合器功能是纯函数式的，每种组合器都会返回一个与原Future相关的新Future对象。
+组合器 `andThen` 的用法是出于纯粹的side-effecting目的。经 `andThen` 返回的新 future 无论原 future 成功或失败都会返回与原 future 一模一样的结果。
+一旦原 future 完成并返回结果，`andThen` 后跟的代码块就会被调用，且新 future 将返回与原 future 一样的结果，这确保了多个 `andThen` 调用的顺序执行。正如下例所示，这段代码可以从社交网站上把近期发出的帖子收集到一个可变集合里，然后把它们都打印在屏幕上：
-### 投影(Projections)
+{% tabs futures-10 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-10 %}
-为了确保for解构(for-comprehensions)能够返回异常，futures也提供了投影(projections)。如果原future对象失败了，失败的投影(projection)会返回一个带有Throwable类型返回值的future对象。如果原Future成功了，失败的投影(projection)会抛出一个NoSuchElementException异常。下面就是一个在屏幕上打印出异常的例子：
+```scala
+val allposts = mutable.Set[String]()
- val f = Future {
- 2 / 0
- }
- for (exc <- f.failed) println(exc)
+Future {
+ session.getRecentPosts
+} andThen {
+ case Success(posts) => allposts ++= posts
+} andThen {
+ case _ =>
+ clearAll()
+ for (post <- allposts) render(post)
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-10 %}
+
+```scala
+val allPosts = mutable.Set[String]()
+
+Future {
+ session.getRecentPosts()
+}.andThen {
+ case Success(posts) => allPosts ++= posts
+}.andThen {
+ case _ =>
+ clearAll()
+ for post <- allPosts do render(post)
+}
+```
+{% endtab %}
+{% endtabs %}
+
+综上所述，在 future 上的组合器功能是纯函数式的。
+每种组合器都会返回一个与原future相关的新 future 对象。
+### 投影
+
+为了确保for解构(for-comprehensions)能够返回异常， future s也提供了投影(projections)。如果原 future 对象失败了，`failed` 的投影会返回一个带有 `Throwable` 类型返回值的 future 对象。如果原 future 成功了，`failed` 的投影失败并有一个 `NoSuchElementException`。下面就是一个在屏幕上打印出异常的例子：
+
+{% tabs futures-11 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-11 %}
+
+```scala
+val f = Future {
+ 2 / 0
+}
+for (exc <- f.failed) println(exc)
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-11 %}
+
+```scala
+val f = Future {
+ 2 / 0
+}
+for exc <- f.failed do println(exc)
+```
+
+{% endtab %}
+{% endtabs %}
+
+本例中的 for-comprehension 翻译成：
+
+{% tabs for-comp-tran %}
+{% tab 'Scala 2 and 3' for=for-comp-tran %}
+
+```scala
+f.failed.foreach(exc => println(exc))
+```
+
+{% endtab %}
+{% endtabs %}
+
+因为 `f` 在这没有成功，该闭包被注册到新成功的 `Future[Throwable]` 上的 `foreach`。
下面的例子不会在屏幕上打印出任何东西：
- val f = Future {
+{% tabs futures-12 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-12 %}
+
+```scala
+val f = Future {
+ 4 / 2
+}
+for (exc <- f.failed) println(exc)
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-12 %}
+
+```scala
+val g = Future {
+ 4 / 2
+}
+for exc <- g.failed do println(exc)
+```
+
+{% endtab %}
+{% endtabs %}
+
+
+
+
+
+
### Future的扩展
-用更多的实用方法来对Futures API进行扩展支持已经被提上了日程，这将为很多外部框架提供更多专业工具。
+用更多的实用方法来对 Futures API 进行扩展支持已经被提上了日程，这将为很多外部框架提供更多专业工具。
-## Blocking
+## 阻塞（Blocking）
-正如前面所说的，在future的blocking非常有效地缓解性能和预防死锁。虽然在futures中使用这些功能方面的首选方式是Callbacks和combinators，但在某些处理中也会需要用到blocking，并且它也是被Futures and Promises API所支持的。
+Future 通常是异步的，不会阻塞底层执行线程。
+但是，在某些情况下，有必要阻塞。
+我们区分了两种形式的阻塞执行线程：
+调用任意代码，从 future 来内部阻塞线程，
+以及从另一个 future 外部阻塞，等待该 future 完成。
-在之前的并发交易(concurrency trading)例子中，在应用的最后有一处用到block来确定是否所有的futures已经完成。这有个如何使用block来处理一个future结果的例子：
+### Future 内的阻塞
- import scala.concurrent._
- import scala.concurrent.duration._
+正如在全局 `ExecutionContext` 中看到的那样，可以使用 `blocking` 结构通知某个阻塞调用的 `ExecutionContext`。
+但是，实现完全由 `ExecutionContext`。一些 `ExecutionContext`，如 `ExecutionContext.global`，用 `MangedBlocker` 的办法实现 `blocking`，而另外一样通过执行上下文，如固定线程池来实现 `blocking`：
+通过“ManagedBlocker”实现“阻塞”，一些执行上下文，如固定线程池：
- def main(args: Array[String]) {
- val rateQuote = Future {
- connection.getCurrentValue(USD)
- }
+{% tabs fixed-thread-pool %}
+{% tab 'Scala 2 and 3' for=fixed-thread-pool %}
- val purchase = rateQuote map { quote =>
- if (isProfitable(quote)) connection.buy(amount, quote)
- else throw new Exception("not profitable")
- }
+```scala
+ExecutionContext.fromExecutor(Executors.newFixedThreadPool(x))
+```
- Await.result(purchase, 0 nanos)
- }
+{% endtab %}
+{% endtabs %}
-在这种情况下这个future是不成功的，这个调用者转发出了该future对象不成功的异常。它包含了失败的投影(projection)-- 阻塞(blocking)该结果将会造成一个NoSuchElementException异常在原future对象被成功计算的情况下被抛出。
+将不作任何事，就像下面演示的那样：
-相反的，调用`Await.ready`来等待这个future直到它已完成，但获不到它的结果。同样的方式，调用那个方法时如果这个future是失败的，它将不会抛出异常。
+{% tabs futures-13 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-13 %}
-The Future trait实现了Awaitable trait还有其`ready()`和`result()`方法。这些方法不能被客户端直接调用，它们只能通过执行环境上下文来进行调用。
+```scala
+implicit val ec =
+ ExecutionContext.fromExecutor(Executors.newFixedThreadPool(4))
-为了允许程序调用可能是阻塞式的第三方代码，而又不必实现Awaitable特质，原函数可以用如下的方式来调用：
+Future {
+ blocking { blockingStuff() }
+}
+```
- blocking {
- potentiallyBlockingCall()
- }
+{% endtab %}
+{% tab 'Scala 3' for=futures-13 %}
-这段blocking代码也可以抛出一个异常。在这种情况下，这个异常会转发给调用者。
+```scala
+given ExecutionContext =
+ ExecutionContext.fromExecutor(Executors.newFixedThreadPool(4))
-## 异常(Exceptions)
+Future {
+ blocking { blockingStuff() }
+}
+```
-当异步计算抛出未处理的异常时，与那些计算相关的futures就失败了。失败的futures存储了一个Throwable的实例，而不是返回值。Futures提供onFailure回调方法，它用一个PartialFunction去表示一个Throwable。下列特殊异常的处理方式不同：
+{% endtab %}
+{% endtabs %}
-`scala.runtime.NonLocalReturnControl[_]` --此异常保存了一个与返回相关联的值。通常情况下，在方法体中的返回结构被调用去抛出这个异常。相关联的值将会存储到future或一个promise中，而不是一直保存在这个异常中。
+和以下代码有一样的副作用：
-ExecutionException-当因为一个未处理的中断异常、错误或者`scala.util.control.ControlThrowable`导致计算失败时会被存储起来。这种情况下，ExecutionException会为此具有未处理的异常。这些异常会在执行失败的异步计算线程中重新抛出。这样做的目的，是为了防止正常情况下没有被客户端代码处理过的那些关键的、与控制流相关的异常继续传播下去，同时告知客户端其中的future对象是计算失败的。
+{% tabs alternative %}
+{% tab 'Scala 2 and 3' for=alternative %}
-更精确的语义描述请参见 [NonFatal]。
+```scala
+Future { blockingStuff() }
+```
-## Promises
+{% endtab %}
+{% endtabs %}
-到目前为止，我们仅考虑了通过异步计算的方式创建future对象来使用future的方法。尽管如此，futures也可以使用promises来创建。
+阻塞代码也可能抛出异常。这种情况下，异常被转发给调用者。
-如果说futures是为了一个还没有存在的结果，而当成一种只读占位符的对象类型去创建，那么promise就被认为是一个可写的，可以实现一个future的单一赋值容器。这就是说，promise通过这种success方法可以成功去实现一个带有值的future。相反的，因为一个失败的promise通过failure方法就会实现一个带有异常的future。
+### Future 外部的阻塞
-一个promise p通过p.future方式返回future。 这个futrue对象被指定到promise p。根据这种实现方式，可能就会出现p.future与p相同的情况。
+正如前面所说的，为了性能和防止死锁，强烈建议不要在future上用阻塞。
+虽然在futures中使用这些功能方面的首选方式是回调和组合器，但在某些处理中也会需要用到阻塞，并且 Futures API 和 Promises API也支持它。
-考虑下面的生产者 - 消费者的例子，其中一个计算产生一个值，并把它转移到另一个使用该值的计算。这个传递中的值通过一个promise来完成。
+在之前的并发交易(concurrency trading)例子中，在应用的最后有一处用到阻塞来确定是否所有的 futures已经完成。这有个如何使用阻塞来处理一个 future 结果的例子：
- import scala.concurrent.{ Future, Promise }
- import scala.concurrent.ExecutionContext.Implicits.global
+{% tabs futures-14 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-14 %}
- val p = Promise[T]()
- val f = p.future
+```scala
+import scala.concurrent._
+import scala.concurrent.duration._
- val producer = Future {
- val r = produceSomething()
- p success r
- continueDoingSomethingUnrelated()
+object awaitPurchase {
+ def main(args: Array[String]): Unit = {
+ val rateQuote = Future {
+ connection.getCurrentValue(USD)
}
- val consumer = Future {
- startDoingSomething()
- f onSuccess {
- case r => doSomethingWithResult()
- }
+ val purchase = rateQuote map { quote =>
+ if (isProfitable(quote)) connection.buy(amount, quote)
+ else throw new Exception("not profitable")
}
-在这里，我们创建了一个promise并利用它的future方法获得由它实现的Future。然后，我们开始了两种异步计算。第一种做了某些计算，结果值存放在r中，通过执行promise p，这个值被用来完成future对象f。第二种做了某些计算，然后读取实现了future f的计算结果值r。需要注意的是，在生产者完成执行`continueDoingSomethingUnrelated()` 方法这个任务之前，消费者可以获得这个结果值。
+ Await.result(purchase, 0.nanos)
+ }
+}
+```
-正如前面提到的，promises具有单赋值语义。因此，它们仅能被实现一次。在一个已经计算完成的promise或者failed的promise上调用success方法将会抛出一个IllegalStateException异常。
+{% endtab %}
+{% tab 'Scala 3' for=futures-14 %}
-下面的这个例子显示了如何fail a promise。
+```scala
+import scala.concurrent.*
+import scala.concurrent.duration.*
- val p = promise[T]
- val f = p.future
+@main def awaitPurchase =
+ val rateQuote = Future {
+ connection.getCurrentValue(USD)
+ }
- val producer = Future {
- val r = someComputation
- if (isInvalid(r))
- p failure (new IllegalStateException)
- else {
- val q = doSomeMoreComputation(r)
- p success q
- }
- }
+ val purchase = rateQuote.map { quote =>
+ if isProfitable(quote) then connection.buy(amount, quote)
+ else throw Exception("not profitable")
+ }
-如上，生产者计算出一个中间结果值r，并判断它的有效性。如果它不是有效的，它会通过返回一个异常实现promise p的方式fails the promise，关联的future f是failed。否则，生产者会继续它的计算，最终使用一个有效的结果值实现future f，同时实现 promise p。
+ Await.result(purchase, 0.nanos)
+```
-Promises也能通过一个complete方法来实现，这个方法采用了一个`potential value Try[T]`，这个值要么是一个类型为`Failure[Throwable]`的失败的结果值，要么是一个类型为`Success[T]`的成功的结果值。
+{% endtab %}
+{% endtabs %}
-类似success方法，在一个已经完成(completed)的promise对象上调用failure方法和complete方法同样会抛出一个IllegalStateException异常。
+在这种情况下这个 future 是不成功的，这个调用者转发出了该 future 对象不成功的异常。它包含了 `failed` 的投影(projection)-- 阻塞(blocking)该结果将会造成一个 `NoSuchElementException` 异常在原 future 对象被成功计算的情况下被抛出。
-应用前面所述的promises和futures方法的一个优点是，这些方法是单一操作的并且是没有副作用(side-effects)的，因此程序是具有确定性的(deterministic)。确定性意味着，如果该程序没有抛出异常(future的计算值被获得)，无论并行的程序如何调度，那么程序的结果将会永远是一样的。
+相反的，调用`Await.ready`来等待这个future直到它已完成，但获不到它的结果。同样的方式，调用那个方法时如果这个future是失败的，它将不会抛出异常。
-在一些情况下，客户端也许希望能够只在promise没有完成的情况下完成该promise的计算(例如，如果有多个HTTP请求被多个不同的futures对象来执行，并且客户端只关心地一个HTTP应答(response)，该应答对应于地一个完成该promise的future)。因为这个原因，future提供了tryComplete，trySuccess和tryFailure方法。客户端需要意识到调用这些的结果是不确定的，调用的结果将以来从程序执行的调度。
+The `Future` trait实现了 `Awaitable` trait 还有其 `ready()` 和 `result()` 方法。这些方法不能被客户端直接调用，它们只能通过执行环境上下文来进行调用。
-completeWith方法将用另外一个future完成promise计算。当该future结束的时候，该promise对象得到那个future对象同样的值，如下的程序将打印1：
+## 异常(Exceptions)
- val f = Future { 1 }
- val p = promise[Int]
+当异步计算抛出未处理的异常时，与那些计算相关的 futures 就失败了。失败的 futures 存储了一个 `Throwable` 的实例，而不是返回值。`Futures` 提供 `failed` 投影方法，它允许这个 `Throwable` 被当作另一个 `Future` 的成功值来处理。下列特殊异常的处理方式不同：
+1. `scala.runtime.NonLocalReturnControl[_]` -- 此异常保存了一个与返回相关联的值。通常情况下，方法体中的 `return` 结构被翻译成带有异常的 `throw` 。相关联的值将会存储到future或一个promise中，而不是一直保存在这个异常中。
- p completeWith f
+2. `ExecutionException` -- 当因为一个未处理的 `InterruptedException`, `Error` 或者 `scala.util.control.ControlThrowable` 导致计算失败时会被存储起来。这种情况下， `ExecutionException` 会为此具有未处理的异常。这些异常会在执行失败的异步计算线程中重新抛出。这样做的目的，是为了防止正常情况下没有被客户端代码处理过的那些关键的、与控制流相关的异常继续传播下去，同时告知客户端其中的 future 对象是计算失败的。
- p.future onSuccess {
- case x => println(x)
- }
+致命异常（由 `NonFatal` 确定）在执行失败的异步计算的线程中重新引发。这会通知管理问题执行线程的代码，并允许它在必要时快速失败。更精确的语义描述请参见[`NonFatal`](https://www.scala-lang.org/api/current/scala/util/control/NonFatal$.html)。
+
+## Promise
+
+到目前为止，我们仅考虑了通过异步计算的方式创建 `Future` 对象来使用 `Future` 的方法。尽管如此，futures也可以使用 *promises* 来创建。
+
+如果说futures是为了一个还没有存在的结果，而当成一种只读占位符的对象类型去创建，那么promise就被认为是一个可写的，可以实现一个future的单一赋值容器。这就是说，promise通过这种 `success` 方法可以成功去实现一个带有值(通过 “实现” 该 promise)的future。相反的，用 `failure` 方法。
+一个 promise 也能用来实现带有异常的 future，通过这个失败的promise。
+
+一个promise `p` 通过 `p.future` 方式返回future。 这个futrue对象被指定到promise `p`。根据这种实现方式，可能就会出现 `p.future eq p` 的情况。
+
+考虑下面的生产者-消费者的例子，其中一个计算产生一个值，并把它转移到另一个使用该值的计算。这个传递中的值通过一个 promise 来完成。
+
+{% tabs promises %}
+{% tab 'Scala 2 and 3' for=promises %}
+
+```scala
+import scala.concurrent.{ Future, Promise }
+import scala.concurrent.ExecutionContext.Implicits.global
+
+val p = Promise[T]()
+val f = p.future
+
+val producer = Future {
+ val r = produceSomething()
+ p.success(r)
+ continueDoingSomethingUnrelated()
+}
+
+val consumer = Future {
+ startDoingSomething()
+ f.foreach { r =>
+ doSomethingWithResult()
+ }
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+在这里，我们创建了一个promise并利用它的 `future` 方法获得由它实现的 `Future`。然后，我们开始了两种异步计算。第一种做了某些计算，结果值存放在r中，通过执行promise `p`，这个值被用来完成future对象 `f`。第二种做了某些计算，然后读取实现了 future `f` 的计算结果值 `r`。需要注意的是，在 `producer` 完成执行 `continueDoingSomethingUnrelated()` 方法这个任务之前，消费者可以获得这个结果值。
+
+正如前面提到的，promises 具有单赋值语义。因此，它们仅能被完成一次。在一个已经计算完成的 promise 或者 failed 的promise上调用 `success` 方法将会抛出一个 `IllegalStateException` 异常。
+
+下面的这个例子显示了如何使 promise 失败。
+
+{% tabs futures-15 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-15 %}
+
+```scala
+val p = Promise[T]()
+val f = p.future
+
+val producer = Future {
+ val r = someComputation
+ if (isInvalid(r))
+ p.failure(new IllegalStateException)
+ else {
+ val q = doSomeMoreComputation(r)
+ p.success(q)
+ }
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-15 %}
+
+```scala
+val p = Promise[T]()
+val f = p.future
+
+val producer = Future {
+ val r = someComputation
+ if isInvalid(r) then
+ p.failure(new IllegalStateException)
+ else
+ val q = doSomeMoreComputation(r)
+ p.success(q)
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+如上， `producer` 计算出一个中间结果值 `r`，并判断它的有效性。如果它不是有效的，它会通过返回一个异常实现promise `p` 的方式fails the promise，关联的future `f` 是失败的。否则， `producer` 会继续它的计算，最终使用一个有效的结果值实现future f，同时实现 promise p。
+
+Promises也能通过一个complete方法来实现，这个方法采用了一个 `potential value Try[T]`，这个值要么是一个类型为 `Failure[Throwable]` 的失败的结果值，要么是一个类型为 `Success[T]` 的成功的结果值。
+
+类似 `success` 方法，在一个已经完成(completed)的promise对象上调用 `failure` 方法和 `complete` 方法同样会抛出一个 `IllegalStateException` 异常。
+
+应用前面所述的 promises 和 futures 操作的一个优点是，这些方法是单一操作的并且是没有副作用(side-effects)的，因此程序是具有确定性的(deterministic)。确定性意味着，如果该程序没有抛出异常(future 的计算值被获得)，无论并行的程序如何调度，那么程序的结果将会永远是一样的。
+
+在一些情况下，客户端也许希望能够只在 promise 没有完成的情况下完成该 promise 的计算(例如，如果有多个HTTP请求被多个不同的futures对象来执行，并且客户端只关心第一个HTTP应答(response)，该应答对应于第一个完成该 promise 的future)。因为这些原因，future提供了 `tryComplete`，`trySuccess` 和 `tryFailure` 方法。客户端需要意识到调用这些的结果是不确定的，调用的结果将以来从程序执行的调度。
+
+`completeWith` 方法将用另外一个 future 完成 promise 计算。当该 future 结束的时候，该 promise 对象得到那个 future 对象同样的值，如下的程序将打印 `1`：
-当让一个promise以异常失败的时候，三总子类型的Throwable异常被分别的处理。如果中断该promise的可抛出(Throwable)一场是`scala.runtime.NonLocalReturnControl`，那么该promise将以对应的值结束；如果是一个Error的实例，`InterruptedException`或者`scala.util.control.ControlThrowable`，那么该可抛出(Throwable)异常将会封装一个ExecutionException异常，该ExectionException将会让该promise以失败结束。
+{% tabs promises-2 %}
+{% tab 'Scala 2 and 3' for=promises-2 %}
-通过使用promises，futures的onComplete方法和future的构造方法，你能够实现前文描述的任何函数式组合组合器(compition combinators)。让我们来假设一下你想实现一个新的组合起，该组合器首先使用两个future对象f和，产生第三个future，该future能够用f或者g来完成，但是只在它能够成功完成的情况下。
+```scala
+val f = Future { 1 }
+val p = promise[Int]()
+
+p.completeWith(f)
+
+p.future.foreach { x =>
+ println(x)
+}
+```
+
+{% endtab %}
+{% endtabs %}
+
+当让一个promise以异常失败的时候，三个子类型的 `Throwable` 异常被分别的处理。如果中断该promise的可抛出(Throwable)一场是`scala.runtime.NonLocalReturnControl`，那么该promise将以对应的值结束；如果是一个Error的实例，`InterruptedException` 或者 `scala.util.control.ControlThrowable`，那么该 `Throwable` 异常将会封装一个 `ExecutionException` 异常，该 `ExectionException` 将会让该 promise 以失败结束。
+
+通过使用 promises，futures 的 `onComplete` 方法和 `future` 的构造方法，你能够实现前文描述的任何函数式组合组合器(compition combinators)。
+让我们来假设一下你想实现一个新的组合器 `first`，该组合器使用两个future `f` 和 `g`，然后生产出第三个 future，该future能够用 `f` 或者 `g` 来完成（看哪一个先到），但前提是它能够成功。
这里有个关于如何去做的实例：
- def first[T](f: Future[T], g: Future[T]): Future[T] = {
- val p = promise[T]
+{% tabs futures-16 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-16 %}
- f onSuccess {
- case x => p.trySuccess(x)
- }
+```scala
+def first[T](f: Future[T], g: Future[T]): Future[T] = {
+ val p = Promise[T]
- g onSuccess {
- case x => p.trySuccess(x)
- }
+ f.foreach { x =>
+ p.trySuccess(x)
+ }
- p.future
- }
+ g.foreach { x =>
+ p.trySuccess(x)
+ }
+
+ p.future
+}
+```
+
+{% endtab %}
+{% tab 'Scala 3' for=futures-16 %}
+
+```scala
+def first[T](f: Future[T], g: Future[T]): Future[T] =
+ val p = Promise[T]
+
+ f.foreach { x =>
+ p.trySuccess(x)
+ }
+
+ g.foreach { x =>
+ p.trySuccess(x)
+ }
+
+ p.future
+```
-注意，在这种实现方式中，如果f与g都不是成功的，那么`first(f, g)`将不会实现（即返回一个值或者返回一个异常）。
+{% endtab %}
+{% endtabs %}
+
+注意，在这种实现方式中，如果 `f` 和 `g` 都不成功，那么 `first(f, g)` 将不会完成（即返回一个值或者返回一个异常）。
+
+
## 工具(Utilities)
-为了简化在并发应用中处理时序(time)的问题，`scala.concurrent`引入了Duration抽象。Duration不是被作为另外一个通常的时间抽象存在的。他是为了用在并发(concurrency)库中使用的，Duration位于`scala.concurrent`包中。
+为了简化在并发应用中处理时序(time)的问题， `scala.concurrent` 引入了 `Duration` 抽象。`Duration` 不是被作为另外一个通常的时间抽象存在的。他是为了用在并发(concurrency)库中使用的，`Duration` 位于 `scala.concurrent` 包中。
+
+`Duration` 是表示时间长短的基础类，其可以是有限的或者无限的。有限的duration用 `FiniteDuration` 类来表示，并通过 `Long` 长度和 `java.util.concurrent.TimeUnit` 来构造。无限的 durations，同样扩展自 `Duration`，只在两种情况下存在，`Duration.Inf` 和 `Duration.MinusInf`。库中同样提供了一些 `Duration` 的子类用来做隐式的转换，这些子类不应被直接使用。
+
+抽象的 `Duration` 类包含了如下方法：
+
+1. 到不同时间单位的转换（`toNanos`，`toMicros`，`toMillis`，`toSeconds`，`toMinutes`，`toHours`，`toDays` 和 `toUnit(unit: TimeUnit)`）。
+2. durations的比较（`<`，`<=`，`>`和`>=`）。
+3. 算术运算符（`+`，`-`，`*`，`/`和 `unary_-`）
+4. `this` duration 与提供的参数之间的最大和最小的方法（`min`，`max`）。
+5. 检查 duration是否有限（`isFinite`）。
+
+`Duration` 能够用如下方法实例化（`instantiated`）：
+
+1. 通过 `Int` 和 `Long` 类型隐式转换，例如：`val d = 100 millis`。
+2. 通过传递一个 `Long` 长度和 `java.util.concurrent.TimeUnit`。例如：`val d = Duration(100, MILLISECONDS)`。
+3. 通过传递一个字符串来表示时间区间，例如： `val d = Duration("1.2 µs")`。
+
+Duration 也提供了 `unapply` 方法，因此可以被用于模式匹配中，例如：
+
+{% tabs futures-17 class=tabs-scala-version %}
+{% tab 'Scala 2' for=futures-17 %}
+
+```scala
+import scala.concurrent.duration._
+import java.util.concurrent.TimeUnit._
-Duration是表示时间长短的基础类，其可以是有限的或者无限的。有限的duration用FiniteDuration类来表示，并通过时间长度`(length)`和`java.util.concurrent.TimeUnit`来构造。无限的durations，同样扩展了Duration，只在两种情况下存在，`Duration.Inf`和`Duration.MinusInf`。库中同样提供了一些Durations的子类用来做隐式的转换，这些子类不应被直接使用。
+// instantiation
+val d1 = Duration(100, MILLISECONDS) // from Long and TimeUnit
+val d2 = Duration(100, "millis") // from Long and String
+val d3 = 100 millis // implicitly from Long, Int or Double
+val d4 = Duration("1.2 µs") // from String
-抽象的Duration类包含了如下方法：
+// pattern matching
+val Duration(length, unit) = 5 millis
+```
-到不同时间单位的转换`(toNanos, toMicros, toMillis, toSeconds, toMinutes, toHours, toDays and toUnit(unit: TimeUnit))`。
-durations的比较`(<，<=，>和>=)`。
-算术运算符`（+, -, *, / 和单值运算_-）`
-duration的最大最小方法`(min，max)`。
-测试duration是否是无限的方法`(isFinite)`。
-Duration能够用如下方法实例化`(instantiated)`：
+{% endtab %}
+{% tab 'Scala 3' for=futures-17 %}
-隐式的通过Int和Long类型转换得来 `val d = 100 millis`。
-通过传递一个`Long length`和`java.util.concurrent.TimeUnit`。例如`val d = Duration(100, MILLISECONDS)`。
-通过传递一个字符串来表示时间区间，例如 `val d = Duration("1.2 µs")`。
-Duration也提供了unapply方法，因此可以i被用于模式匹配中，例如：
+```scala
+import scala.concurrent.duration.*
+import java.util.concurrent.TimeUnit.*
- import scala.concurrent.duration._
- import java.util.concurrent.TimeUnit._
+// instantiation
+val d1 = Duration(100, MILLISECONDS) // from Long and TimeUnit
+val d2 = Duration(100, "millis") // from Long and String
+val d3 = 100.millis // implicitly from Long, Int or Double
+val d4 = Duration("1.2 µs") // from String
- // instantiation
- val d1 = Duration(100, MILLISECONDS) // from Long and TimeUnit
- val d2 = Duration(100, "millis") // from Long and String
- val d3 = 100 millis // implicitly from Long, Int or Double
- val d4 = Duration("1.2 µs") // from String
+// pattern matching
+val Duration(length, unit) = 5.millis
+```
- // pattern matching
- val Duration(length, unit) = 5 millis
+{% endtab %}
+{% endtabs %}
diff --git a/_zh-cn/overviews/core/implicit-classes.md b/_zh-cn/overviews/core/implicit-classes.md
index 6999f419aa..e7ec62cad1 100644
--- a/_zh-cn/overviews/core/implicit-classes.md
+++ b/_zh-cn/overviews/core/implicit-classes.md
@@ -61,7 +61,7 @@ Scala 2.10引入了一种叫做隐式类的新特性。隐式类指的是用impl
2. 构造函数只能携带一个非隐式参数。
````
- implicit class RichDate(date: java.util.Date) // 正确！
+ implicit class RichDate(date: java.time.LocalDate) // 正确！
implicit class Indexer[T](collecton: Seq[T], index: Int) // 错误！
implicit class Indexer[T](collecton: Seq[T])(implicit index: Index) // 正确！
````
diff --git a/_zh-cn/overviews/core/string-interpolation.md b/_zh-cn/overviews/core/string-interpolation.md
deleted file mode 100644
index eab9e4a742..0000000000
--- a/_zh-cn/overviews/core/string-interpolation.md
+++ /dev/null
@@ -1,119 +0,0 @@
----
-layout: singlepage-overview
-title: 字符串插值
-
-partof: string-interpolation
-
-language: zh-cn
----
-
-**Josh Suereth 著**
-
-## 简介
-
-自2.10.0版本开始，Scala提供了一种新的机制来根据数据生成字符串：字符串插值。字符串插值允许使用者将变量引用直接插入处理过的字面字符中。如下例：
-
- val name="James"
- println(s"Hello,$name")//Hello,James
-
-在上例中， s"Hello,$name" 是待处理字符串字面，编译器会对它做额外的工作。待处理字符串字面通过“号前的字符来标示（例如：上例中是s）。字符串插值的实现细节在 [SIP-11](https://docs.scala-lang.org/sips/pending/string-interpolation.html) 中有全面介绍。
-
-## 用法
-
-Scala 提供了三种创新的字符串插值方法：s,f 和 raw.
-
-### s 字符串插值器
-
-在任何字符串前加上s，就可以直接在串中使用变量了。你已经见过这个例子：
-
- val name="James"
- println(s"Hello,$name")//Hello,James
-此例中，$name嵌套在一个将被s字符串插值器处理的字符串中。插值器知道在这个字符串的这个地方应该插入这个name变量的值，以使输出字符串为Hello,James。使用s插值器，在这个字符串中可以使用任何在处理范围内的名字。
-
-字符串插值器也可以处理任意的表达式。例如：
-
- println(s"1+1=${1+1}")
-将会输出字符串1+1=2。任何表达式都可以嵌入到${}中。
-
-### f 插值器
-
-在任何字符串字面前加上 f，就可以生成简单的格式化串，功能相似于其他语言中的 printf 函数。当使用 f 插值器的时候，所有的变量引用都应当后跟一个printf-style格式的字符串，如%d。看下面这个例子：
-
- val height=1.9d
- val name="James"
- println(f"$name%s is $height%2.2f meters tall")//James is 1.90 meters tall
-f 插值器是类型安全的。如果试图向只支持 int 的格式化串传入一个double 值，编译器则会报错。例如：
-
- val height:Double=1.9d
-
- scala>f"$height%4d"
-
-
- Completed
--
- {% for sip in sips %}
- {% if sip.vote-status == "complete" or sip.vote-status == "accepted" %}
-
-
- {{ sip.title }}
- {{ sip.date | date: '%B %Y' }}-{{ site.data.sip-data[sip.vote-status].text }}-
- {% endif %}
- {% endfor %}
-
-
- Dormant
--
- {% for sip in sips %}
- {% if sip.vote-status == "dormant" %}
-
-
- {{ sip.title }}
- {{ sip.date | date: '%B %Y' }}-{{ site.data.sip-data[sip.vote-status].text }}-
- {% endif %}
- {% endfor %}
-
-
+## Completed SIPs
+
+Proposals that have been implemented in the compiler and that are available as a stable
+feature of the compiler (shipped), or that will be available in the next minor release
+of the compiler (accepted). Click on a proposal to read its content.
+
+Rejected
--
- {% for sip in sips %}
- {% if sip.vote-status == "rejected" %}
-
-
- {{ sip.title }}
- {{ sip.date | date: '%B %Y' }}-{{ site.data.sip-data[sip.vote-status].text }}-
- {% endif %}
- {% endfor %}
-
+
+
+## Rejected SIPs
+
+Proposals that have been rejected by the committee. Click on a proposal to read the
+corresponding discussions on GitHub.
+
+-
+ {% for sip in sips %}
+ {% if sip.stage == "completed" %}
+
-
+ {{ sip.title }}
+ {{ sipData[sip.status].text }}+
+ {% endif %}
+ {% endfor %}
+
+
+
+## Withdrawn SIPs
+
+Proposals that have been withdrawn by their authors. Click on a proposal to read the
+corresponding discussions on GitHub.
+
+-
+ {% for sip in sips %}
+ {% if sip.status == "rejected" %}
+
- + {{ sip.title }} + + {% endif %} + {% endfor %} +
+
diff --git a/_sips/index.md b/_sips/index.md
index 99c3a5264a..87dc975d0c 100644
--- a/_sips/index.md
+++ b/_sips/index.md
@@ -3,24 +3,17 @@ layout: sips
title: Scala Improvement Process
---
-
-Two separate processes govern changes to Scala:
-
-1. The **Scala Improvement Process** (SIP) covers changes to the Scala
+The **Scala Improvement Process** covers changes to the Scala
language, the Scala compiler, and the core of the Scala standard
library.
-2. The **Scala Platform Process** (SPP) aims to establish a stable
-collection of libraries suitable for widespread use, with a low barrier
-to entry for newcomers.
-
-## Scala Improvement Process (SIP)
+## Scala Improvement Process
-The **SIP** (_Scala Improvement Process_) is a process for submitting
+The _Scala Improvement Process_ is a process for submitting
changes to the Scala language. This process aims to evolve Scala
openly and collaboratively.
-The SIP process covers the Scala language and compiler and the core of
+The process covers the Scala language and compiler and the core of
the Scala standard library. (The core is anything that is unlikely to
be spun off into a separate module.)
@@ -28,14 +21,20 @@ A proposed change requires a design document, called a Scala
Improvement Proposal (SIP). The SIP committee meets monthly to
discuss, and eventually vote upon, proposals.
-A SIP is subject to a [review process](./sip-submission.html).
+A SIP is subject to a [review process]({% link _sips/process-specification.md %}).
Proposals normally include proposed changes to the
-[Scala language specification](https://www.scala-lang.org/files/archive/spec/2.12/).
+[Scala language specification](https://www.scala-lang.org/files/archive/spec/2.13/).
Before reaching the committee, a proposal normally receives community
discussion and review on the
[Scala Contributors](https://contributors.scala-lang.org/) forum.
-Please read [Submitting a SIP](./sip-submission.html) and our
-[SIP tutorial](./sip-tutorial.html) for more information.
+Please read the [SIP tutorial]({% link _sips/sip-tutorial.md %}) or
+[the process specification]({% link _sips/process-specification.md %}) for more
+information.
+
+The aim of the Scala Improvement Process is to apply the openness and
+collaboration that have shaped Scala's documentation and implementation to the
+process of evolving the language. The linked documents capture our guidelines,
+commitments and expectations regarding this process.
> Historical note: The SIP replaces the older SID (Scala Improvement Document) process.
> Completed SID documents remain available in the
diff --git a/_sips/meeting-results.md b/_sips/meeting-results.md
new file mode 100644
index 0000000000..4a44ee7c1b
--- /dev/null
+++ b/_sips/meeting-results.md
@@ -0,0 +1,32 @@
+---
+layout: sips
+title: SIP Meeting Results
+redirect_from: /sips/minutes-list.html
+---
+
+This page lists the results of every SIP meeting, starting from July 2016.
+
+### Meetings ###
+
+-
+ {% for sip in sips %}
+ {% if sip.status == "withdrawn" %}
+
- + {{ sip.title }} + + {% endif %} + {% endfor %} +
-
+ {% assign sips = site.sips | sort: 'date' | reverse %}
+ {% for page in sips %}
+ {% if page.partof == 'results' %}
+
- {{ page.date | date_to_long_string }} + {% endif %} + {% endfor %} +
-
+ {% assign sips = site.sips | sort: 'date' | reverse %}
+ {% for pg in sips %}
+ {% if pg.partof == 'minutes' %}
+
- {{ pg.title }} + {% endif %} + {% endfor %} +
-
- {% assign sips = site.sips | sort: 'date' | reverse %}
- {% for pg in sips %}
- {% if pg.partof == 'minutes' %}
-
- {{ pg.title }} - {% endif %} - {% endfor %} -
| Stage | +Purpose | +Entry criteria | +Post-entry changes expected | +
| Pre-SIP | +Gather initial community feedback and support. | +N/A. Opening a "Pre-SIP" post on the Scala Contributors forum can be done by anyone at any time | +N/A | +
| Design | +Make the case for the proposal. Make the design of the feature precise. Evaluate the solution among other possible solutions. Identify potential challenges. | +Community support was demonstrated in the Pre-SIP forum post. This is loosely defined. | +Major changes expected. | +
| Implementation | +Provide an Experimental implementation of the changes in the compiler. Evaluate how they hold up in practice. Get feedback from implementers and users. | +The SIP contains a precise specification for the changes and how they should interact with the rest of the language. + The Committee votes in favor of the SIP to be "Accepted for implementation". |
+ Minor changes based on feedback from implementers and early users. | +
| Completed | +Ship the feature. Once accepted, the feature will ship as stable in the next Minor release of the Scala language. | +A complete implementation, with tests, was merged in the mainline compiler and shipped as Experimental. Implementers do not have any concerns left wrt. the implementation of the feature and its interactions. + The Committee votes in favor of the SIP to be "Accepted". |
+ No changes allowed. | +
-
-
- The map method invokes f on every element and produces a StreamZipper of -the results. -
- The extract method returns the value at the cursor -
- The coflatMap method invokes f on every cursor (all possible zippers) providing a contextual global operation. -The result is a StreamZipper[B] of the results with a cursor pointing at the same location as this. - -
-
-
- Adding a new keyword to the language makes it more complex -
- Understanding the desugaring and concept behind cofor is not -trivial and it's much more complex than for (which many developers still -don't feel at ease with). -
line1
line2
` will result the following code:
-
-``` scala
-xml.tags.div(
- xml.attributes.title(xml.text("my-title")),
- xml.text("line1"),
- xml.tags.br(),
- xml.text("line2")
-)
-```
-
-With the help of this curried varargs proposal and `@inline`, we are able to implement an API to build a DOM tree with no additional overhead over manually written Scala code.
-
-``` scala
-import org.scalajs.dom.document
-import org.scalajs.dom.raw._
-
-object xml {
- type Attribute[-A <: Element] = A => Unit
- @inline def text(data: String) = data
- object attributes {
- @inline def title(value: String): Attribute[Element] = _.setAttribute("title", value)
- }
- object tags {
- class Builder[+E <: Element](private val element: E) extends AnyVal with Curried {
- @inline def applyBegin = this
- @inline def applyNext(text: String) = {
- element.appendChild(document.createTextNode(text))
- this
- }
- @inline def applyNext(node: Node) = {
- element.appendChild(node)
- this
- }
- @inline def applyNext[A <: Attribute[E]](attribute: A) = {
- attribute(element)
- this
- }
- @inline def applyEnd = element
- }
- @inline def div = new Builder(document.createElement("div"))
- @inline def br = new Builder(document.createElement("br"))
- }
-}
-```
-
-Since `xml.tags.div` returns a `Builder`, which is a subtype of `Curried`, calls on `xml.tags.div` will be translated to the curried form, as shown below:
-``` scala
-xml.tags.div
- .applyBegin
- .applyNext(xml.attributes.title(xml.text("my-title")))
- .applyNext(xml.text("line1"))
- .applyNext(xml.tags.br.applyBegin.applyEnd)
- .applyNext(xml.text("line2"))
- .applyEnd
-```
-
-When the above code is compiled in Scala.js, the builders should be eliminated entirely as a zero cost abstraction layer, and the output JavaScript is tiny as shown below:
-
-``` javascript
-var $$this = $m_Lorg_scalajs_dom_package$().document__Lorg_scalajs_dom_raw_HTMLDocument().createElement("div");
-$$this.setAttribute("title", "my-title");
-$$this.appendChild($m_Lorg_scalajs_dom_package$().document__Lorg_scalajs_dom_raw_HTMLDocument().createTextNode("line1"));
-var $$this$1 = $m_Lorg_scalajs_dom_package$().document__Lorg_scalajs_dom_raw_HTMLDocument().createElement("br");
-$$this.appendChild($$this$1);
-$$this.appendChild($m_Lorg_scalajs_dom_package$().document__Lorg_scalajs_dom_raw_HTMLDocument().createTextNode("line2"));
-```
-
-### Comparison Examples
-
-The `Builder` API can be also implemented in repeated parameters:
-
-``` scala
-import org.scalajs.dom.document
-import org.scalajs.dom.raw._
-
-object xml {
- type Attribute[-A <: Element] = A => Unit
- @inline def text(data: String) = data
- object attributes {
- @inline def title(value: String): Attribute[Element] = _.setAttribute("title", value)
- }
- object tags {
- class Builder[+E <: Element](private val element: E) extends AnyVal {
- @inline def apply(attributesAndChildren: Any*) = {
- attributesAndChildren.foreach {
- case text: String =>
- element.appendChild(document.createTextNode(text))
- case node: Node =>
- element.appendChild(node)
- case attribute: Attribute[E] =>
- attribute(element)
- }
- element
- }
- }
- @inline def div = new Builder(document.createElement("div"))
- @inline def br = new Builder(document.createElement("br"))
- }
-}
-```
-
-However, the Scala compiler is unable to optimize repeated parameters, as a result, the output JavaScript from Scala.js would look like the below code.
-
-``` javascript
-var $$this$1 = $m_Lorg_scalajs_dom_package$().document__Lorg_scalajs_dom_raw_HTMLDocument().createElement("div");
-var this$3 = $m_LScalaFiddle$xml$attributes$();
-var jsx$1 = new $c_sjsr_AnonFunction1().init___sjs_js_Function1((function($this, value) {
- return (function(x$1$2) {
- x$1$2.setAttribute("title", value)
- })
-})(this$3, "my-title"));
-var $$this = $m_Lorg_scalajs_dom_package$().document__Lorg_scalajs_dom_raw_HTMLDocument().createElement("br");
-var array = [jsx$1, "line1", $$this, "line2"];
-var i = 0;
-var len = $uI(array.length);
-while ((i < len)) {
- var index = i;
- var arg1 = array[index];
- if ($is_T(arg1)) {
- var x2 = $as_T(arg1);
- $$this$1.appendChild($m_Lorg_scalajs_dom_package$().document__Lorg_scalajs_dom_raw_HTMLDocument().createTextNode(x2))
- } else if ($uZ((arg1 instanceof $g.Node))) {
- $$this$1.appendChild(arg1)
- } else if ($is_F1(arg1)) {
- var x4 = $as_F1(arg1);
- x4.apply__O__O($$this$1)
- } else {
- throw new $c_s_MatchError().init___O(arg1)
- };
- i = ((1 + i) | 0)
-};
-```
-
-Despite of the type safety issue due to the usage of `Any`, the above code are inefficient:
-
-1. Unnecessary temporary object for the `xml.attributes.title(xml.text("my-title"))`.
-2. Unnecessary temporary `Seq` to hold repeated parameters.
-3. Unnecessary runtime type check for each argument.
-
-The similar issues can be found in many other usage of repeated parameters. For example, Scala string interpolation is inefficient due to its internal vararg function call, unless implementing it in a macro; Scala collection initializers (e.g. `List(1, 2, 3)`) create unnecessary temporary `Seq` before creating the desired collection.
-
-## Design
-
-This proposal introduces a new type `Curried` defined as following:
-
-``` scala
-trait Curried extends Any
-```
-
-When a function call `f(p1, p2, p3, ... pn)` is being type checked, the compiler will firstly look for `apply` method on `f`. If an applicable `apply` method is not found and `f` is a subtype of `Curried`, the compiler will convert the function call to curried form `f.applyBegin.applyNext(p1).applyNext(p2).applyNext(p3) ... .applyNext(pn).applyEnd`, and continue type checking the translated call.
-
-### Expanding sequence argument
-
-Optionally, some arguments to a `Curried` call may be a sequence argument marked as `_*`. Those are arguments should be translated to `applyNextSeq` calls instead of `applyNext`. For example, `f(p1, s1: _*, p2)` will be translated to the following code.
-
-``` scala
-f.applyBegin
- .applyNext(p1)
- .applyNextSeq(s1)
- .applyNext(p2)
-.applyEnd
-```
-
-Unlike traditional repeated parameters, which restrict the sequence argument at the last position, sequence arguments in a curried call are allowed at any position.
-
-### Builder type shifting
-
-The type of partially applied function might be changed during applying each argument. Given the following type signature:
-
-``` scala
-class ListBuilder[A] {
- def applyNext[B >: A](b: B): ListBuilder[B] = ???
- def applyNextSeq[B >: A](seqB: Seq[B]): ListBuilder[B] = ???
- def applyEnd: List[A] = ???
-}
-object List extends Curried {
- def applyBegin[A]: ListBuilder[A] = ???
-}
-```
-
-`List(42, "a")` should be translated to `List.applyBegin.applyNext(42).applyNext("a").applyEnd`. Then, the typer will infer type parameters as `List.applyBegin[Nothing].applyNext[Int](42).applyNext[Any]("a").applyEnd`, therefore the final return type of `applyEnd` will be `List[Any]`.
-
-### Explicit type parameters
-
-When a `Curried` is invoked with some type arguments, those type arguments will be moved to the `applyBegin` method. Therefore, `List[Int](1 to 3: _*)` should be translated to `List.applyBegin[Int].applyNextSeq(1 to 3).applyEnd`.
-
-### Implicit parameters
-
-A more common form of curried function call would be like `f(a)(b)(c)`. We prefer the explicit named method calls to `applyNext` instead of the common form, in order to support implicit parameters in `applyNext`. Therefore, each explicit parameter might come with an implicit parameter list, resolving the infamous [multiple type parameter lists](https://github.com/scala/bug/issues/4719) issue.
-
-### Multiple curried vararg parameter lists
-
-When a `Curried` is invoked with multiple parameter lists, for example:
-``` scala
-f(a, b, c)(d, e)
-```
-
-Then the first parameter list should be translated to a curried call:
-
-``` scala
-f.applyBegin
- .applyNext(a)
- .applyNext(b)
- .applyNext(c)
-.applyEnd(d, e)
-```
-
-`(d, e)` is translated to the curried form only if `applyEnd` returns a `Curried`.
-
-### Overloaded curried calls
-
-Curried varargs enables overloaded functions for each parameter. Parameters will not be erased to their common supertype.
-
-## Implementation
-
-This proposal can be implemented either in the Scala compiler or in a whitebox macro. [Curried.scala](https://github.com/Atry/Curried.scala) is an implementation of the proposal in a whitebox macro.
-
-## Alternatives
-
-### Repeated parameters
-
-Repeated parameters are packed into a `Seq`, which is then passed to the callee.
-
-#### Pros
-
-* Interoperable with Java
-
-#### Cons
-
-* Always boxing value class parameters
-* Unable to inline function parameters
-* Unable to inline call-by-name parameters
-* Unable to perform implicit conversion for each parameter
-* Unable to infer context bound for each parameter
-* Erasing all parameters to their common super type
-
-## Reference
-* [Existing Implementation (Curried.scala)](https://github.com/Atry/Curried.scala)
-* [Discussion on Scala Contributors forum](https://contributors.scala-lang.org/t/pre-sip-curried-varargs/3608)
-* [Pre SIP: name based XML literals](https://contributors.scala-lang.org/t/pre-sip-name-based-xml-literals/2175)
-* [Scala Language Specification - Repeated Parameters](https://scala-lang.org/files/archive/spec/2.13/04-basic-declarations-and-definitions.html#repeated-parameters)
diff --git a/_sips/sips/2019-10-24-name-based-xml.md b/_sips/sips/2019-10-24-name-based-xml.md
deleted file mode 100644
index 6389003fa9..0000000000
--- a/_sips/sips/2019-10-24-name-based-xml.md
+++ /dev/null
@@ -1,421 +0,0 @@
----
-layout: sip
-title: SIP-NN - Name Based XML Literals
-vote-status: pending
-permalink: /sips/:title.html
-redirect_from: /sips/pending/name-based-xml.html
----
-
-**By: Yang, Bo**
-
-## History
-
-| Date | Version |
-|---------------|---------------|
-| Oct 24th 2019 | Initial Draft |
-
-## Introduction
-
-Name-based `for` comprehension has been proven success in Scala language design. A `for` / `yield` expression will be converted to higher-order function calls to `flatMap` , `map` and `withFilter` methods, no matter which type signatures they are. The `for` comprehension can be used for either `Option` or `List` , even when `List` has an additional implicit `CanBuildFrom` parameter. Third-party libraries like Scalaz and Cats also provides `Ops` to allow monadic data types in `for` comprehension.
-
-[Name-based pattern matching](https://dotty.epfl.ch/docs/reference/changed-features/pattern-matching.html) is introduced by Dotty. It is greatly simplified the implementation compared to Scala 2. In addition, specific symbols in Scala library ( `Option` , `Seq` ) are decoupled from the Scala compiler.
-
-Considering the success of the above name-based syntactic sugars, in order to decouple `scala-xml` library from Scala compiler, name-based XML literal is an obvious approach.
-
-## Motivating Examples
-
-### Examples
-
-Given an XML literal `line2
line1
line2
`, at the parser phase, the compiler should internally convert it to an AST equivalent to the following code:
-
-``` scala
-xml.literal(
- xml.elements.div(
- xml.attributes.title(xml.values.`my-title`),
- xml.texts.line1,
- xml.elements.br(),
- xml.texts.line2
- )
-)
-```
-
-By creating or importing different implementation of `xml`, various representation of objects for the XML literal will be created. For example, to create HTML DOM in Scala.js, you can define `xml` object as following:
-
-``` scala
-import org.scalajs.dom.document
-import org.scalajs.dom.raw._
-
-object xml {
- type Attribute[-A <: Element] = A => Unit
- object values extends Dynamic {
- def selectDynamic(data: String) = data
- }
- object texts extends Dynamic {
- def selectDynamic(data: String) = data
- }
- object attributes {
- def title(value: String): Attribute[Element] = _.setAttribute("title", value)
- }
- object elements {
- class Builder[+E <: Element](val element: E) extends AnyVal {
- def apply(attributesAndChildren: Any*) = {
- attributesAndChildren.foreach {
- case text: String =>
- element.appendChild(document.createTextNode(text))
- case builder: Builder[_] =>
- element.appendChild(builder.element)
- case node: Node =>
- element.appendChild(node)
- case attribute: Attribute[E] =>
- attribute(element)
- }
- element
- }
- }
- def div = new Builder(document.createElement("div"))
- def br = new Builder(document.createElement("br"))
- def literal[+E <: Element](builder: Builder[E]) = builder.element
- }
-}
-```
-
-The ability of custom implementation for XML literals enables a lot of possibilities, including React-like virtual DOM frameworks, static type checked XML schema, and reactive XHTML/FXML templating.
-
-### Comparison Examples
-
-XML literals in Scala 2.13 are symbol based, which means the type of an XML literal is always `scala.xml.Elem`. The code `line2
line1
line2
` will be parsed to an AST equivalent to the following code:
-
-``` scala
-{
- var $md: MetaData = Null;
- $md = new UnprefixedAttribute("title", new Text("my-title"), $md);
- new Elem(null, "div", $md, TopScope, false, ({
- val $buf = new NodeBuffer();
- $buf.$amp$plus(new Text("line1"));
- $buf.$amp$plus({
- {
- new Elem(null, "br", Null, TopScope, true)
- }
- });
- $buf.$amp$plus(new Text("line2"));
- $buf
- }: _*))
-}
-```
-
-Note that `MetaData`, `UnprefixedAttribute`, `Text`, `Elem` and `TopScope` are types defined in `scala.xml`. Library authors cannot create their custom representation of XML literals.
-
-### Counter-Examples
-
-With the help of this proposal, a library author can create custom XML based DSL.
-
-``` scala
-
-```
-
-It will be translated to:
-
-``` scala
-xml.literal(
- xml.elements.div(
- xml.elements.label(
- xml.attributes.`v-if`(xml.interpolation(math.random() < 0.5)),
- xml.texts.`You might see me`
- )
- )
-)
-```
-
-The translated `v-if` method can be supported by creating an `implicit class` for `xml.attributes` easily. However, this proposal is not intended to be used for creating a DSL as an alternative to regular Scala code. Instead, you should just use ordinary `if` expression.
-
-``` scala
-line2
{
- if (math.random() < 0.5) {
-
- } else {
-
- }
-}
-```
-
-and it will be translated to:
-
-``` scala
-xml.literal(
- xml.elements.div(
- xml.interpolation {
- if (math.random() < 0.5) {
- xml.literal(
- xml.elements.label(
- xml.texts.`You might see me`
- )
- )
- } else {
- xml.literal(
- xml.comment("condition not met")
- )
- }
- }
- )
-)
-```
-
-Name based XML literal is best for modeling existing XML format within Scala source files. For other cases, just use ordinary Scala control flows for dynamic conditions, and use ordinary Scala case class for data structures not defined in the existing XML format.
-
-## Design
-
-### Goals
-
-* Keeping source-level backward compatibility to existing symbol-based XML literals in most use cases of `scala-xml`.
-* Allowing schema-aware XML literals, i.e. static type varying according to tag names, similar to the current TypeScript and [Binding.scala](https://github.com/ThoughtWorksInc/Binding.scala) behavior.
-* Schema-aware XML literals should be understandable by both the compiler and IDE (e.g. no white box macros involved).
-* Existing libraries like ScalaTags should be able to support XML literals by adding a few simple wrapper classes. No macro or meta-programming knowledge is required for library authors.
-* Able to implement an API to build a DOM tree with no more cost than manually written Scala code.
-
-### Non-goals
-
-* Embedding fully-featured standard XML in Scala.
-* Allowing arbitrary tag names and attribute names (or avoiding reserved word).
-* Distinguishing lexical differences, e.g. `` vs `` .
-
-### Other consideration
-#### White space only text
-
-Whitespace-only is preserved by default. However, a XML library vendor is able to discard whitespace texts during constructing the object for the XML literal.
-
-#### The usage of varargs
-
-Since an element might contain arbitrary number of child nodes, varargs are required to handle these child nodes. Unfortunately, traditional varargs are type unsafe as it erase all arguments to their common super type, inefficient as it creates a temporary `Seq` that is difficult to be eliminated by optimizer.
-
-Both problems can be resolved with the help of [Curried Varargs](https://docs.scala-lang.org/sips/curried-varargs.html), which is another SIP to address the type safety and performance issues in traditional varargs.
-
-## Other Examples
-
-### Self-closing tags without prefixes
-
-``` scala
-
+
+
+### Specification
+
+We must add `publicInBinary` to the standard library.
+
+```scala
+package scala.annotation
+
+final class publicInBinary extends scala.annotation.StaticAnnotation
+```
+
+#### `@publicInBinary` annotation
+
+* Only valid on `def`, `val`, `lazy val`, `var`, `object`, and `given`.
+* If a definition overrides a `@publicInBinary` definition, it must also be annotated with `@publicInBinary`.
+* TASTy will contain references to non-public definitions that are out of scope but `@publicInBinary`. TASTy already allows those references.
+* The annotated definitions will be public in the generated bytecode. Definitions should be made public as early as possible in the compiler phases, as this can remove the need to create other accessors. It should be done after we check the accessibility of references.
+
+#### Inline
+
+* Inlining will not require the generation of an inline accessor for binary APIs.
+* The user will be warned if a new inline accessor is automatically generated under `-WunstableInlineAccessors`.
+ The message will suggest `@publicInBinary` and how to fix potential incompatibilities.
+
+### Compatibility
+
+The introduction of the `@publicInBinary` do not introduce any binary incompatibility.
+
+Using references to `@publicInBinary` in inline code can cause binary incompatibilities. These incompatibilities are equivalent to the ones that can occur due to the unsoundness we want to fix. When migrating to binary APIs, the compiler will show the implementation of accessors that the users need to add to keep binary compatibility with pre-publicInBinary code.
+
+### Other concerns
+
+* Tools that analyze inlined TASTy code will need to know about `@publicInBinary`. For example [MiMa](https://github.com/lightbend/mima/) and [TASTy MiMa](https://github.com/scalacenter/tasty-mima).
+
+## Alternatives
+
+### Add a `@binaryAccessor`
+This annotation would generate an stable accessor. This annotation could be used on `private` definition. It would also mitigate [migration costs](https://gist.github.com/nicolasstucki/003f7293941836b08a0d53dbcb913e3c) for library authors that have published unstable accessors.
+
+* Implementation https://github.com/scala/scala3/pull/16992
+
+
+### Make all `private[C]` part of the binary API
+
+Currently, we already make `private[C]` public in the binary API but do not have the same guarantees regarding binary compatibility.
+For example, the following change is binary compatible but would remove the existence of the `private[C]` definition in the bytecode.
+```diff
+class C:
+- private[C] def f: T = ...
+```
+We could change the rules to make all `private[C]` part of binary compatible to flag such a change as binary incompatible. This would imply that all these
+methods can be accessed directly from inline methods without generating an accessor.
+
+The drawback of this approach is that that we would need to force users to keep their `private[C]` methods even if they never used inline methods.
+
+
+## Related work
+
+* Initial discussions: [https://github.com/scala/scala3/issues/16983](https://github.com/scala/scala3/issues/16983)
+* Initial proof of concept (outdated): [https://github.com/scala/scala3/pull/16992](https://github.com/scala/scala3/pull/16992)
+* Single annotation proof of concept: [https://github.com/scala/scala3/pull/18402](https://github.com/scala/scala3/pull/18402)
+* Community migration analysis: [Gist](https://gist.github.com/nicolasstucki/003f7293941836b08a0d53dbcb913e3c)
+* Kotlin: [PublishedApi](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-published-api/) plays the same role as `@publicInBinary`
+ but its interaction with (inline definitions)[https://kotlinlang.org/docs/inline-functions.html#restrictions-for-public-api-inline-functions]
+ is stricter as they do not support automatic accessor generation.
+
+
diff --git a/_sips/sips/2019-07-27-binary-integer-literals.md b/_sips/sips/binary-integer-literals.md
similarity index 94%
rename from _sips/sips/2019-07-27-binary-integer-literals.md
rename to _sips/sips/binary-integer-literals.md
index da803bd5ae..ef761601fb 100644
--- a/_sips/sips/2019-07-27-binary-integer-literals.md
+++ b/_sips/sips/binary-integer-literals.md
@@ -1,7 +1,8 @@
---
layout: sip
-title: SIP-NN - Support Binary Integer Literals
-vote-status: pending
+title: SIP-42 - Support Binary Integer Literals
+stage: completed
+status: shipped
permalink: /sips/:title.html
---
diff --git a/_sips/sips/2017-11-20-byname-implicits.md b/_sips/sips/byname-implicits.md
similarity index 99%
rename from _sips/sips/2017-11-20-byname-implicits.md
rename to _sips/sips/byname-implicits.md
index db735776a6..fd63269068 100644
--- a/_sips/sips/2017-11-20-byname-implicits.md
+++ b/_sips/sips/byname-implicits.md
@@ -1,11 +1,14 @@
---
layout: sip
-title: SIP-NN - Byname implicit arguments
-vote-status: pending
+title: SIP-31 - Byname implicit arguments
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/byname-implicits.html
---
+> This proposal has been implemented in Scala 2.13.0 and Scala 3.0.0.
+
**Author: Miles Sabin**
**Supervisor and advisor: Martin Odersky**
@@ -36,7 +39,7 @@ the knot" implicitly.
### Implementation status
-Byname implicits have been implemented in [Dotty](https://github.com/lampepfl/dotty/issues/1998)
+Byname implicits have been implemented in [Dotty](https://github.com/scala/scala3/issues/1998)
with an earlier iteration of the divergence checking algorithm described below. A full
implementation of this proposal exists as a [pull request](https://github.com/scala/scala/pull/6050)
relative to the 2.13.x branch of the Lightbend Scala compiler and it is scheduled to be included in
@@ -164,7 +167,7 @@ object Semigroup {
}
}
```
-
+
then we can manually write instances for, for example, tuples of types which have `Semigroup`
instances,
@@ -384,7 +387,7 @@ val showListInt: Show[List[Int]] =
showUnit
)
)
-```
+```
where at least one argument position between the val definition and the recursive occurrence of
`showListInt` is byname.
@@ -496,16 +499,16 @@ any _Tj_, where _i_ < _j_.
The essence of the algorithm described in the Scala Language Specification is as follows,
> Call the sequence of open implicit types _O_. This is initially empty.
->
-> To resolve an implicit of type _T_ given stack of open implicits _O_,
->
+>
+> To resolve an implicit of type _T_ given stack of open implicits _O_,
+>
> + Identify the definition _d_ which satisfies _T_.
->
+>
> + If the core type of _T_ dominates any element of _O_ then we have observed divergence and we're
> done.
->
+>
> + If _d_ has no implicit arguments then the result is the value yielded by _d_.
->
+>
> + Otherwise for each implicit argument _a_ of _d_, resolve _a_ against _O+T_, and the result is the
> value yielded by _d_ applied to its resolved arguments.
@@ -547,15 +550,15 @@ divergence check across the set of relevant implicit definitions.
This gives us the following,
-> To resolve an implicit of type _T_ given stack of open implicits _O_,
->
+> To resolve an implicit of type _T_ given stack of open implicits _O_,
+>
> + Identify the definition _d_ which satisfies _T_.
->
+>
> + If the core type of _T_ dominates the type _U_ of some element _With `-WunstableInlineAccessors -explain`
+ +~~~ +-- [E...] Compatibility Warning: C.scala ----------------------------- + | inline def foo: Int = a + b + c + d + | ^ + | Unstable inline accessor C$$inline$b was generated in class C. + |----------------------------------------------------------------------------- + | Explanation (enabled by `-explain`) + |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + | Access to non-public method b causes the automatic generation of an accessor. + | This accessor is not stable, its name may change or it may disappear + | if not needed in a future version. + | + | To make sure that the inlined code is binary compatible you must make sure that + | method b is public in the binary API. + | * Option 1: Annotate method b with @publicInBinary + | * Option 2: Make method b public + | + | This change may break binary compatibility if a previous version of this + | library was compiled with generated accessors. Binary compatibility should + | be checked using MiMa. If binary compatibility is broken, you should add the + | old accessor explicitly in the source code. The following code should be + | added to class C: + | @publicInBinary private[C] def C$$inline$b: Int = this.b + ----------------------------------------------------------------------------- +-- [E...] Compatibility Warning: C.scala ----------------------------- + | inline def foo: Int = a + b + c + d + | ^ + | Unstable inline accessor C$$inline$d was generated in class C. + |----------------------------------------------------------------------------- + | Explanation (enabled by `-explain`) + |- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + | Access to non-public method d causes the automatic generation of an accessor. + | This accessor is not stable, its name may change or it may disappear + | if not needed in a future version. + | + | To make sure that the inlined code is binary compatible you must make sure that + | method d is public in the binary API. + | * Option 1: Annotate method d with @publicInBinary + | * Option 2: Make method d public + | + | This change may break binary compatibility if a previous version of this + | library was compiled with generated accessors. Binary compatibility should + | be checked using MiMa. If binary compatibility is broken, you should add the + | old accessor explicitly in the source code. The following code should be + | added to class C: + | @publicInBinary private[C] def C$$inline$d: Int = this.d + ----------------------------------------------------------------------------- +~~~ + +
+
+~~~
+$> cat build.sc
+import mill._, scalalib._
+object proj extends ScalaModule {
+ def scalaVersion = "2.13.8"
+ def ivyDeps = Agg(
+ ivy"com.softwaremill.sttp.client3::core:3.8.3",
+ ivy"com.softwaremill.sttp.shared::ws:1.2.7",
+ )
+}
+$> mill show proj.runClasspath
+[1/1] show > [37/37] proj.runClasspath
+[
+ "qref:868554b6:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/client3/core_2.13/3.8.3/core_2.13-3.8.3.jar",
+ "qref:f3ba6af6:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/shared/ws_2.13/1.3.10/ws_2.13-1.3.10.jar",
+ "qref:438104da:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/org/scala-lang/scala-library/2.13.8/scala-library-2.13.8.jar",
+ "qref:0c9ef1ab:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/model/core_2.13/1.5.2/core_2.13-1.5.2.jar",
+ "qref:9b3d3f7d:/Users/luc/Library/Caches/Coursier/v1/https/repo1.maven.org/maven2/com/softwaremill/sttp/shared/core_2.13/1.3.10/core_2.13-1.3.10.jar"
+]
+~~~
+
+
+
+### Gradle
+
+Gradle handles the Scala library the same as other dependencies, so it already implements the behavior proposed by this SIP.
+
+
+
+~~~
+$> cat build.gradle
+plugins {
+ id 'scala'
+}
+repositories {
+ mavenCentral()
+}
+dependencies {
+ implementation 'org.scala-lang:scala-library:2.13.8'
+ implementation 'com.softwaremill.sttp.client3:core_2.13:3.8.3'
+ implementation 'com.softwaremill.sttp.shared:ws_2.13:1.2.7'
+}
+$> gradle dependencies --configuration runtimeClasspath
+
+> Task :dependencies
+
+------------------------------------------------------------
+Root project 'proj'
+------------------------------------------------------------
+
+runtimeClasspath - Runtime classpath of source set 'main'.
++--- org.scala-lang:scala-library:2.13.8 -> 2.13.10
++--- com.softwaremill.sttp.client3:core_2.13:3.8.3
+| +--- org.scala-lang:scala-library:2.13.10
+| +--- com.softwaremill.sttp.model:core_2.13:1.5.2
+| | \--- org.scala-lang:scala-library:2.13.8 -> 2.13.10
+| +--- com.softwaremill.sttp.shared:core_2.13:1.3.10
+| | \--- org.scala-lang:scala-library:2.13.9 -> 2.13.10
+| \--- com.softwaremill.sttp.shared:ws_2.13:1.3.10
+| +--- org.scala-lang:scala-library:2.13.9 -> 2.13.10
+| +--- com.softwaremill.sttp.shared:core_2.13:1.3.10 (*)
+| \--- com.softwaremill.sttp.model:core_2.13:1.5.2 (*)
+\--- com.softwaremill.sttp.shared:ws_2.13:1.2.7 -> 1.3.10 (*)
+
+(*) - dependencies omitted (listed previously)
+~~~
+
+
+
+### Maven
+
+Maven [does not update](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html) versions of dependencies that are explicitly listed in the `pom.xml` file, so it's possible to run into linkage errors at run time already now.
+The maven versions plugin can display and update dependencies to newer versions.
+
+
+
+~~~
+$> cat pom.xml
+
+
+ 4.0.0
+ a.b
+ proj
+ 1.0.0-SNAPSHOT
+
+ UTF-8
+ UTF-8
+ 1.8
+ 2.13.8
+
+
+
+ org.scala-lang
+ scala-library
+ ${scala.version}
+
+
+ com.softwaremill.sttp.client3
+ core_2.13
+ 3.8.3
+
+
+ com.softwaremill.sttp.shared
+ ws_2.13
+ 1.2.7
+
+
+
+
+
+ net.alchim31.maven
+ scala-maven-plugin
+ 4.8.0
+
+
+
+
+$> mvn dependency:build-classpath
+[INFO] --- maven-dependency-plugin:2.8:build-classpath (default-cli) @ proj ---
+[INFO] Dependencies classpath:
+/Users/luc/.m2/repository/org/scala-lang/scala-library/2.13.8/scala-library-2.13.8.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/client3/core_2.13/3.8.3/core_2.13-3.8.3.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/model/core_2.13/1.5.2/core_2.13-1.5.2.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/shared/core_2.13/1.3.10/core_2.13-1.3.10.jar:/Users/luc/.m2/repository/com/softwaremill/sttp/shared/ws_2.13/1.2.7/ws_2.13-1.2.7.jar
+$> mvn versions:display-dependency-updates
+[INFO] --- versions-maven-plugin:2.13.0:display-dependency-updates (default-cli) @ proj ---
+[INFO] The following dependencies in Dependencies have newer versions:
+[INFO] com.softwaremill.sttp.client3:core_2.13 ............... 3.8.3 -> 3.8.5
+[INFO] com.softwaremill.sttp.shared:ws_2.13 ................. 1.2.7 -> 1.3.12
+[INFO] org.scala-lang:scala-library ....................... 2.13.8 -> 2.13.10
+~~~
+
+
+
+### Bazel
+
+I have never used bazel and did not manage set up / find a sample build definition to test its behavior.
+Help from someone knowing bazel would be appreciated.
+
+### Pants
+
+As with bazel, I did not yet manage to set up / find an example project.
+
+### Other Tools
+
+The SIP might also require changes in other tools such as scala-cli, coursier or bloop.
diff --git a/_sips/sips/2009-06-02-early-member-definitions.md b/_sips/sips/early-member-definitions.md
similarity index 73%
rename from _sips/sips/2009-06-02-early-member-definitions.md
rename to _sips/sips/early-member-definitions.md
index 06adf76c50..244b7c15b3 100644
--- a/_sips/sips/2009-06-02-early-member-definitions.md
+++ b/_sips/sips/early-member-definitions.md
@@ -1,8 +1,8 @@
---
layout: sip
title: SID-4 - Early Member Definitions
-vote-status: complete
-vote-text: This SIP has already been accepted and completed.
+stage: completed
+status: shipped
permalink: /sips/:title.html
redirect_from: /sips/pending/early-member-definitions.html
---
diff --git a/_sips/sips/eference-able-package-objects.md b/_sips/sips/eference-able-package-objects.md
new file mode 100644
index 0000000000..cfba956529
--- /dev/null
+++ b/_sips/sips/eference-able-package-objects.md
@@ -0,0 +1,7 @@
+---
+title: 'SIP-68: Reference-able Package Objects'
+status: under-review
+pull-request-number: 100
+stage: implementation
+
+---
diff --git a/_sips/sips/fewer-braces.md b/_sips/sips/fewer-braces.md
new file mode 100644
index 0000000000..321f665233
--- /dev/null
+++ b/_sips/sips/fewer-braces.md
@@ -0,0 +1,296 @@
+---
+layout: sip
+permalink: /sips/:title.html
+stage: completed
+status: shipped
+title: SIP-44 - Fewer Braces
+---
+
+**By: Martin Odersky**
+
+## History
+
+| Date | Version |
+|----------------|--------------------|
+| July 1st 2022 | Initial Draft |
+| July 21st 2022 | Expanded Other Conerns Section |
+
+## Summary
+
+The current state of Scala 3 makes braces optional around blocks and template definitions (i.e. bodies of classes, objects, traits, enums, or givens). This SIP proposes to allow optional braces also for function arguments.
+The advantages of doing so is that the language feels more systematic, and programs become typographically cleaner.
+The changes have been implemented and and made available under the language import `language.experimental.fewerBraces`. The proposal here is to make them available without a language import instead.
+
+
+## Motivation
+
+After extensive experience with the current indentation rules I conclude that they are overall a big success.
+However, they still feel incomplete and a bit unsystematic since we can replace `{...}` in the majority of situations, but there are also important classes of situations where braces remain mandatory. In particular, braces are currently needed around blocks as function arguments.
+
+It seems very natural to generalize the current class syntax indentation syntax to function arguments. In both cases, an indentation block is started by a colon at the end of a line. Doing so will bring two major benefits:
+
+ - Better _consistency_, since we avoid the situation where braces are sometimes optional and in other places mandatory.
+ - Better _readability_ in many common use cases, similar to why current
+ optional braces lead to better readability.
+
+## Proposed solution
+
+The proposed solution is described in detail in https://dotty.epfl.ch/docs/reference/other-new-features/indentation.html#variant-indentation-marker--for-arguments. I inline the relevant sections here:
+
+First, here is the spec for colons at ends of lines for template bodies. This is part of official Scala 3. I cited it here for context.
+
+> A template body can alternatively consist of a colon followed by one or more indented statements. To this purpose we introduce a new ``println(i)`
`}` | ทำความเข้าใจ for : ทำซ้ำโดยละเว้นขอบเขตบน | | จับคู่รูปแบบ | | | Good
`(xs zip ys) map { case (x,y) => x*y }`
Bad
`(xs zip ys) map( (x,y) => x*y )` | ใช้ case ใน arg ของฟังก์ชันสำหรับ จับคู่รูปแบบ (pattern maching) | -| Bad
`val v42 = 42`
`Some(3) match {`
` case Some(v42) => println("42")`
` case _ => println("Not 42")`
`}` | "v42" ถูกตีความว่าเป็นชื่อที่ตรงกับค่า Int และพิมพ์ "42" | -| Good
`val v42 = 42`
`Some(3) match {`
`` case Some(`v42`) => println("42")``
`case _ => println("Not 42")`
`}` | "v42" กับ backticks ถูกตีความว่าเป็น v42 val ที่มีอยู่และ
พิมพ์ "Not 42" | -| Good
`val UppercaseVal = 42`
`Some(3) match {`
` case Some(UppercaseVal) => println("42")`
` case _ => println("Not 42")`
`}` | UppercaseVal ถือว่าเป็น val ที่มีอยู่ไม่ใช่ตัวแปรรูปแบบใหม่
เพราะมันเริ่มต้นด้วยตัวอักษรตัวพิมพ์ใหญ่ ดังนั้นค่าที่มีอยู่ใน
UppercaseVal จะถูกตรวจสอบเทียบกับ 3 และพิมพ์ "Not 42" | +| Bad
`val v42 = 42`
`Some(3) match {`
` case Some(v42) => println("42")`
` case _ => println("Not 42")`
`}` | "v42" ถูกตีความว่าเป็นชื่อที่ตรงกับค่า Int และแสดงค่า "42" | +| Good
`val v42 = 42`
`Some(3) match {`
`` case Some(`v42`) => println("42")``
`case _ => println("Not 42")`
`}` | "v42" กับ backticks ถูกตีความว่าเป็น v42 val ที่มีอยู่และ
แสดงค่า "Not 42" | +| Good
`val UppercaseVal = 42`
`Some(3) match {`
` case Some(UppercaseVal) => println("42")`
` case _ => println("Not 42")`
`}` | UppercaseVal ถือว่าเป็น val ที่มีอยู่ไม่ใช่ตัวแปรรูปแบบใหม่
เพราะมันเริ่มต้นด้วยตัวอักษรตัวพิมพ์ใหญ่ ดังนั้นค่าที่มีอยู่ใน
UppercaseVal จะถูกตรวจสอบเทียบกับ 3 และแสดงค่า "Not 42" | | การใช้งาน object | | | `class C(x: R)` _เหมือนกับ_
`class C(private val x: R)`
`var c = new C(4)` | ตัวสร้างพารามิเตอร์ - x มีเฉพาะในคลาส body เท่านั้น | | `class C(val x: R)`
`var c = new C(4)`
`c.x` | ตัวสร้างพารามิเตอร์ - กำหนดสมาชิกสาธารณะโดยอัตโนมัติ | diff --git a/_th/tour/automatic-closures.md b/_th/tour/automatic-closures.md deleted file mode 100644 index 1c30b693a9..0000000000 --- a/_th/tour/automatic-closures.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: tour -title: Automatic Closures -partof: scala-tour - -language: th ---- diff --git a/_th/tour/basics.md b/_th/tour/basics.md index 48c285511e..273161fd6a 100644 --- a/_th/tour/basics.md +++ b/_th/tour/basics.md @@ -15,16 +15,14 @@ In this page, we will cover basics of Scala. ## ทดลอง Scala ในเว็บบราวเซอร์ -เราสามารถรัน Scala ในเว็บเบราว์เซอร์ด้วย ScalaFiddle +เราสามารถรัน Scala ในเว็บเบราว์เซอร์ด้วย Scastie -1. ไปที่ [https://scalafiddle.io](https://scalafiddle.io). +1. ไปที่ [Scastie](https://scastie.scala-lang.org/). 2. วาง `println("Hello, world!")` ในด้านซ้าย. 3. กดที่ปุ่ม "Run" . output จะแสดงในด้านขวา ในขั้นตอนนี้ง่ายมาก ที่จะได้ประสบการณ์ของเรากับ Scala -หลายๆ โค้ดตัวอย่างในเอกสารนี้จะฝังใน ScalaFiddle ซึ่งคุณสามารถกดที่ปุ่ม Run เพื่อดูว่าโด้นนั้นๆ จะได้ผลลัพธ์อย่างไร - ## Expressions Expression หรือ นิพจน์ เป็นโค้ดที่ทำการคำนวนได้ @@ -33,14 +31,12 @@ Expression หรือ นิพจน์ เป็นโค้ดที่ท ``` เราสามารถแสดงผลลัพธ์ของ Expression ด้วยการใช้ `println` -{% scalafiddle %} ```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! println("Hello," + " world!") // Hello, world! ``` -{% endscalafiddle %} ### Values @@ -111,21 +107,17 @@ function เป็น expression ที่รับ parameter ได้ เราสามารถตั้งชื่อของ function ได้ดังนี้ -{% scalafiddle %} ```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -{% endscalafiddle %} function สามารถรับ parameter ได้หลายตัว -{% scalafiddle %} ```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} หรือ เราจะไม่รับ parameter เลยก็ได้ @@ -140,23 +132,19 @@ Method มีลักษณะเหมือนกับ function มาก Method จะประกาศได้ด้วย keyword `def` ตามด้วยชื่อของ function, รายการ parameter, return type และ body ของ function -{% scalafiddle %} ```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} สังเกตว่า การ return type จะประกาศ _หลังจาก_ รายการ parameter และ colon `: Int` Method ยังสามารถรับรายการ parameter ได้หลายรายการ -{% scalafiddle %} ```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -{% endscalafiddle %} หรือ ไม่มีรายการ parameter เลยก็ได้ อย่างเช่น @@ -169,7 +157,6 @@ println("Hello, " + name + "!") Method สามารถมี expression ได้หลายบรรทัด -{% scalafiddle %} ```scala mdoc def getSquareString(input: Double): String = { val square = input * input @@ -177,7 +164,6 @@ def getSquareString(input: Double): String = { } println(getSquareString(2.5)) // 6.25 ``` -{% endscalafiddle %} expression สุดท้ายใน body เป็น expression ที่ return value ของ method (Scala ก็มี keyword `return` แต่ว่าไม่ค่อยได้ใช้) @@ -222,15 +208,15 @@ val yetAnotherPoint = Point(2, 2) ```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) and Point(1,2) are the same. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) and Point(2,2) are different. ``` @@ -277,7 +263,6 @@ trait Greeter { Trait สามารถมี default implementation ได้ -{% scalafiddle %} ```scala mdoc:reset trait Greeter { def greet(name: String): Unit = @@ -302,7 +287,6 @@ greeter.greet("Scala developer") // Hello, Scala developer! val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` -{% endscalafiddle %} จากตัวอย่างนี้ `defaultGreeter` ขยายเพียง trait เดียว แต่มันสามารถขยายหลาย trait @@ -310,7 +294,7 @@ customGreeter.greet("Scala developer") // How are you, Scala developer? ## Main Method -main method เป็น entry point หรือจุดเริ่มต้นของโปรแกรม ใน Java Virtual Machine +main method เป็น entry point หรือจุดเริ่มต้นของโปรแกรม ใน Java Virtual Machine ต้องการ main method ชื่อว่า `main` และสามารถรับ argument ที่เป็น array ของ string ใช้ object เราสามารถประกาศ main method ได้ดังนี้: diff --git a/_th/tour/classes.md b/_th/tour/classes.md index 7800a5f492..3054dbcc8d 100644 --- a/_th/tour/classes.md +++ b/_th/tour/classes.md @@ -11,7 +11,7 @@ next-page: traits previous-page: unified-types --- -คลาสใน Scala เป็นพิมพ์เขียวสำหรับสร้าง object ในคลาสสามารถมี method, value, ตัวแปร, type, object, +คลาสใน Scala เป็นพิมพ์เขียวสำหรับสร้าง object ในคลาสสามารถมี method, value, ตัวแปร, type, object, trait และคลาส ซึ่งเรียกรวมๆ กันว่า _members_ หรือ _สมาชิก_ ของคลาส type, object และ trait จะกล่าวถึงภายหลัง ## การกำหนดคลาส @@ -22,7 +22,7 @@ class User val user1 = new User ``` -keyword `new` ใช้เพื่อสร้าง instance ของคลาส `User` มี constructor เริ่มต้นซึ่งไม่รับค่า argument เพราะว่าไม่ได้กำหนด constructor ไว้ตอนประกาสคลาส +keyword `new` ใช้เพื่อสร้าง instance ของคลาส `User` มี constructor เริ่มต้นซึ่งไม่รับค่า argument เพราะว่าไม่ได้กำหนด constructor ไว้ตอนประกาสคลาส อย่างไรก็ตาม, เราอาจจะมี constructor และ body ของคลาส ตัวอย่างดังนี้ เป็นการประกาศคลาสสำหรับจุด (point): @@ -41,11 +41,11 @@ class Point(var x: Int, var y: Int) { val point1 = new Point(2, 3) point1.x // 2 -println(point1) // พิมพ์ (2, 3) +println(point1) // แสดงค่า (2, 3) ``` คลาส `Point` นี้มีสมาชิก 4 ตัว คือ ตัวแปร `x` และ `y` และ method `move` และ `toString` -ไม่เหมือนภาษาอื่นๆ, ซึ่ง constructor หลักจะอยู่ใน class signature `(var x: Int, var y: Int)` +ไม่เหมือนภาษาอื่นๆ, ซึ่ง constructor หลักจะอยู่ใน class signature `(var x: Int, var y: Int)` method `move` รับ argument ชนิดตัวเลข 2 ตัว และ return เป็นค่า Unit `()` ซึ่งไม่มีค่า จะมีผลลัพธ์คลายกับ `void` ในภาษาที่เหมือน Java, `toString` ในทางกลับกัน ไม่รับ argument ใดๆ แต่ return เป็นค่า `String` ซึ่งแทนที่ method `toString` จาก [`AnyRef`](unified-types.html) โดยจะมี keyword `override` @@ -58,7 +58,7 @@ class Point(var x: Int = 0, var y: Int = 0) val origin = new Point // x and y are both set to 0 val point1 = new Point(1) -println(point1.x) // พิมพ์ 1 +println(point1.x) // แสดงค่า 1 ``` @@ -68,13 +68,13 @@ println(point1.x) // พิมพ์ 1 ```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val point2 = new Point(y=2) -println(point2.y) // พิมพ์ 2 +println(point2.y) // แสดงค่า 2 ``` นี้เป็นวิธีปฏิบัติที่ดีเพื่อจะทำให้โค้ดชัดเจนมากขึ้น ## Private Members และ Getter/Setter -สมาชิกของคลาสจะเป็น public โดยค่าเริ่มต้น ใช้ access modifier `private` +สมาชิกของคลาสจะเป็น public โดยค่าเริ่มต้น ใช้ access modifier `private` เพื่อซ่อนสมาชิกนั้นจากภายนอกของคลาส ```scala mdoc:reset class Point { @@ -97,10 +97,10 @@ class Point { val point1 = new Point point1.x = 99 -point1.y = 101 // พิมพ์คำเตือน warning +point1.y = 101 // แสดงค่า "WARNING: Out of bounds" ``` -คลาส `Point` เวอร์ชันนี้ ข้อมูลจะถูกเก็บไว้ในตัวแปรชนิด private ที่ชื่อว่า `_x` และ `_y` และมี method ที่ชื่อว่า `def x` และ `def y` ทีจะใช้ในการเข้าถึงข้อมูล private เป็น getter, `def x_=` และ `def y=` -เป็น method สำหรับตรวจสอบข้อมูลและ setting ค่าของตัวแปร `_x` และ `_y` +คลาส `Point` เวอร์ชันนี้ ข้อมูลจะถูกเก็บไว้ในตัวแปรชนิด private ที่ชื่อว่า `_x` และ `_y` และมี method ที่ชื่อว่า `def x` และ `def y` ทีจะใช้ในการเข้าถึงข้อมูล private เป็น getter, `def x_=` และ `def y=` +เป็น method สำหรับตรวจสอบข้อมูลและ setting ค่าของตัวแปร `_x` และ `_y` สังเกตว่า syntax พิเศษนี้สำหรับ setter: คือ method ที่ตามด้วย `_=` ไปยังตัวระบุของ setter และ parameter ตามหลังมา constructor หลักกำหนด parameter ด้วย `val` และ `var` เป็น public อย่างไรก็ตามเพราะว่า `val` เป็นตัวแปรที่เปลี่ยนแปลงไม่ได้ (immutable) เราไม่สามารถเขียบแบบนี้ได้ diff --git a/_th/tour/named-arguments.md b/_th/tour/named-arguments.md index 161b53b50e..0257732c5d 100644 --- a/_th/tour/named-arguments.md +++ b/_th/tour/named-arguments.md @@ -10,3 +10,56 @@ language: th next-page: packages-and-imports previous-page: default-parameter-values --- + +เมื่อเราเรียกใช้ method แล้วเราสามารถระบุชื่อ argument (label the argument) สำหรับ parameter ใดๆ ได้ดังนี้: + +{% tabs named-arguments-when-good %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-good %} + +```scala mdoc +def printName(first: String, last: String): Unit = + println(s"$first $last") + +printName("John", "Public") // แสดงค่า "John Public" +printName(first = "John", last = "Public") // แสดงค่า "John Public" +printName(last = "Public", first = "John") // แสดงค่า "John Public" +printName("Elton", last = "John") // แสดงค่า "Elton John" +``` + +{% endtab %} + +{% endtabs %} + +named argument นั้นมีประโยชน์เมื่อ parameter 2 ตัวมี type เดียวกัน\ +ทำให้ argument ที่เราส่งไปให้ function อาจถูกสลับกันโดยไม่ได้ตั้งใจ + +สังเกตว่าเราจะเขียน argument ที่ระบุชื่อในลำดับใดก็ได้\ +แต่ถ้า argument ไม่ได้อยู่ในลำดับของ parameter ใน function จากซ้ายไปขวา แล้ว argument ที่เหลือจะต้องระบุชื่อทั้งหมด + +ในตัวอย่างข้างล่างนี้ named argument ทำให้เราสามารถเว้น parameter `middle` ได้\ +แต่ในกรณีที่เกิด `error: positional after named argument`\ +เนื่องจาก argument ตัวแรกไม่ได้เรียงตามลำดับของ parameter (ตัวแรกไม่ใช่ parameter `first` และ argument ตัวที่ 2 เป็นต้นไปก็ไม่ได้ระบุชื่อด้วย)\ +ดังนั้น เราจะต้องระบุชื่อ argument ตั้งแต่ตัวที่ 2 เป็นต้นไป + +{% tabs named-arguments-when-error %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-error %} + +```scala mdoc:fail +def printFullName(first: String, middle: String = "Q.", last: String): Unit = + println(s"$first $middle $last") + +printFullName(first = "John", last = "Public") // แสดงค่า "John Q. Public" +printFullName("John", last = "Public") // แสดงค่า "John Q. Public" +printFullName("John", middle = "Quincy", "Public") // แสดงค่า "John Quincy Public" +printFullName(last = "Public", first = "John") // แสดงค่า "John Q. Public" +printFullName(last = "Public", "John") // error: positional after named argument +``` + +{% endtab %} + +{% endtabs %} + +เราสามารถใช้ Named Argument กับการเรียกใช้ method ของ Java ได้\ +แต่ทำได้เฉพาะในกรณีที่ Java library นั้นถูกคอมไพล์ด้วยออพชั่น `-parameters` เท่านั้น diff --git a/_th/tour/tour-of-scala.md b/_th/tour/tour-of-scala.md index f10a88d77d..ab75a7d541 100644 --- a/_th/tour/tour-of-scala.md +++ b/_th/tour/tour-of-scala.md @@ -13,7 +13,7 @@ next-page: basics ## ยินดีต้อนรับสู่การเดินทาง การเดินทางครั้งนี้ประกอบด้วยการแนะนำแบบสั้นๆ สำหรับแต่ล่ะคุณสมบัติของ Scala ที่ใช้บ่อยที่สุด และมีมีความตั้งใจเพื่อสำหรับผู้ที่เรียนรู้ภาษา Scala ใหม่ -และนี่ก็เป็นเพียงบทความสั้นๆ ที่ไม่ใช้การสอนเต็มรูปแบบของภาษา Scala หากต้องการเรียนรู้มากขึ้นให้พิจารณา[หนังสือ](/books.html) หรือขอคำปรึกษาจาก[แหล่งอื่นๆ](/learn.html) +และนี่ก็เป็นเพียงบทความสั้นๆ ที่ไม่ใช้การสอนเต็มรูปแบบของภาษา Scala หากต้องการเรียนรู้มากขึ้นให้พิจารณา[หนังสือ](/books.html) หรือขอคำปรึกษาจาก[แหล่งอื่นๆ](/online-courses.html) ## อะไรคือ Scala? Scala เป็นภาษาเขียนโปรแกรมแบบหลากหลายกระบวนทัศน์ที่ทันสมัย ที่ออกแบบมาเพื่อแสดงรูปแบบการเขียนโปรแกรมโดยทั่วไปที่กระชับ สง่างาม และมีชนิดข้อมูลที่ปลอดภัย (type-safe) ซึ่งผสานคุณสมบัติของภาษาเชิงวัตถุและภาษาเชิงฟังก์ชัน diff --git a/_th/tour/traits.md b/_th/tour/traits.md index dfc3b31a74..92dc07597c 100644 --- a/_th/tour/traits.md +++ b/_th/tour/traits.md @@ -75,7 +75,7 @@ val cat = new Cat("Sally") val animals = ArrayBuffer.empty[Pet] animals.append(dog) animals.append(cat) -animals.foreach(pet => println(pet.name)) // พิมพ์ Harry Sally +animals.foreach(pet => println(pet.name)) // แสดงค่า Harry Sally ``` -`trait Pet` มี abstract field `name` ซึ่ง implement โดย Cat และ Dog ใน constructor ของมัน +`trait Pet` มี abstract field `name` ซึ่ง implement โดย Cat และ Dog ใน constructor ของมัน ในบรรทัดสุดท้าย เราเรียก `pet.name` ซึ่งจะต้องถูก implement แล้วใน subtype ใดๆ ของ trait `Pet` diff --git a/_th/tour/unified-types.md b/_th/tour/unified-types.md index 7e92c8a39f..4c2b24c48a 100644 --- a/_th/tour/unified-types.md +++ b/_th/tour/unified-types.md @@ -57,7 +57,7 @@ Value type สามารถแปลได้ด้วยวิธีดัง ```scala mdoc val x: Long = 987654321 -val y: Float = x // 9.8765434E8 (หมายเหตุว่าค่าความละเอียดจะสูญหายไปในกรณีนี้) +val y: Float = x.toFloat // 9.8765434E8 (หมายเหตุว่าค่าความละเอียดจะสูญหายไปในกรณีนี้) val face: Char = '☺' val number: Int = face // 9786 @@ -67,7 +67,7 @@ val number: Int = face // 9786 ``` val x: Long = 987654321 -val y: Float = x // 9.8765434E8 +val y: Float = x.toFloat // 9.8765434E8 val z: Long = y // ไม่เป็นไปตามที่ต้องการ ``` diff --git a/_tour/abstract-type-members.md b/_tour/abstract-type-members.md index 8cad19b617..aef46a52b2 100644 --- a/_tour/abstract-type-members.md +++ b/_tour/abstract-type-members.md @@ -8,22 +8,37 @@ previous-page: inner-classes topics: abstract type members prerequisite-knowledge: variance, upper-type-bound -redirect_from: "/tutorials/tour/abstract-types.html" -redirect_from: "/tour/abstract-types.html" +redirect_from: + - "/tutorials/tour/abstract-types.html" + - "/tour/abstract-types.html" --- Abstract types, such as traits and abstract classes, can in turn have abstract type members. This means that the concrete implementations define the actual types. Here's an example: +{% tabs abstract-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_1 %} ```scala mdoc trait Buffer { type T val element: T } ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_1 %} +```scala +trait Buffer: + type T + val element: T +``` +{% endtab %} +{% endtabs %} + Here we have defined an abstract `type T`. It is used to describe the type of `element`. We can extend this trait in an abstract class, adding an upper-type-bound to `T` to make it more specific. +{% tabs abstract-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_2 %} ```scala mdoc abstract class SeqBuffer extends Buffer { type U @@ -31,29 +46,61 @@ abstract class SeqBuffer extends Buffer { def length = element.length } ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_2 %} +```scala +abstract class SeqBuffer extends Buffer: + type U + type T <: Seq[U] + def length = element.length +``` +{% endtab %} +{% endtabs %} + Notice how we can use yet another abstract type `U` in the specification of an upper-type-bound for `T`. This `class SeqBuffer` allows us to store only sequences in the buffer by stating that type `T` has to be a subtype of `Seq[U]` for a new abstract type `U`. Traits or [classes](classes.html) with abstract type members are often used in combination with anonymous class instantiations. To illustrate this, we now look at a program which deals with a sequence buffer that refers to a list of integers: +{% tabs abstract-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_3 %} ```scala mdoc abstract class IntSeqBuffer extends SeqBuffer { type U = Int } - def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = new IntSeqBuffer { - type T = List[U] - val element = List(elem1, elem2) - } + type T = List[U] + val element = List(elem1, elem2) + } val buf = newIntSeqBuf(7, 8) println("length = " + buf.length) println("content = " + buf.element) ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_3 %} +```scala +abstract class IntSeqBuffer extends SeqBuffer: + type U = Int + +def newIntSeqBuf(elem1: Int, elem2: Int): IntSeqBuffer = + new IntSeqBuffer: + type T = List[U] + val element = List(elem1, elem2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% endtabs %} + Here the factory `newIntSeqBuf` uses an anonymous class implementation of `IntSeqBuffer` (i.e. `new IntSeqBuffer`) to set the abstract type `T` to the concrete type `List[Int]`. It is also possible to turn abstract type members into type parameters of classes and vice versa. Here is a version of the code above which only uses type parameters: +{% tabs abstract-types_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=abstract-types_4 %} ```scala mdoc:nest abstract class Buffer[+T] { val element: T @@ -71,5 +118,24 @@ val buf = newIntSeqBuf(7, 8) println("length = " + buf.length) println("content = " + buf.element) ``` +{% endtab %} +{% tab 'Scala 3' for=abstract-types_4 %} +```scala +abstract class Buffer[+T]: + val element: T + +abstract class SeqBuffer[U, +T <: Seq[U]] extends Buffer[T]: + def length = element.length + +def newIntSeqBuf(e1: Int, e2: Int): SeqBuffer[Int, Seq[Int]] = + new SeqBuffer[Int, List[Int]]: + val element = List(e1, e2) + +val buf = newIntSeqBuf(7, 8) +println("length = " + buf.length) +println("content = " + buf.element) +``` +{% endtab %} +{% endtabs %} Note that we have to use [variance annotations](variances.html) here (`+T <: Seq[U]`) in order to hide the concrete sequence implementation type of the object returned from method `newIntSeqBuf`. Furthermore, there are cases where it is not possible to replace abstract type members with type parameters. diff --git a/_tour/annotations.md b/_tour/annotations.md index bdd39a09b7..a9876fab42 100644 --- a/_tour/annotations.md +++ b/_tour/annotations.md @@ -11,14 +11,29 @@ redirect_from: "/tutorials/tour/annotations.html" --- Annotations associate meta-information with definitions. For example, the annotation `@deprecated` before a method causes the compiler to print a warning if the method is used. -``` + +{% tabs annotations_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_1 %} +```scala mdoc:fail object DeprecationDemo extends App { @deprecated("deprecation message", "release # which deprecates method") def hello = "hola" - hello + hello } ``` +{% endtab %} +{% tab 'Scala 3' for=annotations_1 %} +```scala +object DeprecationDemo extends App: + @deprecated("deprecation message", "release # which deprecates method") + def hello = "hola" + + hello +``` +{% endtab %} +{% endtabs %} + This will compile but the compiler will print a warning: "there was one deprecation warning". An annotation clause applies to the first definition or declaration following it. More than one annotation clause may precede a definition and declaration. The order in which these clauses are given does not matter. @@ -26,6 +41,9 @@ An annotation clause applies to the first definition or declaration following it ## Annotations that ensure correctness of encodings Certain annotations will actually cause compilation to fail if a condition(s) is not met. For example, the annotation `@tailrec` ensures that a method is [tail-recursive](https://en.wikipedia.org/wiki/Tail_call). Tail-recursion can keep memory requirements constant. Here's how it's used in a method which calculates the factorial: + +{% tabs annotations_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_2 %} ```scala mdoc import scala.annotation.tailrec @@ -38,8 +56,26 @@ def factorial(x: Int): Int = { factorialHelper(x, 1) } ``` -The `factorialHelper` method has the `@tailrec` which ensures the method is indeed tail-recursive. If we were to change the implementation of `factorialHelper` to the following, it would fail: +{% endtab %} +{% tab 'Scala 3' for=annotations_2 %} +```scala +import scala.annotation.tailrec + +def factorial(x: Int): Int = + + @tailrec + def factorialHelper(x: Int, accumulator: Int): Int = + if x == 1 then accumulator else factorialHelper(x - 1, accumulator * x) + factorialHelper(x, 1) ``` +{% endtab %} +{% endtabs %} + +The `factorialHelper` method has the `@tailrec` which ensures the method is indeed tail-recursive. If we were to change the implementation of `factorialHelper` to the following, it would fail: + +{% tabs annotations_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_3 %} +```scala mdoc:fail import scala.annotation.tailrec def factorial(x: Int): Int = { @@ -50,76 +86,134 @@ def factorial(x: Int): Int = { factorialHelper(x) } ``` -We would get the message "Recursive call not in tail position". +{% endtab %} +{% tab 'Scala 3' for=annotations_3 %} +```scala +import scala.annotation.tailrec +def factorial(x: Int): Int = + @tailrec + def factorialHelper(x: Int): Int = + if x == 1 then 1 else x * factorialHelper(x - 1) + factorialHelper(x) +``` +{% endtab %} +{% endtabs %} + +We would get the message "Recursive call not in tail position". ## Annotations affecting code generation + +{% tabs annotations_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=annotations_4 %} + Some annotations like `@inline` affect the generated code (i.e. your jar file might have different bytes than if you hadn't used the annotation). Inlining means inserting the code in a method's body at the call site. The resulting bytecode is longer, but hopefully runs faster. Using the annotation `@inline` does not ensure that a method will be inlined, but it will cause the compiler to do it if and only if some heuristics about the size of the generated code are met. +{% endtab %} +{% tab 'Scala 3' for=annotations_4 %} + +Some annotations like `@main` affect the generated code (i.e. your jar file might have different bytes than if you hadn't used the annotation). A `@main` annotation on a method generates an executable program that calls the method as an entry point. + +{% endtab %} +{% endtabs %} + ### Java Annotations ### When writing Scala code which interoperates with Java, there are a few differences in annotation syntax to note. **Note:** Make sure you use the `-target:jvm-1.8` option with Java annotations. Java has user-defined metadata in the form of [annotations](https://docs.oracle.com/javase/tutorial/java/annotations/). A key feature of annotations is that they rely on specifying name-value pairs to initialize their elements. For instance, if we need an annotation to track the source of some class we might define it as -``` +{% tabs annotations_5 %} +{% tab 'Java' for=annotations_5 %} +```java @interface Source { - public String URL(); + public String url(); public String mail(); } ``` +{% endtab %} +{% endtabs %} And then apply it as follows -``` -@Source(URL = "https://coders.com/", +{% tabs annotations_6 %} +{% tab 'Java' for=annotations_6 %} +```java +@Source(url = "https://coders.com/", mail = "support@coders.com") -public class MyClass extends TheirClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -An annotation application in Scala looks like a constructor invocation, for instantiating a Java annotation one has to use named arguments: +An annotation application in Scala looks like a constructor invocation, but to instantiate a Java annotation one has to use named arguments: -``` -@Source(URL = "https://coders.com/", +{% tabs annotations_7 %} +{% tab 'Scala 2 and 3' for=annotations_7 %} +```scala +@Source(url = "https://coders.com/", mail = "support@coders.com") class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} This syntax is quite tedious if the annotation contains only one element (without default value) so, by convention, if the name is specified as `value` it can be applied in Java using a constructor-like syntax: -``` +{% tabs annotations_8 %} +{% tab 'Java' for=annotations_8 %} +```java @interface SourceURL { public String value(); public String mail() default ""; } ``` +{% endtab %} +{% endtabs %} -And then apply it as follows +And then apply it as follows: -``` +{% tabs annotations_9 %} +{% tab 'Java' for=annotations_9 %} +```java @SourceURL("https://coders.com/") -public class MyClass extends TheirClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -In this case, Scala provides the same possibility +In this case, Scala provides the same possibility: -``` +{% tabs annotations_10 %} +{% tab 'Scala 2 and 3' for=annotations_10 %} +```scala @SourceURL("https://coders.com/") class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} -The `mail` element was specified with a default value so we need not explicitly provide a value for it. However, if we need to do it we can not mix-and-match the two styles in Java: +The `mail` element was specified with a default value so we need not explicitly provide a value for it. +However, if we need to provide one then in Java we must also explicitly name the `value` parameter: -``` +{% tabs annotations_11 %} +{% tab 'Java' for=annotations_11 %} +```java @SourceURL(value = "https://coders.com/", mail = "support@coders.com") -public class MyClass extends TheirClass ... +public class MyJavaClass extends TheirClass ... ``` +{% endtab %} +{% endtabs %} -Scala provides more flexibility in this respect +Scala provides more flexibility in this respect, so we can choose to only name the `mail` parameter: -``` +{% tabs annotations_12 %} +{% tab 'Scala 2 and 3' for=annotations_12 %} +```scala @SourceURL("https://coders.com/", mail = "support@coders.com") - class MyScalaClass ... +class MyScalaClass ... ``` +{% endtab %} +{% endtabs %} diff --git a/_tour/automatic-closures.md b/_tour/automatic-closures.md deleted file mode 100644 index 7df0b975ab..0000000000 --- a/_tour/automatic-closures.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: tour -title: Automatic Type-Dependent Closure Construction -partof: scala-tour - -redirect_from: "/tutorials/tour/automatic-closures.html" ---- - -Scala allows parameterless function names as parameters of methods. When such a method is called, the actual parameters for parameterless function names are not evaluated and a nullary function is passed instead which encapsulates the computation of the corresponding parameter (so-called *call-by-name* evaluation). - -The following code demonstrates this mechanism: - - object TargetTest1 extends Application { - def whileLoop(cond: => Boolean)(body: => Unit): Unit = - if (cond) { - body - whileLoop(cond)(body) - } - var i = 10 - whileLoop (i > 0) { - println(i) - i -= 1 - } - } - -The function whileLoop takes two parameters `cond` and `body`. When the function is applied, the actual parameters do not get evaluated. But whenever the formal parameters are used in the body of `whileLoop`, the implicitly created nullary functions will be evaluated instead. Thus, our method `whileLoop` implements a Java-like while-loop with a recursive implementation scheme. - -We can combine the use of [infix/postfix operators](operators.html) with this mechanism to create more complex statements (with a nice syntax). - -Here is the implementation of a loop-unless statement: - - object TargetTest2 extends Application { - def loop(body: => Unit): LoopUnlessCond = - new LoopUnlessCond(body) - protected class LoopUnlessCond(body: => Unit) { - def unless(cond: => Boolean) { - body - if (!cond) unless(cond) - } - } - var i = 10 - loop { - println("i = " + i) - i -= 1 - } unless (i == 0) - } -The `loop` function just accepts a body of a loop and returns an instance of class `LoopUnlessCond` (which encapsulates this body object). Note that the body didn't get evaluated yet. Class `LoopUnlessCond` has a method `unless` which we can use as a *infix operator*. This way, we achieve a quite natural syntax for our new loop: `loop { < stats > } unless ( < cond > )`. - -Here's the output when `TargetTest2` gets executed: - - i = 10 - i = 9 - i = 8 - i = 7 - i = 6 - i = 5 - i = 4 - i = 3 - i = 2 - i = 1 diff --git a/_tour/basics.md b/_tour/basics.md index f5acd95ab3..ccfb324feb 100644 --- a/_tour/basics.md +++ b/_tour/basics.md @@ -14,72 +14,98 @@ In this page, we will cover the basics of Scala. ## Trying Scala in the Browser -You can run Scala in your browser with _ScalaFiddle_. This is an easy, zero-setup way to experiment with pieces of Scala code: +You can run Scala in your browser with _Scastie_. This is an easy, zero-setup way to experiment with pieces of Scala code: -1. Go to [https://scalafiddle.io](https://scalafiddle.io). +1. Go to [Scastie](https://scastie.scala-lang.org/). 2. Paste `println("Hello, world!")` in the left pane. 3. Click __Run__. The output appears in the right pane. -_ScalaFiddle_ is integrated with some of the code examples in this documentation; if you see a __Run__ button in a code example below, click it to directly experiment with the code. - ## Expressions Expressions are computable statements: + +{% tabs expression %} +{% tab 'Scala 2 and 3' for=expression %} ```scala mdoc 1 + 1 ``` +{% endtab %} +{% endtabs %} + You can output the results of expressions using `println`: -{% scalafiddle %} +{% tabs println %} +{% tab 'Scala 2 and 3' for=println %} ```scala mdoc println(1) // 1 println(1 + 1) // 2 println("Hello!") // Hello! println("Hello," + " world!") // Hello, world! ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} ### Values You can name the results of expressions using the `val` keyword: +{% tabs val %} +{% tab 'Scala 2 and 3' for=val %} ```scala mdoc val x = 1 + 1 println(x) // 2 ``` +{% endtab %} +{% endtabs %} Named results, such as `x` here, are called values. Referencing a value does not re-compute it. Values cannot be re-assigned: +{% tabs val-error %} +{% tab 'Scala 2 and 3' for=val-error %} ```scala mdoc:fail x = 3 // This does not compile. ``` +{% endtab %} +{% endtabs %} The type of a value can be omitted and [inferred](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated: +{% tabs type-inference %} +{% tab 'Scala 2 and 3' for=type-inference %} ```scala mdoc:nest val x: Int = 1 + 1 ``` +{% endtab %} +{% endtabs %} -Notice how the type declaration `Int` comes after the identifier `x`. You also need a `:`. +Notice how the type declaration `Int` comes after the identifier `x`. You also need a `:`. ### Variables Variables are like values, except you can re-assign them. You can define a variable with the `var` keyword. +{% tabs var %} +{% tab 'Scala 2 and 3' for=var %} ```scala mdoc:nest var x = 1 + 1 x = 3 // This compiles because "x" is declared with the "var" keyword. println(x * x) // 9 ``` +{% endtab %} +{% endtabs %} As with values, the type of a variable can be omitted and [inferred](https://docs.scala-lang.org/tour/type-inference.html), or it can be explicitly stated: +{% tabs type-inference-2 %} +{% tab 'Scala 2 and 3' for=type-inference-2 %} ```scala mdoc:nest var x: Int = 1 + 1 ``` +{% endtab %} +{% endtabs %} ## Blocks @@ -88,12 +114,16 @@ You can combine expressions by surrounding them with `{}`. We call this a block. The result of the last expression in the block is the result of the overall block, too: +{% tabs blocks %} +{% tab 'Scala 2 and 3' for=blocks %} ```scala mdoc println({ val x = 1 + 1 x + 1 }) // 3 ``` +{% endtab %} +{% endtabs %} ## Functions @@ -101,36 +131,48 @@ Functions are expressions that have parameters, and take arguments. You can define an anonymous function (i.e., a function that has no name) that returns a given integer plus one: +{% tabs anonymous-function %} +{% tab 'Scala 2 and 3' for=anonymous-function %} ```scala mdoc (x: Int) => x + 1 ``` +{% endtab %} +{% endtabs %} On the left of `=>` is a list of parameters. On the right is an expression involving the parameters. You can also name functions: -{% scalafiddle %} +{% tabs named-function %} +{% tab 'Scala 2 and 3' for=named-function %} ```scala mdoc val addOne = (x: Int) => x + 1 println(addOne(1)) // 2 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} A function can have multiple parameters: -{% scalafiddle %} +{% tabs multiple-parameters %} +{% tab 'Scala 2 and 3' for=multiple-parameters %} ```scala mdoc val add = (x: Int, y: Int) => x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} Or it can have no parameters at all: +{% tabs no-parameters %} +{% tab 'Scala 2 and 3' for=no-parameters %} ```scala mdoc val getTheAnswer = () => 42 println(getTheAnswer()) // 42 ``` +{% endtab %} +{% endtabs %} ## Methods @@ -138,36 +180,46 @@ Methods look and behave very similar to functions, but there are a few key diffe Methods are defined with the `def` keyword. `def` is followed by a name, parameter list(s), a return type, and a body: -{% scalafiddle %} +{% tabs method %} +{% tab 'Scala 2 and 3' for=method %} ```scala mdoc:nest def add(x: Int, y: Int): Int = x + y println(add(1, 2)) // 3 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} Notice how the return type `Int` is declared _after_ the parameter list and a `:`. A method can take multiple parameter lists: -{% scalafiddle %} +{% tabs multiple-parameter-lists %} +{% tab 'Scala 2 and 3' for=multiple-parameter-lists %} ```scala mdoc def addThenMultiply(x: Int, y: Int)(multiplier: Int): Int = (x + y) * multiplier println(addThenMultiply(1, 2)(3)) // 9 ``` -{% endscalafiddle %} +{% endtab %} +{% endtabs %} Or no parameter lists at all: +{% tabs no-parameter-lists %} +{% tab 'Scala 2 and 3' for=no-parameter-lists %} ```scala mdoc def name: String = System.getProperty("user.name") println("Hello, " + name + "!") ``` +{% endtab %} +{% endtabs %} There are some other differences, but for now, you can think of methods as something similar to functions. Methods can have multi-line expressions as well: -{% scalafiddle %} +{% tabs get-square-string class=tabs-scala-version %} + +{% tab 'Scala 2' for=get-square-string %} ```scala mdoc def getSquareString(input: Double): String = { val square = input * input @@ -175,7 +227,19 @@ def getSquareString(input: Double): String = { } println(getSquareString(2.5)) // 6.25 ``` -{% endscalafiddle %} +{% endtab %} + +{% tab 'Scala 3' for=get-square-string %} +```scala +def getSquareString(input: Double): String = + val square = input * input + square.toString + +println(getSquareString(2.5)) // 6.25 +``` +{% endtab %} + +{% endtabs %} The last expression in the body is the method's return value. (Scala does have a `return` keyword, but it is rarely used.) @@ -183,20 +247,48 @@ The last expression in the body is the method's return value. (Scala does have a You can define classes with the `class` keyword, followed by its name and constructor parameters: +{% tabs greeter-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-definition %} ```scala mdoc class Greeter(prefix: String, suffix: String) { def greet(name: String): Unit = println(prefix + name + suffix) } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-definition %} +```scala +class Greeter(prefix: String, suffix: String): + def greet(name: String): Unit = + println(prefix + name + suffix) +``` +{% endtab %} + +{% endtabs %} + The return type of the method `greet` is `Unit`, which signifies that there is nothing meaningful to return. It is used similarly to `void` in Java and C. (A difference is that, because every Scala expression must have some value, there is actually a singleton value of type Unit, written (). It carries no information.) -You can make an instance of a class with the `new` keyword: +In Scala 2 you can make an instance of a class with the `new` keyword. In Scala 3, however, the `new` keyword is not needed thanks to [universal apply methods](https://docs.scala-lang.org/scala3/reference/other-new-features/creator-applications.html): +{% tabs greeter-usage class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-usage %} ```scala mdoc:nest val greeter = new Greeter("Hello, ", "!") greeter.greet("Scala developer") // Hello, Scala developer! ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-usage %} +```scala +val greeter = Greeter("Hello, ", "!") +greeter.greet("Scala developer") // Hello, Scala developer! +``` +{% endtab %} + +{% endtabs %} We will cover classes in depth [later](classes.html). @@ -206,33 +298,63 @@ Scala has a special type of class called a "case" class. By default, instances o You can define case classes with the `case class` keywords: +{% tabs case-class-definition %} +{% tab 'Scala 2 and 3' for=case-class-definition %} ```scala mdoc case class Point(x: Int, y: Int) ``` +{% endtab %} +{% endtabs %} You can instantiate case classes without the `new` keyword: +{% tabs case-class-creation %} +{% tab 'Scala 2 and 3' for=case-class-creation %} ```scala mdoc val point = Point(1, 2) val anotherPoint = Point(1, 2) val yetAnotherPoint = Point(2, 2) ``` +{% endtab %} +{% endtabs %} Instances of case classes are compared by value, not by reference: +{% tabs compare-case-class-equality class=tabs-scala-version %} + +{% tab 'Scala 2' for=compare-case-class-equality %} ```scala mdoc if (point == anotherPoint) { - println(point + " and " + anotherPoint + " are the same.") + println(s"$point and $anotherPoint are the same.") } else { - println(point + " and " + anotherPoint + " are different.") + println(s"$point and $anotherPoint are different.") } // Point(1,2) and Point(1,2) are the same. if (point == yetAnotherPoint) { - println(point + " and " + yetAnotherPoint + " are the same.") + println(s"$point and $yetAnotherPoint are the same.") } else { - println(point + " and " + yetAnotherPoint + " are different.") + println(s"$point and $yetAnotherPoint are different.") } // Point(1,2) and Point(2,2) are different. ``` +{% endtab %} + +{% tab 'Scala 3' for=compare-case-class-equality %} +```scala +if point == anotherPoint then + println(s"$point and $anotherPoint are the same.") +else + println(s"$point and $anotherPoint are different.") +// ==> Point(1,2) and Point(1,2) are the same. + +if point == yetAnotherPoint then + println(s"$point and $yetAnotherPoint are the same.") +else + println(s"$point and $yetAnotherPoint are different.") +// ==> Point(1,2) and Point(2,2) are different. +``` +{% endtab %} + +{% endtabs %} There is a lot more to case classes that we would like to introduce, and we are convinced you will fall in love with them! We will cover them in depth [later](case-classes.html). @@ -242,6 +364,9 @@ Objects are single instances of their own definitions. You can think of them as You can define objects with the `object` keyword: +{% tabs id-factory-definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=id-factory-definition %} ```scala mdoc object IdFactory { private var counter = 0 @@ -251,15 +376,32 @@ object IdFactory { } } ``` +{% endtab %} + +{% tab 'Scala 3' for=id-factory-definition %} +```scala +object IdFactory: + private var counter = 0 + def create(): Int = + counter += 1 + counter +``` +{% endtab %} + +{% endtabs %} You can access an object by referring to its name: +{% tabs id-factory-usage %} +{% tab 'Scala 2 and 3' for=id-factory-usage %} ```scala mdoc val newId: Int = IdFactory.create() println(newId) // 1 val newerId: Int = IdFactory.create() println(newerId) // 2 ``` +{% endtab %} +{% endtabs %} We will cover objects in depth [later](singleton-objects.html). @@ -269,24 +411,53 @@ Traits are abstract data types containing certain fields and methods. In Scala i You can define traits with the `trait` keyword: +{% tabs greeter-trait-def class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-trait-def %} ```scala mdoc:nest trait Greeter { def greet(name: String): Unit } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def %} +```scala +trait Greeter: + def greet(name: String): Unit +``` +{% endtab %} + +{% endtabs %} Traits can also have default implementations: -{% scalafiddle %} +{% tabs greeter-trait-def-impl class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-trait-def-impl %} ```scala mdoc:reset trait Greeter { def greet(name: String): Unit = println("Hello, " + name + "!") } ``` +{% endtab %} + +{% tab 'Scala 3' for=greeter-trait-def-impl %} +```scala +trait Greeter: + def greet(name: String): Unit = + println("Hello, " + name + "!") +``` +{% endtab %} + +{% endtabs %} You can extend traits with the `extends` keyword and override an implementation with the `override` keyword: +{% tabs greeter-implementations class=tabs-scala-version %} + +{% tab 'Scala 2' for=greeter-implementations %} ```scala mdoc class DefaultGreeter extends Greeter @@ -302,19 +473,41 @@ greeter.greet("Scala developer") // Hello, Scala developer! val customGreeter = new CustomizableGreeter("How are you, ", "?") customGreeter.greet("Scala developer") // How are you, Scala developer? ``` -{% endscalafiddle %} +{% endtab %} + +{% tab 'Scala 3' for=greeter-implementations %} +```scala +class DefaultGreeter extends Greeter + +class CustomizableGreeter(prefix: String, postfix: String) extends Greeter: + override def greet(name: String): Unit = + println(prefix + name + postfix) + +val greeter = DefaultGreeter() +greeter.greet("Scala developer") // Hello, Scala developer! + +val customGreeter = CustomizableGreeter("How are you, ", "?") +customGreeter.greet("Scala developer") // How are you, Scala developer? +``` +{% endtab %} + +{% endtabs %} Here, `DefaultGreeter` extends only one single trait, but it could extend multiple traits. We will cover traits in depth [later](traits.html). -## Main Method +## Program Entry Point The main method is the entry point of a Scala program. The Java Virtual Machine requires a main method, named `main`, that takes one argument: an array of strings. -Using an object, you can define the main method as follows: +{% tabs hello-world-demo class=tabs-scala-version %} + +{% tab 'Scala 2' for=hello-world-demo %} + +In Scala 2 you must define a main method manually. Using an object, you can define the main method as follows: ```scala mdoc object Main { @@ -322,7 +515,19 @@ object Main { println("Hello, Scala developer!") } ``` +{% endtab %} + +{% tab 'Scala 3' for=hello-world-demo %} + +In Scala 3, with the `@main` annotation, a main method is automatically generated from a method as follows: + +```scala +@main def hello() = println("Hello, Scala developer!") +``` +{% endtab %} + +{% endtabs %} ## More resources -* [Scala book](/overviews/scala-book/prelude-taste-of-scala.html) overview +* [Scala book](/scala3/book/taste-intro.html) overview diff --git a/_tour/by-name-parameters.md b/_tour/by-name-parameters.md index 6d0ff8b610..441aefa597 100644 --- a/_tour/by-name-parameters.md +++ b/_tour/by-name-parameters.md @@ -8,16 +8,25 @@ next-page: annotations previous-page: operators redirect_from: "/tutorials/tour/by-name-parameters.html" +redirect_from: "/tutorials/tour/automatic-closures.html" --- _By-name parameters_ are evaluated every time they are used. They won't be evaluated at all if they are unused. This is similar to replacing the by-name parameters with the passed expressions. They are in contrast to _by-value parameters_. To make a parameter called by-name, simply prepend `=>` to its type. + +{% tabs by-name-parameters_1 %} +{% tab 'Scala 2 and 3' for=by-name-parameters_1 %} ```scala mdoc def calculate(input: => Int) = input * 37 ``` +{% endtab %} +{% endtabs %} + By-name parameters have the advantage that they are not evaluated if they aren't used in the function body. On the other hand, by-value parameters have the advantage that they are evaluated only once. Here's an example of how we could implement a while loop: +{% tabs by-name-parameters_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=by-name-parameters_2 %} ```scala mdoc def whileLoop(condition: => Boolean)(body: => Unit): Unit = if (condition) { @@ -32,6 +41,24 @@ whileLoop (i > 0) { i -= 1 } // prints 2 1 ``` +{% endtab %} +{% tab 'Scala 3' for=by-name-parameters_2 %} +```scala +def whileLoop(condition: => Boolean)(body: => Unit): Unit = + if condition then + body + whileLoop(condition)(body) + +var i = 2 + +whileLoop (i > 0) { + println(i) + i -= 1 +} // prints 2 1 +``` +{% endtab %} +{% endtabs %} + The method `whileLoop` uses multiple parameter lists to take a condition and a body of the loop. If the `condition` is true, the `body` is executed and then a recursive call to whileLoop is made. If the `condition` is false, the body is never evaluated because we prepended `=>` to the type of `body`. Now when we pass `i > 0` as our `condition` and `println(i); i-= 1` as the `body`, it behaves like the standard while loop in many languages. diff --git a/_tour/case-classes.md b/_tour/case-classes.md index b05756f81b..889f8e98bc 100644 --- a/_tour/case-classes.md +++ b/_tour/case-classes.md @@ -15,14 +15,26 @@ Case classes are like regular classes with a few key differences which we will g ## Defining a case class A minimal case class requires the keywords `case class`, an identifier, and a parameter list (which may be empty): + +{% tabs case-classe_Book %} + +{% tab 'Scala 2 and 3' for=case-classe_Book %} ```scala mdoc case class Book(isbn: String) val frankenstein = Book("978-0486282114") ``` -Notice how the keyword `new` was not used to instantiate the `Book` case class. This is because case classes have an `apply` method by default which takes care of object construction. +{% endtab %} + +{% endtabs %} + +Although that is usually left out, it is possible to explicitly use the `new` keyword, as `new Book()`. This is because case classes have an `apply` method by default which takes care of object construction. When you create a case class with parameters, the parameters are public `val`s. + +{% tabs case-classe_Message_define %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_define %} ``` case class Message(sender: String, recipient: String, body: String) val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") @@ -30,10 +42,18 @@ val message1 = Message("guillaume@quebec.ca", "jorge@catalonia.es", "Ça va ?") println(message1.sender) // prints guillaume@quebec.ca message1.sender = "travis@washington.us" // this line does not compile ``` +{% endtab %} + +{% endtabs %} + You can't reassign `message1.sender` because it is a `val` (i.e. immutable). It is possible to use `var`s in case classes but this is discouraged. ## Comparison Instances of case classes are compared by structure and not by reference: + +{% tabs case-classe_Message_compare %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_compare %} ```scala mdoc case class Message(sender: String, recipient: String, body: String) @@ -41,10 +61,18 @@ val message2 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") val message3 = Message("jorge@catalonia.es", "guillaume@quebec.ca", "Com va?") val messagesAreTheSame = message2 == message3 // true ``` +{% endtab %} + +{% endtabs %} + Even though `message2` and `message3` refer to different objects, the value of each object is equal. ## Copying You can create a (shallow) copy of an instance of a case class simply by using the `copy` method. You can optionally change the constructor arguments. + +{% tabs case-classe_Message_copy %} + +{% tab 'Scala 2 and 3' for=case-classe_Message_copy %} ```scala mdoc:nest case class Message(sender: String, recipient: String, body: String) val message4 = Message("julien@bretagne.fr", "travis@washington.us", "Me zo o komz gant ma amezeg") @@ -53,8 +81,12 @@ message5.sender // travis@washington.us message5.recipient // claire@bourgogne.fr message5.body // "Me zo o komz gant ma amezeg" ``` +{% endtab %} + +{% endtabs %} + The recipient of `message4` is used as the sender of `message5` but the `body` of `message4` was copied directly. ## More resources -* Learn more about case classes in the [Scala Book](/overviews/scala-book/case-classes.html) +* Learn more about case classes in the [Scala Book](/scala3/book/domain-modeling-tools.html#case-classes) diff --git a/_tour/classes.md b/_tour/classes.md index 47b5079bc5..683ae049cf 100644 --- a/_tour/classes.md +++ b/_tour/classes.md @@ -18,13 +18,37 @@ values, variables, types, objects, traits, and classes which are collectively ca ## Defining a class A minimal class definition is simply the keyword `class` and an identifier. Class names should be capitalized. + +{% tabs class-minimal-user class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-minimal-user %} ```scala mdoc class User val user1 = new User ``` -The keyword `new` is used to create an instance of the class. `User` has a default constructor which takes no arguments because no constructor was defined. However, you'll often want a constructor and class body. Here is an example class definition for a point: +The keyword `new` is used to create an instance of the class. +{% endtab %} + +{% tab 'Scala 3' for=class-minimal-user %} +```scala +class User + +val user1 = User() +``` + +We call the class like a function, as `User()`, to create an instance of the class. +It is also possible to explicitly use the `new` keyword, as `new User()`, although that is usually left out. +{% endtab %} + +{% endtabs %} + +`User` has a default constructor which takes no arguments because no constructor was defined. However, you'll often want a constructor and class body. Here is an example class definition for a point: + +{% tabs class-point-example class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-example %} ```scala mdoc class Point(var x: Int, var y: Int) { @@ -38,78 +62,205 @@ class Point(var x: Int, var y: Int) { } val point1 = new Point(2, 3) -println(point1.x) // 2 -println(point1) // prints (2, 3) +println(point1.x) // prints 2 +println(point1) // prints (2, 3) ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-example %} +```scala +class Point(var x: Int, var y: Int): + + def move(dx: Int, dy: Int): Unit = + x = x + dx + y = y + dy + + override def toString: String = + s"($x, $y)" +end Point + +val point1 = Point(2, 3) +println(point1.x) // prints 2 +println(point1) // prints (2, 3) +``` +{% endtab %} + +{% endtabs %} This `Point` class has four members: the variables `x` and `y` and the methods `move` and -`toString`. Unlike many other languages, the primary constructor is in the class signature `(var x: Int, var y: Int)`. The `move` method takes two integer arguments and returns the Unit value `()`, which carries no information. This corresponds roughly with `void` in Java-like languages. `toString`, on the other hand, does not take any arguments but returns a `String` value. Since `toString` overrides `toString` from [`AnyRef`](unified-types.html), it is tagged with the `override` keyword. +`toString`. Unlike many other languages, the primary constructor is in the class signature `(var x: Int, var y: Int)`. The `move` method takes two integer arguments and returns the Unit value `()`, which carries no information. This corresponds roughly to `void` in Java-like languages. `toString`, on the other hand, does not take any arguments but returns a `String` value. Since `toString` overrides `toString` from [`AnyRef`](unified-types.html), it is tagged with the `override` keyword. ## Constructors Constructors can have optional parameters by providing a default value like so: +{% tabs class-point-with-default-values class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-with-default-values %} ```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) -val origin = new Point // x and y are both set to 0 -val point1 = new Point(1) -println(point1.x) // prints 1 +val origin = new Point // x and y are both set to 0 +val point1 = new Point(1) // x is set to 1 and y is set to 0 +println(point1) // prints (1, 0) +``` +{% endtab %} +{% tab 'Scala 3' for=class-point-with-default-values %} +```scala +class Point(var x: Int = 0, var y: Int = 0) + +val origin = Point() // x and y are both set to 0 +val point1 = Point(1) // x is set to 1 and y is set to 0 +println(point1) // prints (1, 0) ``` +{% endtab %} + +{% endtabs %} In this version of the `Point` class, `x` and `y` have the default value `0` so no arguments are required. However, because the constructor reads arguments left to right, if you just wanted to pass in a `y` value, you would need to name the parameter. + +{% tabs class-point-named-argument class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-named-argument %} ```scala mdoc:nest class Point(var x: Int = 0, var y: Int = 0) val point2 = new Point(y = 2) -println(point2.y) // prints 2 +println(point2) // prints (0, 2) +``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-named-argument %} +```scala +class Point(var x: Int = 0, var y: Int = 0) +val point2 = Point(y = 2) +println(point2) // prints (0, 2) ``` +{% endtab %} + +{% endtabs %} This is also a good practice to enhance clarity. ## Private Members and Getter/Setter Syntax Members are public by default. Use the `private` access modifier to hide them from outside of the class. + +{% tabs class-point-private-getter-setter class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-private-getter-setter %} ```scala mdoc:reset class Point { private var _x = 0 private var _y = 0 private val bound = 100 - def x = _x - def x_= (newValue: Int): Unit = { - if (newValue < bound) _x = newValue else printWarning + def x: Int = _x + def x_=(newValue: Int): Unit = { + if (newValue < bound) + _x = newValue + else + printWarning() } - def y = _y - def y_= (newValue: Int): Unit = { - if (newValue < bound) _y = newValue else printWarning + def y: Int = _y + def y_=(newValue: Int): Unit = { + if (newValue < bound) + _y = newValue + else + printWarning() } - private def printWarning = println("WARNING: Out of bounds") + private def printWarning(): Unit = + println("WARNING: Out of bounds") } val point1 = new Point point1.x = 99 point1.y = 101 // prints the warning ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-private-getter-setter %} +```scala +class Point: + private var _x = 0 + private var _y = 0 + private val bound = 100 + + def x: Int = _x + def x_=(newValue: Int): Unit = + if newValue < bound then + _x = newValue + else + printWarning() + + def y: Int = _y + def y_=(newValue: Int): Unit = + if newValue < bound then + _y = newValue + else + printWarning() + + private def printWarning(): Unit = + println("WARNING: Out of bounds") +end Point + +val point1 = Point() +point1.x = 99 +point1.y = 101 // prints the warning +``` +{% endtab %} + +{% endtabs %} + In this version of the `Point` class, the data is stored in private variables `_x` and `_y`. There are methods `def x` and `def y` for accessing the private data. `def x_=` and `def y_=` are for validating and setting the value of `_x` and `_y`. Notice the special syntax for the setters: the method has `_=` appended to the identifier of the getter and the parameters come after. Primary constructor parameters with `val` and `var` are public. However, because `val`s are immutable, you can't write the following. + +{% tabs class-point-cannot-set-val class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-cannot-set-val %} ```scala mdoc:fail class Point(val x: Int, val y: Int) val point = new Point(1, 2) point.x = 3 // <-- does not compile ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-cannot-set-val %} +```scala +class Point(val x: Int, val y: Int) +val point = Point(1, 2) +point.x = 3 // <-- does not compile +``` +{% endtab %} + +{% endtabs %} Parameters without `val` or `var` are private values, visible only within the class. + +{% tabs class-point-non-val-ctor-param class=tabs-scala-version %} + +{% tab 'Scala 2' for=class-point-non-val-ctor-param %} ```scala mdoc:fail class Point(x: Int, y: Int) val point = new Point(1, 2) point.x // <-- does not compile ``` +{% endtab %} + +{% tab 'Scala 3' for=class-point-non-val-ctor-param %} +```scala +class Point(x: Int, y: Int) +val point = Point(1, 2) +point.x // <-- does not compile +``` +{% endtab %} + +{% endtabs %} ## More resources -* Learn more about Classes in the [Scala Book](/overviews/scala-book/classes.html) -* How to use [Auxiliary Class Constructors](/overviews/scala-book/classes-aux-constructors.html) +* Learn more about Classes in the [Scala Book](/scala3/book/domain-modeling-tools.html#classes) +* How to use [Auxiliary Class Constructors](/scala3/book/domain-modeling-tools.html#auxiliary-constructors) diff --git a/_tour/compound-types.md b/_tour/compound-types.md index 4cd53674b5..2c12773600 100644 --- a/_tour/compound-types.md +++ b/_tour/compound-types.md @@ -1,6 +1,6 @@ --- layout: tour -title: Compound Types +title: Intersection Types, aka Compound Types partof: scala-tour num: 26 @@ -10,13 +10,18 @@ previous-page: abstract-type-members redirect_from: "/tutorials/tour/compound-types.html" --- -Sometimes it is necessary to express that the type of an object is a subtype of several other types. In Scala this can be expressed with the help of *compound types*, which are intersections of object types. +Sometimes it is necessary to express that the type of an object is a subtype of several other types. + +In Scala this can be expressed with the help of *intersection types*, (or *compound types* in +Scala 2) which are types that behave like any part of the intersection. Suppose we have two traits `Cloneable` and `Resetable`: +{% tabs compound-types_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_1 %} ```scala mdoc trait Cloneable extends java.lang.Cloneable { - override def clone(): Cloneable = { + override def clone(): Cloneable = { // makes clone public super.clone().asInstanceOf[Cloneable] } } @@ -24,28 +29,67 @@ trait Resetable { def reset: Unit } ``` +{% endtab %} +{% tab 'Scala 3' for=compound-types_1 %} +```scala +trait Cloneable extends java.lang.Cloneable: + override def clone(): Cloneable = // makes clone public + super.clone().asInstanceOf[Cloneable] +trait Resetable: + def reset: Unit +``` +{% endtab %} +{% endtabs %} Now suppose we want to write a function `cloneAndReset` which takes an object, clones it and resets the original object: -``` +{% tabs compound-types_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_2 %} +```scala mdoc:fail def cloneAndReset(obj: ?): Cloneable = { val cloned = obj.clone() obj.reset cloned } ``` +{% endtab %} +{% tab 'Scala 3' for=compound-types_2 %} +```scala +def cloneAndReset(obj: ?): Cloneable = + val cloned = obj.clone() + obj.reset + cloned +``` +{% endtab %} +{% endtabs %} -The question arises what the type of the parameter `obj` is. If it's `Cloneable` then the object can be `clone`d, but not `reset`; if it's `Resetable` we can `reset` it, but there is no `clone` operation. To avoid type casts in such a situation, we can specify the type of `obj` to be both `Cloneable` and `Resetable`. This compound type is written like this in Scala: `Cloneable with Resetable`. +The question arises what the type of the parameter `obj` is. If it's `Cloneable` then the object can be `clone`d, but not `reset`; if it's `Resetable` we can `reset` it, but there is no `clone` operation. To avoid type casts in such a situation, we can specify the type of `obj` to be both `Cloneable` and `Resetable`. +{% tabs compound-types_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=compound-types_3 %} +This compound type is written in Scala as `Cloneable with Resetable`. Here's the updated function: - -``` +```scala mdoc:fail def cloneAndReset(obj: Cloneable with Resetable): Cloneable = { //... } ``` +Note that you can have more than two types: `A with B with C with ...`. +This means the same as thing as `(...(A with B) with C) with ... )` +{% endtab %} +{% tab 'Scala 3' for=compound-types_3 %} +This intersection type is written in Scala as `Cloneable & Resetable`. -Compound types can consist of several object types and they may have a single refinement which can be used to narrow the signature of existing object members. -The general form is: `A with B with C ... { refinement }` +Here's the updated function: +```scala +def cloneAndReset(obj: Cloneable & Resetable): Cloneable = { + //... +} +``` + +Note that you can have more than two types: `A & B & C & ...`. +And `&` is associative, so parentheses can be added around any part without changing the meaning. +{% endtab %} +{% endtabs %} -An example for the use of refinements is given on the page about [class composition with mixins](mixin-class-composition.html). + diff --git a/_tour/default-parameter-values.md b/_tour/default-parameter-values.md index 60776fd228..96b28f278a 100644 --- a/_tour/default-parameter-values.md +++ b/_tour/default-parameter-values.md @@ -13,29 +13,45 @@ redirect_from: "/tutorials/tour/default-parameter-values.html" Scala provides the ability to give parameters default values that can be used to allow a caller to omit those parameters. +{% tabs default-parameter-values-1 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-1 %} ```scala mdoc def log(message: String, level: String = "INFO") = println(s"$level: $message") log("System starting") // prints INFO: System starting log("User not found", "WARNING") // prints WARNING: User not found ``` +{% endtab %} +{% endtabs %} + The parameter `level` has a default value so it is optional. On the last line, the argument `"WARNING"` overrides the default argument `"INFO"`. Where you might do overloaded methods in Java, you can use methods with optional parameters to achieve the same effect. However, if the caller omits an argument, any following arguments must be named. +{% tabs default-parameter-values-2 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-2 %} ```scala mdoc class Point(val x: Double = 0, val y: Double = 0) val point1 = new Point(y = 1) ``` +{% endtab %} +{% endtabs %} + Here we have to say `y = 1`. Note that default parameters in Scala are not optional when called from Java code: +{% tabs default-parameter-values-3 %} +{% tab 'Scala 2 and 3' for=default-parameter-values-3 %} ```scala mdoc:reset // Point.scala class Point(val x: Double = 0, val y: Double = 0) ``` +{% endtab %} +{% endtabs %} +{% tabs default-parameter-values-4 %} +{% tab 'Java' for=default-parameter-values-4 %} ```java // Main.java public class Main { @@ -44,3 +60,30 @@ public class Main { } } ``` +{% endtab %} +{% endtabs %} + +### Default Parameters for Overloaded Methods + +Scala doesn't allow having two methods with default parameters and with the same name (overloaded). +An important reason why is to avoid the ambiguity that can be caused due to the existence of default parameters. To illustrate the problem, let's consider the method declarations provided below: + +{% tabs default-parameter-values-5 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala mdoc:fail +object A { + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object A: + def func(x: Int = 34): Unit + def func(y: String = "abc"): Unit +``` +{% endtab %} +{% endtabs %} + +If we call `A.func()`, compiler cannot know whether the programmer intended to call `func(x: Int = 34)` or `func(y: String = "abc")`. diff --git a/_tour/extractor-objects.md b/_tour/extractor-objects.md index b7e08ed708..a859d6cdda 100644 --- a/_tour/extractor-objects.md +++ b/_tour/extractor-objects.md @@ -12,12 +12,15 @@ redirect_from: "/tutorials/tour/extractor-objects.html" An extractor object is an object with an `unapply` method. Whereas the `apply` method is like a constructor which takes arguments and creates an object, the `unapply` takes an object and tries to give back the arguments. This is most often used in pattern matching and partial functions. +{% tabs extractor-objects_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=extractor-objects_definition %} ```scala mdoc import scala.util.Random object CustomerID { - def apply(name: String) = s"$name--${Random.nextLong}" + def apply(name: String) = s"$name--${Random.nextLong()}" def unapply(customerID: String): Option[String] = { val stringArray: Array[String] = customerID.split("--") @@ -31,28 +34,68 @@ customer1ID match { case _ => println("Could not extract a CustomerID") } ``` +{% endtab %} + +{% tab 'Scala 3' for=extractor-objects_definition %} +```scala +import scala.util.Random + +object CustomerID: + + def apply(name: String) = s"$name--${Random.nextLong()}" + + def unapply(customerID: String): Option[String] = + val stringArray: Array[String] = customerID.split("--") + if stringArray.tail.nonEmpty then Some(stringArray.head) else None + +val customer1ID = CustomerID("Sukyoung") // Sukyoung--23098234908 +customer1ID match + case CustomerID(name) => println(name) // prints Sukyoung + case _ => println("Could not extract a CustomerID") +``` +{% endtab %} + +{% endtabs %} The `apply` method creates a `CustomerID` string from a `name`. The `unapply` does the inverse to get the `name` back. When we call `CustomerID("Sukyoung")`, this is shorthand syntax for calling `CustomerID.apply("Sukyoung")`. When we call `case CustomerID(name) => println(name)`, we're calling the unapply method with `CustomerID.unapply(customer1ID)`. Since a value definition can use a pattern to introduce a new variable, an extractor can be used to initialize the variable, where the unapply method supplies the value. +{% tabs extractor-objects_use-case-1 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-1 %} ```scala mdoc val customer2ID = CustomerID("Nico") val CustomerID(name) = customer2ID println(name) // prints Nico ``` +{% endtab %} + +{% endtabs %} This is equivalent to `val name = CustomerID.unapply(customer2ID).get`. +{% tabs extractor-objects_use-case-2 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-2 %} ```scala mdoc val CustomerID(name2) = "--asdfasdfasdf" ``` +{% endtab %} + +{% endtabs %} If there is no match, a `scala.MatchError` is thrown: -```scala +{% tabs extractor-objects_use-case-3 %} + +{% tab 'Scala 2 and 3' for=extractor-objects_use-case-3 %} +```scala mdoc:crash val CustomerID(name3) = "-asdfasdfasdf" ``` +{% endtab %} + +{% endtabs %} The return type of an `unapply` should be chosen as follows: diff --git a/_tour/for-comprehensions.md b/_tour/for-comprehensions.md index 54ed69f0bf..a97758d8b3 100644 --- a/_tour/for-comprehensions.md +++ b/_tour/for-comprehensions.md @@ -7,14 +7,18 @@ num: 19 next-page: generic-classes previous-page: extractor-objects -redirect_from: "/tutorials/tour/for-comprehensions.html" -redirect_from: "/tutorials/tour/sequence-comprehensions.html" +redirect_from: + - "/tutorials/tour/for-comprehensions.html" + - "/tutorials/tour/sequence-comprehensions.html" --- -Scala offers a lightweight notation for expressing *sequence comprehensions*. Comprehensions have the form `for (enumerators) yield e`, where `enumerators` refers to a semicolon-separated list of enumerators. An *enumerator* is either a generator which introduces new variables, or it is a filter. A comprehension evaluates the body `e` for each binding generated by the enumerators and returns a sequence of these values. +Scala offers a lightweight notation for expressing _sequence comprehensions_. Comprehensions have the form `for (enumerators) yield e`, where `enumerators` refers to a list of enumerators. An _enumerator_ is either a generator, or it is a guard (see: [Control Structures](/scala3/book/control-structures.html#for-loops)). A comprehension evaluates the body `e` for each binding generated by the enumerators and returns a sequence of these values. Here's an example: +{% tabs for-comprehensions-01 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-01 %} + ```scala mdoc case class User(name: String, age: Int) @@ -31,23 +35,66 @@ val twentySomethings = twentySomethings.foreach(println) // prints Travis Dennis ``` +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-01 %} + +```scala +case class User(name: String, age: Int) + +val userBase = List( + User("Travis", 28), + User("Kelly", 33), + User("Jennifer", 44), + User("Dennis", 23)) + +val twentySomethings = + for user <- userBase if user.age >=20 && user.age < 30 + yield user.name // i.e. add this to a list + +twentySomethings.foreach(println) // prints Travis Dennis +``` + +{% endtab %} +{% endtabs %} + A `for` loop with a `yield` statement returns a result, the container type of which is determined by the first generator. `user <- userBase` is a `List`, and because we said `yield user.name` where `user.name` is a `String`, the overall result is a `List[String]`. And `if user.age >=20 && user.age < 30` is a guard that filters out users who are not in their twenties. Here is a more complicated example using two generators. It computes all pairs of numbers between `0` and `n-1` whose sum is equal to a given value `v`: +{% tabs for-comprehensions-02 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-02 %} + ```scala mdoc def foo(n: Int, v: Int) = for (i <- 0 until n; j <- 0 until n if i + j == v) yield (i, j) -foo(10, 10) foreach { +foo(10, 10).foreach { case (i, j) => println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) } +``` +{% endtab %} +{% tab 'Scala 3' for=for-comprehensions-02 %} + +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + yield (i, j) + +foo(10, 10).foreach { + (i, j) => println(s"($i, $j) ") // prints (1, 9) (2, 8) (3, 7) (4, 6) (5, 5) (6, 4) (7, 3) (8, 2) (9, 1) +} ``` + +{% endtab %} +{% endtabs %} + Here `n == 10` and `v == 10`. On the first iteration, `i == 0` and `j == 0` so `i + j != v` and therefore nothing is yielded. `j` gets incremented 9 more times before `i` gets incremented to `1`. Without the `if` guard, this would simply print the following: + ```scala (0, 0) (0, 1) (0, 2) (0, 3) (0, 4) (0, 5) (0, 6) (0, 7) (0, 8) (0, 9) (1, 0) ... ``` @@ -56,6 +103,9 @@ Note that comprehensions are not restricted to lists. Every datatype that suppor You can omit `yield` in a comprehension. In that case, comprehension will return `Unit`. This can be useful in case you need to perform side-effects. Here's a program equivalent to the previous one, but without using `yield`: +{% tabs for-comprehensions-03 class=tabs-scala-version %} +{% tab 'Scala 2' for=for-comprehensions-03 %} + ```scala mdoc:nest def foo(n: Int, v: Int) = for (i <- 0 until n; @@ -65,6 +115,22 @@ def foo(n: Int, v: Int) = foo(10, 10) ``` +{% endtab %} + +{% tab 'Scala 3' for=for-comprehensions-03 %} + +```scala +def foo(n: Int, v: Int) = + for i <- 0 until n + j <- 0 until n if i + j == v + do println(s"($i, $j)") + +foo(10, 10) +``` + +{% endtab %} +{% endtabs %} + ## More resources -* Other examples of "For comprehension" in the [Scala Book](/overviews/scala-book/for-expressions.html) +- Other examples of "For comprehension" in the [Scala Book](/scala3/book/control-structures.html#for-expressions) diff --git a/_tour/generic-classes.md b/_tour/generic-classes.md index 0b479d30df..5dbb8990d8 100644 --- a/_tour/generic-classes.md +++ b/_tour/generic-classes.md @@ -10,10 +10,14 @@ assumed-knowledge: classes unified-types redirect_from: "/tutorials/tour/generic-classes.html" --- + Generic classes are classes which take a type as a parameter. They are particularly useful for collection classes. ## Defining a generic class Generic classes take a type as a parameter within square brackets `[]`. One convention is to use the letter `A` as type parameter identifier, though any parameter name may be used. + +{% tabs generic-classes-1 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-1 %} ```scala mdoc class Stack[A] { private var elements: List[A] = Nil @@ -27,6 +31,22 @@ class Stack[A] { } } ``` +{% endtab %} +{% tab 'Scala 3' for=generic-classes-1 %} +```scala +class Stack[A]: + private var elements: List[A] = Nil + def push(x: A): Unit = + elements = x :: elements + def peek: A = elements.head + def pop(): A = + val currentTop = peek + elements = elements.tail + currentTop +``` +{% endtab %} +{% endtabs %} + This implementation of a `Stack` class takes any type `A` as a parameter. This means the underlying list, `var elements: List[A] = Nil`, can only store elements of type `A`. The procedure `def push` only accepts objects of type `A` (note: `elements = x :: elements` reassigns `elements` to a new list created by prepending `x` to the current `elements`). `Nil` here is an empty `List` and is not to be confused with `null`. @@ -34,15 +54,33 @@ This implementation of a `Stack` class takes any type `A` as a parameter. This m ## Usage To use a generic class, put the type in the square brackets in place of `A`. -``` + +{% tabs generic-classes-2 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-2 %} +```scala mdoc val stack = new Stack[Int] stack.push(1) stack.push(2) -println(stack.pop) // prints 2 -println(stack.pop) // prints 1 +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 ``` -The instance `stack` can only take Ints. However, if the type argument had subtypes, those could be passed in: +{% endtab %} +{% tab 'Scala 3' for=generic-classes-2 %} +```scala +val stack = Stack[Int] +stack.push(1) +stack.push(2) +println(stack.pop()) // prints 2 +println(stack.pop()) // prints 1 ``` +{% endtab %} +{% endtabs %} + +The instance `stack` can only take Ints. However, if the type argument had subtypes, those could be passed in: + +{% tabs generic-classes-3 class=tabs-scala-version %} +{% tab 'Scala 2' for=generic-classes-3 %} +```scala mdoc:nest class Fruit class Apple extends Fruit class Banana extends Fruit @@ -54,6 +92,23 @@ val banana = new Banana stack.push(apple) stack.push(banana) ``` +{% endtab %} +{% tab 'Scala 3' for=generic-classes-3 %} +```scala +class Fruit +class Apple extends Fruit +class Banana extends Fruit + +val stack = Stack[Fruit] +val apple = Apple() +val banana = Banana() + +stack.push(apple) +stack.push(banana) +``` +{% endtab %} +{% endtabs %} + Class `Apple` and `Banana` both extend `Fruit` so we can push instances `apple` and `banana` onto the stack of `Fruit`. _Note: subtyping of generic types is *invariant*. This means that if we have a stack of characters of type `Stack[Char]` then it cannot be used as an integer stack of type `Stack[Int]`. This would be unsound because it would enable us to enter true integers into the character stack. To conclude, `Stack[A]` is only a subtype of `Stack[B]` if and only if `B = A`. Since this can be quite restrictive, Scala offers a [type parameter annotation mechanism](variances.html) to control the subtyping behavior of generic types._ diff --git a/_tour/higher-order-functions.md b/_tour/higher-order-functions.md index c56846b81a..7dc08ea005 100644 --- a/_tour/higher-order-functions.md +++ b/_tour/higher-order-functions.md @@ -16,31 +16,54 @@ The terminology can get a bit confusing at this point, and we use the phrase "higher order function" for both methods and functions that take functions as parameters or that return a function. -In a pure Object Oriented world a good practice is to avoid exposing methods parameterized with functions that might leak object's internal state. Leaking internal state might break the invariants of the object itself thus violating encapsulation. +In a pure Object Oriented world, a good practice is to avoid exposing methods parameterised with functions that might leak an object's internal state. Leaking internal state might break the invariants of the object itself, thus violating encapsulation. One of the most common examples is the higher-order function `map` which is available for collections in Scala. -```scala mdoc -val salaries = Seq(20000, 70000, 40000) + +{% tabs map_example_1 %} + +{% tab 'Scala 2 and 3' for=map_example_1 %} +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) val doubleSalary = (x: Int) => x * 2 val newSalaries = salaries.map(doubleSalary) // List(40000, 140000, 80000) ``` +{% endtab %} + +{% endtabs %} + `doubleSalary` is a function which takes a single Int, `x`, and returns `x * 2`. In general, the tuple on the left of the arrow `=>` is a parameter list and the value of the expression on the right is what gets returned. On line 3, the function `doubleSalary` gets applied to each element in the list of salaries. To shrink the code, we could make the function anonymous and pass it directly as an argument to map: -```scala:nest -val salaries = Seq(20000, 70000, 40000) + +{% tabs map_example_2 %} + +{% tab 'Scala 2 and 3' for=map_example_2 %} +```scala mdoc:nest +val salaries = Seq(20_000, 70_000, 40_000) val newSalaries = salaries.map(x => x * 2) // List(40000, 140000, 80000) ``` +{% endtab %} + +{% endtabs %} + Notice how `x` is not declared as an Int in the above example. That's because the -compiler can infer the type based on the type of function map expects (see [Currying](/tour/multiple-parameter-lists.html). An even more idiomatic way to write the same piece of code would be: +compiler can infer the type based on the type of function `map` expects (see [Currying](/tour/multiple-parameter-lists.html)). An even more idiomatic way to write the same piece of code would be: + +{% tabs map_example_3 %} +{% tab 'Scala 2 and 3' for=map_example_3 %} ```scala mdoc:nest -val salaries = Seq(20000, 70000, 40000) +val salaries = Seq(20_000, 70_000, 40_000) val newSalaries = salaries.map(_ * 2) ``` +{% endtab %} + +{% endtabs %} + Since the Scala compiler already knows the type of the parameters (a single Int), you just need to provide the right side of the function. The only caveat is that you need to use `_` in place of a parameter name (it was `x` in @@ -49,6 +72,10 @@ the previous example). ## Coercing methods into functions It is also possible to pass methods as arguments to higher-order functions because the Scala compiler will coerce the method into a function. + +{% tabs Coercing_methods_into_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Coercing_methods_into_functions %} ```scala mdoc case class WeeklyWeatherForecast(temperatures: Seq[Double]) { @@ -57,6 +84,20 @@ case class WeeklyWeatherForecast(temperatures: Seq[Double]) { def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF } ``` +{% endtab %} + +{% tab 'Scala 3' for=Coercing_methods_into_functions %} +```scala +case class WeeklyWeatherForecast(temperatures: Seq[Double]): + + private def convertCtoF(temp: Double) = temp * 1.8 + 32 + + def forecastInFahrenheit: Seq[Double] = temperatures.map(convertCtoF) // <-- passing the method convertCtoF +``` +{% endtab %} + +{% endtabs %} + Here the method `convertCtoF` is passed to the higher order function `map`. This is possible because the compiler coerces `convertCtoF` to the function `x => convertCtoF(x)` (note: `x` will be a generated name which is guaranteed to be unique within its scope). @@ -64,6 +105,9 @@ Here the method `convertCtoF` is passed to the higher order function `map`. This One reason to use higher-order functions is to reduce redundant code. Let's say you wanted some methods that could raise someone's salaries by various factors. Without creating a higher-order function, it might look something like this: +{% tabs Functions_that_accept_functions_1 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_1 %} ```scala mdoc object SalaryRaiser { @@ -77,10 +121,31 @@ object SalaryRaiser { salaries.map(salary => salary * salary) } ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_1 %} +```scala +object SalaryRaiser: + + def smallPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + salaries.map(salary => salary * salary) +``` +{% endtab %} + +{% endtabs %} Notice how each of the three methods vary only by the multiplication factor. To simplify, you can extract the repeated code into a higher-order function like so: +{% tabs Functions_that_accept_functions_2 class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_accept_functions_2 %} ```scala mdoc:nest object SalaryRaiser { @@ -97,17 +162,41 @@ object SalaryRaiser { promotion(salaries, salary => salary * salary) } ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_accept_functions_2 %} +```scala +object SalaryRaiser: + + private def promotion(salaries: List[Double], promotionFunction: Double => Double): List[Double] = + salaries.map(promotionFunction) + + def smallPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * 1.1) + + def greatPromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * math.log(salary)) + + def hugePromotion(salaries: List[Double]): List[Double] = + promotion(salaries, salary => salary * salary) +``` +{% endtab %} + +{% endtabs %} The new method, `promotion`, takes the salaries plus a function of type `Double => Double` (i.e. a function that takes a Double and returns a Double) and returns the product. -Methods and functions usually express behaviours or data transformations, therefore having functions that compose based on other functions can help building generic mechanisms. Those generic operations defer to lock down the entire operation behaviour giving clients a way to control or further customize parts of the operation itself. +Methods and functions usually express behaviours or data transformations. Therefore, having functions that compose based on other functions can allow us to build more generic mechanisms. Such generic operations avoid completely locking down their behaviour in order to give clients a way to control or further customize parts of those operations. ## Functions that return functions There are certain cases where you want to generate a function. Here's an example of a method that returns a function. +{% tabs Functions_that_return_functions class=tabs-scala-version %} + +{% tab 'Scala 2' for=Functions_that_return_functions %} ```scala mdoc def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = { val schema = if (ssl) "https://" else "http://" @@ -120,6 +209,23 @@ val endpoint = "users" val query = "id=1" val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String ``` +{% endtab %} + +{% tab 'Scala 3' for=Functions_that_return_functions %} +```scala +def urlBuilder(ssl: Boolean, domainName: String): (String, String) => String = + val schema = if ssl then "https://" else "http://" + (endpoint: String, query: String) => s"$schema$domainName/$endpoint?$query" + +val domainName = "www.example.com" +def getURL = urlBuilder(ssl=true, domainName) +val endpoint = "users" +val query = "id=1" +val url = getURL(endpoint, query) // "https://www.example.com/users?id=1": String +``` +{% endtab %} + +{% endtabs %} Notice the return type of urlBuilder `(String, String) => String`. This means that the returned anonymous function takes two Strings and returns a String. In this case, diff --git a/_tour/implicit-conversions.md b/_tour/implicit-conversions.md index 4915f51daf..7c0b5840e4 100644 --- a/_tour/implicit-conversions.md +++ b/_tour/implicit-conversions.md @@ -10,51 +10,34 @@ previous-page: implicit-parameters redirect_from: "/tutorials/tour/implicit-conversions.html" --- -An implicit conversion from type `S` to type `T` is defined by an implicit value which has function type `S => T`, or by an implicit method convertible to a value of that type. +Implicit conversions are a powerful Scala feature that enable two common use cases: +- allow users to supply an argument of one type, as if it were another type, to avoid boilerplate. +- in Scala 2, to provide additional members to closed classes (replaced by [extension methods][exts] in Scala 3). + +### Detailed Explanation +{% tabs implicit-conversion-defn class=tabs-scala-version %} +{% tab 'Scala 2' %} +In Scala 2, an implicit conversion from type `S` to type `T` is defined by either an [implicit class]({% link _overviews/core/implicit-classes.md %}) `T` that has a single parameter of type `S`, an [implicit value]({% link _tour/implicit-parameters.md %}) which has function type `S => T`, or by an implicit method convertible to a value of that type. +{% endtab %} +{% tab 'Scala 3' %} +In Scala 3, an implicit conversion from type `S` to type `T` is defined by a [given instance]({% link _tour/implicit-parameters.md %}) which has type `scala.Conversion[S, T]`. For compatibility with Scala 2, they can also be defined by an implicit method (read more in the Scala 2 tab). +{% endtab %} +{% endtabs %} Implicit conversions are applied in two situations: -* If an expression `e` is of type `S`, and `S` does not conform to the expression's expected type `T`. -* In a selection `e.m` with `e` of type `S`, if the selector `m` does not denote a member of `S`. +1. If an expression `e` is of type `S`, and `S` does not conform to the expression's expected type `T`. +2. In a selection `e.m` with `e` of type `S`, if the selector `m` does not denote a member of `S`. -In the first case, a conversion `c` is searched for which is applicable to `e` and whose result type conforms to `T`. -In the second case, a conversion `c` is searched for which is applicable to `e` and whose result contains a member named `m`. +In the first case, a conversion `c` is searched for, which is applicable to `e` and whose result type conforms to `T`. -If an implicit method `List[A] => Ordered[List[A]]` is in scope, as well as an implicit method `Int => Ordered[Int]`, the following operation on the two lists of type `List[Int]` is legal: +An example is to pass a `scala.Int`, e.g. `x`, to a method that expects `scala.Long`. In this case, the implicit conversion `Int.int2long(x)` is inserted. -``` -List(1, 2, 3) <= List(4, 5) -``` -An implicit method `Int => Ordered[Int]` is provided automatically through `scala.Predef.intWrapper`. An example of an implicit method `List[A] => Ordered[List[A]]` is provided below. +In the second case, a conversion `c` is searched for, which is applicable to `e` and whose result contains a member named `m`. -```scala mdoc -import scala.language.implicitConversions +An example is to compare two strings `"foo" < "bar"`. In this case, `String` has no member `<`, so the implicit conversion `Predef.augmentString("foo") < "bar"` is inserted. (`scala.Predef` is automatically imported into all Scala programs.) -implicit def list2ordered[A](x: List[A]) - (implicit elem2ordered: A => Ordered[A]): Ordered[List[A]] = - new Ordered[List[A]] { - //replace with a more useful implementation - def compare(that: List[A]): Int = 1 - } -``` +Further reading: [Implicit Conversions (in the Scala book)]({% link _overviews/scala3-book/ca-implicit-conversions.md %}). -The implicitly imported object `scala.Predef` declares several aliases to frequently used types (e.g. `scala.collection.immutable.Map` is aliased to `Map`) and methods (e.g. `assert`) but also several implicit conversions. - -For example, when calling a Java method that expects a `java.lang.Integer`, you are free to pass it a `scala.Int` instead. That's because Predef includes the following implicit conversions: - -```scala mdoc -import scala.language.implicitConversions - -implicit def int2Integer(x: Int) = - java.lang.Integer.valueOf(x) -``` - -Because implicit conversions can have pitfalls if used indiscriminately the compiler warns when compiling the implicit conversion definition. - -To turn off the warnings take either of these actions: - -* Import `scala.language.implicitConversions` into the scope of the implicit conversion definition -* Invoke the compiler with `-language:implicitConversions` - -No warning is emitted when the conversion is applied by the compiler. +[exts]: {% link _overviews/scala3-book/ca-extension-methods.md %} diff --git a/_tour/implicit-parameters.md b/_tour/implicit-parameters.md index e67d992d79..4d5977f242 100644 --- a/_tour/implicit-parameters.md +++ b/_tour/implicit-parameters.md @@ -1,6 +1,6 @@ --- layout: tour -title: Implicit Parameters +title: Contextual Parameters, aka Implicit Parameters partof: scala-tour num: 28 @@ -10,61 +10,93 @@ previous-page: self-types redirect_from: "/tutorials/tour/implicit-parameters.html" --- -A method can have an _implicit_ parameter list, marked by the _implicit_ keyword at the start of the parameter list. If the parameters in that parameter list are not passed as usual, Scala will look if it can get an implicit value of the correct type, and if it can, pass it automatically. +A method can have *contextual parameters*, also called *implicit parameters*, or more concisely *implicits*. +Parameter lists starting with the keyword `using` (or `implicit` in Scala 2) mark contextual parameters. +Unless the call site explicitly provides arguments for those parameters, Scala will look for implicitly available `given` (or `implicit` in Scala 2) values of the correct type. +If it can find appropriate values, it automatically passes them. -The places Scala will look for these parameters fall into two categories: +This is best shown using a small example first. +We define an interface `Comparator[A]` that can compare elements of type `A`, and provide two implementations, for `Int`s and `String`s. +We then define a method `max[A](x: A, y: A)` that returns the greater of the two arguments. +Since `x` and `y` are generically typed, in general we do not know how to compare them, but we can ask for an appropriate comparator. +As there is typically a canonical comparator for any given type `A`, we can declare them as *given*s, or *implicitly* available. -* Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called. -* Then it looks for members marked implicit in all the companion objects associated with the implicit candidate type. - -A more detailed guide to where Scala looks for implicits can be found in [the FAQ](//docs.scala-lang.org/tutorials/FAQ/finding-implicits.html). - -In the following example we define a method `sum` which computes the sum of a list of elements using the monoid's `add` and `unit` operations. Please note that implicit values cannot be top-level. +{% tabs implicits-comparator class=tabs-scala-version %} +{% tab 'Scala 2' for=implicits-comparator %} ```scala mdoc -abstract class Monoid[A] { - def add(x: A, y: A): A - def unit: A +trait Comparator[A] { + def compare(x: A, y: A): Int } -object ImplicitTest { - implicit val stringMonoid: Monoid[String] = new Monoid[String] { - def add(x: String, y: String): String = x concat y - def unit: String = "" +object Comparator { + implicit object IntComparator extends Comparator[Int] { + def compare(x: Int, y: Int): Int = Integer.compare(x, y) } - - implicit val intMonoid: Monoid[Int] = new Monoid[Int] { - def add(x: Int, y: Int): Int = x + y - def unit: Int = 0 - } - - def sum[A](xs: List[A])(implicit m: Monoid[A]): A = - if (xs.isEmpty) m.unit - else m.add(xs.head, sum(xs.tail)) - - def main(args: Array[String]): Unit = { - println(sum(List(1, 2, 3))) // uses intMonoid implicitly - println(sum(List("a", "b", "c"))) // uses stringMonoid implicitly + + implicit object StringComparator extends Comparator[String] { + def compare(x: String, y: String): Int = x.compareTo(y) } } -``` -`Monoid` defines an operation called `add` here, that combines a pair of `A`s and returns another `A`, together with an operation called `unit` that is able to create some (specific) `A`. +def max[A](x: A, y: A)(implicit comparator: Comparator[A]): A = + if (comparator.compare(x, y) >= 0) x + else y + +println(max(10, 6)) // 10 +println(max("hello", "world")) // world +``` -To show how implicit parameters work, we first define monoids `stringMonoid` and `intMonoid` for strings and integers, respectively. The `implicit` keyword indicates that the corresponding object can be used implicitly. +```scala mdoc:fail +// does not compile: +println(max(false, true)) +// ^ +// error: could not find implicit value for parameter comparator: Comparator[Boolean] +``` -The method `sum` takes a `List[A]` and returns an `A`, which takes the initial `A` from `unit`, and combines each next `A` in the list to that with the `add` method. Making the parameter `m` implicit here means we only have to provide the `xs` parameter when we call the method if Scala can find an implicit `Monoid[A]` to use for the implicit `m` parameter. +The `comparator` parameter is automatically filled in with `Comparator.IntComparator` for `max(10, 6)`, and with `Comparator.StringComparator` for `max("hello", "world")`. +Since no implicit `Comparator[Boolean]` can be found, the call `max(false, true)` fails to compile. +{% endtab %} -In our `main` method we call `sum` twice, and only provide the `xs` parameter. Scala will now look for an implicit in the scope mentioned above. The first call to `sum` passes a `List[Int]` for `xs`, which means that `A` is `Int`. The implicit parameter list with `m` is left out, so Scala will look for an implicit of type `Monoid[Int]`. The first lookup rule reads +{% tab 'Scala 3' for=implicits-comparator %} +```scala +trait Comparator[A]: + def compare(x: A, y: A): Int -> Scala will first look for implicit definitions and implicit parameters that can be accessed directly (without a prefix) at the point the method with the implicit parameter block is called. +object Comparator: + given Comparator[Int] with + def compare(x: Int, y: Int): Int = Integer.compare(x, y) -`intMonoid` is an implicit definition that can be accessed directly in `main`. It is also of the correct type, so it's passed to the `sum` method automatically. + given Comparator[String] with + def compare(x: String, y: String): Int = x.compareTo(y) +end Comparator -The second call to `sum` passes a `List[String]`, which means that `A` is `String`. Implicit lookup will go the same way as with `Int`, but will this time find `stringMonoid`, and pass that automatically as `m`. +def max[A](x: A, y: A)(using comparator: Comparator[A]): A = + if comparator.compare(x, y) >= 0 then x + else y -The program will output +println(max(10, 6)) // 10 +println(max("hello", "world")) // world ``` -6 -abc + +```scala +// does not compile: +println(max(false, true)) +-- Error: ---------------------------------------------------------------------- +1 |println(max(false, true)) + | ^ + |no given instance of type Comparator[Boolean] was found for parameter comparator of method max ``` + +The `comparator` parameter is automatically filled in with the `given Comparator[Int]` for `max(10, 6)`, and with the `given Comparator[String]` for `max("hello", "world")`. +Since no `given Comparator[Boolean]` can be found, the call `max(false, true)` fails to compile. +{% endtab %} + +{% endtabs %} + +Scala will look for available given values in two places: + +* Scala will first look for given definitions and using parameters that can be accessed directly (without a prefix) at the call site of `max`. +* Then it looks for members marked `given`/`implicit` in the companion objects associated with the implicit candidate type (for example: `object Comparator` for the candidate type `Comparator[Int]`). + +A more detailed guide to where Scala looks for implicits can be found in [the FAQ](/tutorials/FAQ/finding-implicits.html). diff --git a/_tour/inner-classes.md b/_tour/inner-classes.md index fc9e4f150a..e2d94542b4 100644 --- a/_tour/inner-classes.md +++ b/_tour/inner-classes.md @@ -14,6 +14,8 @@ In Scala it is possible to let classes have other classes as members. As opposed To illustrate the difference, we quickly sketch the implementation of a graph datatype: +{% tabs inner-classes_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_1 %} ```scala mdoc class Graph { class Node { @@ -32,8 +34,29 @@ class Graph { } } ``` +{% endtab %} +{% tab 'Scala 3' for=inner-classes_1 %} +```scala +class Graph: + class Node: + var connectedNodes: List[Node] = Nil + def connectTo(node: Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` +{% endtab %} +{% endtabs %} + This program represents a graph as a list of nodes (`List[Node]`). Each node has a list of other nodes it's connected to (`connectedNodes`). The `class Node` is a _path-dependent type_ because it is nested in the `class Graph`. Therefore, all nodes in the `connectedNodes` must be created using the `newNode` from the same instance of `Graph`. +{% tabs inner-classes_2 %} +{% tab 'Scala 2 and 3' for=inner-classes_2 %} ```scala mdoc val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode @@ -42,11 +65,16 @@ val node3: graph1.Node = graph1.newNode node1.connectTo(node2) node3.connectTo(node1) ``` +{% endtab %} +{% endtabs %} + We have explicitly declared the type of `node1`, `node2`, and `node3` as `graph1.Node` for clarity but the compiler could have inferred it. This is because when we call `graph1.newNode` which calls `new Node`, the method is using the instance of `Node` specific to the instance `graph1`. If we now have two graphs, the type system of Scala does not allow us to mix nodes defined within one graph with the nodes of another graph, since the nodes of the other graph have a different type. Here is an illegal program: +{% tabs inner-classes_3 %} +{% tab 'Scala 2 and 3' for=inner-classes_3 %} ```scala mdoc:fail val graph1: Graph = new Graph val node1: graph1.Node = graph1.newNode @@ -56,8 +84,13 @@ val graph2: Graph = new Graph val node3: graph2.Node = graph2.newNode node1.connectTo(node3) // illegal! ``` +{% endtab %} +{% endtabs %} + The type `graph1.Node` is distinct from the type `graph2.Node`. In Java, the last line in the previous example program would have been correct. For nodes of both graphs, Java would assign the same type `Graph.Node`; i.e. `Node` is prefixed with class `Graph`. In Scala such a type can be expressed as well, it is written `Graph#Node`. If we want to be able to connect nodes of different graphs, we have to change the definition of our initial graph implementation in the following way: +{% tabs inner-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=inner-classes_4 %} ```scala mdoc:nest class Graph { class Node { @@ -76,3 +109,21 @@ class Graph { } } ``` +{% endtab %} +{% tab 'Scala 3' for=inner-classes_4 %} +```scala +class Graph: + class Node: + var connectedNodes: List[Graph#Node] = Nil + def connectTo(node: Graph#Node): Unit = + if !connectedNodes.exists(node.equals) then + connectedNodes = node :: connectedNodes + + var nodes: List[Node] = Nil + def newNode: Node = + val res = Node() + nodes = res :: nodes + res +``` +{% endtab %} +{% endtabs %} diff --git a/_tour/lower-type-bounds.md b/_tour/lower-type-bounds.md index a1cdb9648f..bac1883358 100644 --- a/_tour/lower-type-bounds.md +++ b/_tour/lower-type-bounds.md @@ -15,53 +15,93 @@ While [upper type bounds](upper-type-bounds.html) limit a type to a subtype of a Here is an example where this is useful: +{% tabs upper-type-bounds_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_1 %} ```scala mdoc:fail -trait Node[+B] { - def prepend(elem: B): Node[B] +trait List[+A] { + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) } -case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { - def prepend(elem: B): ListNode[B] = ListNode(elem, this) - def head: B = h - def tail: Node[B] = t -} +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] -case class Nil[+B]() extends Node[B] { - def prepend(elem: B): ListNode[B] = ListNode(elem, this) -} +object Nil extends List[Nothing] +``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_1 %} +```scala +trait List[+A]: + def prepend(elem: A): NonEmptyList[A] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] ``` +{% endtab %} +{% endtabs %} -This program implements a singly-linked list. `Nil` represents an empty element (i.e. an empty list). `class ListNode` is a node which contains an element of type `B` (`head`) and a reference to the rest of the list (`tail`). The `class Node` and its subtypes are covariant because we have `+B`. +This program implements a singly-linked list. `Nil` represents an empty list with no elements. `class NonEmptyList` is a node which contains an element of type `A` (`head`) and a reference to the rest of the list (`tail`). The `trait List` and its subtypes are covariant because we have `+A`. -However, this program does _not_ compile because the parameter `elem` in `prepend` is of type `B`, which we declared *co*variant. This doesn't work because functions are *contra*variant in their parameter types and *co*variant in their result types. +However, this program does _not_ compile because the parameter `elem` in `prepend` is of type `A`, which we declared *co*variant. This doesn't work because functions are *contra*variant in their parameter types and *co*variant in their result types. -To fix this, we need to flip the variance of the type of the parameter `elem` in `prepend`. We do this by introducing a new type parameter `U` that has `B` as a lower type bound. +To fix this, we need to flip the variance of the type of the parameter `elem` in `prepend`. We do this by introducing a new type parameter `B` that has `A` as a lower type bound. +{% tabs upper-type-bounds_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=upper-type-bounds_2 %} ```scala mdoc -trait Node[+B] { - def prepend[U >: B](elem: U): Node[U] +trait List[+A] { + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) } -case class ListNode[+B](h: B, t: Node[B]) extends Node[B] { - def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) - def head: B = h - def tail: Node[B] = t -} +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] -case class Nil[+B]() extends Node[B] { - def prepend[U >: B](elem: U): ListNode[U] = ListNode(elem, this) -} +object Nil extends List[Nothing] +``` +{% endtab %} +{% tab 'Scala 3' for=upper-type-bounds_2 %} +```scala +trait List[+A]: + def prepend[B >: A](elem: B): NonEmptyList[B] = NonEmptyList(elem, this) + +case class NonEmptyList[+A](head: A, tail: List[A]) extends List[A] + +object Nil extends List[Nothing] ``` +{% endtab %} +{% endtabs %} Now we can do the following: + +{% tabs upper-type-bounds_3 %} +{% tab 'Scala 2 and 3' for=upper-type-bounds_3 %} ```scala mdoc trait Bird case class AfricanSwallow() extends Bird case class EuropeanSwallow() extends Bird +val africanSwallows: List[AfricanSwallow] = Nil.prepend(AfricanSwallow()) +val swallowsFromAntarctica: List[Bird] = Nil +val someBird: Bird = EuropeanSwallow() + +// assign swallows to birds +val birds: List[Bird] = africanSwallows + +// add some bird to swallows, `B` is `Bird` +val someBirds = africanSwallows.prepend(someBird) + +// add a swallow to birds +val moreBirds = birds.prepend(EuropeanSwallow()) -val africanSwallowList = ListNode[AfricanSwallow](AfricanSwallow(), Nil()) -val birdList: Node[Bird] = africanSwallowList -birdList.prepend(EuropeanSwallow()) +// add disparate swallows together, `B` is `Bird` because that is the supertype common to both swallows +val allBirds = africanSwallows.prepend(EuropeanSwallow()) + +// but this is a mistake! adding a list of birds widens the type arg too much. -Xlint will warn! +val error = moreBirds.prepend(swallowsFromAntarctica) // List[Object] ``` -The `Node[Bird]` can be assigned the `africanSwallowList` but then accept `EuropeanSwallow`s. +{% endtab %} +{% endtabs %} + +The covariant type parameter allows `birds` to get the value of `africanSwallows`. + +The type bound on the type parameter for `prepend` allows adding different varieties of swallows and getting a wider type: instead of `List[AfricanSwallow]`, we get a `List[Bird]`. + +Use `-Xlint` to warn if the inferred type arg is widened too much. diff --git a/_tour/mixin-class-composition.md b/_tour/mixin-class-composition.md index fc362b2643..27eeafbf61 100644 --- a/_tour/mixin-class-composition.md +++ b/_tour/mixin-class-composition.md @@ -12,6 +12,9 @@ redirect_from: "/tutorials/tour/mixin-class-composition.html" --- Mixins are traits which are used to compose a class. +{% tabs mixin-first-exemple class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-first-exemple %} ```scala mdoc abstract class A { val message: String @@ -30,8 +33,33 @@ println(d.loudMessage) // I'M AN INSTANCE OF CLASS B ``` Class `D` has a superclass `B` and a mixin `C`. Classes can only have one superclass but many mixins (using the keywords `extends` and `with` respectively). The mixins and the superclass may have the same supertype. +{% endtab %} + +{% tab 'Scala 3' for=mixin-first-exemple %} +```scala +abstract class A: + val message: String +class B extends A: + val message = "I'm an instance of class B" +trait C extends A: + def loudMessage = message.toUpperCase() +class D extends B, C + +val d = D() +println(d.message) // I'm an instance of class B +println(d.loudMessage) // I'M AN INSTANCE OF CLASS B +``` +Class `D` has a superclass `B` and a mixin `C`. Classes can only have one superclass but many mixins (using the keyword `extends` and the separator `,` respectively). The mixins and the superclass may have the same supertype. + +{% endtab %} + +{% endtabs %} + Now let's look at a more interesting example starting with an abstract class: +{% tabs mixin-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-abstract-iterator %} ```scala mdoc abstract class AbsIterator { type T @@ -39,10 +67,26 @@ abstract class AbsIterator { def next(): T } ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-abstract-iterator %} +```scala +abstract class AbsIterator: + type T + def hasNext: Boolean + def next(): T +``` +{% endtab %} + +{% endtabs %} + The class has an abstract type `T` and the standard iterator methods. Next, we'll implement a concrete class (all abstract members `T`, `hasNext`, and `next` have implementations): +{% tabs mixin-concrete-string-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-concrete-string-iterator %} ```scala mdoc class StringIterator(s: String) extends AbsIterator { type T = Char @@ -55,10 +99,30 @@ class StringIterator(s: String) extends AbsIterator { } } ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-concrete-string-iterator %} +```scala +class StringIterator(s: String) extends AbsIterator: + type T = Char + private var i = 0 + def hasNext = i < s.length + def next() = + val ch = s charAt i + i += 1 + ch +``` +{% endtab %} + +{% endtabs %} + `StringIterator` takes a `String` and can be used to iterate over the String (e.g. to see if a String contains a certain character). Now let's create a trait which also extends `AbsIterator`. +{% tabs mixin-extended-abstract-iterator class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-extended-abstract-iterator %} ```scala mdoc trait RichIterator extends AbsIterator { def foreach(f: T => Unit): Unit = while (hasNext) f(next()) @@ -66,13 +130,41 @@ trait RichIterator extends AbsIterator { ``` This trait implements `foreach` by continually calling the provided function `f: T => Unit` on the next element (`next()`) as long as there are further elements (`while (hasNext)`). Because `RichIterator` is a trait, it doesn't need to implement the abstract members of AbsIterator. +{% endtab %} + +{% tab 'Scala 3' for=mixin-extended-abstract-iterator %} +```scala +trait RichIterator extends AbsIterator: + def foreach(f: T => Unit): Unit = while hasNext do f(next()) +``` +This trait implements `foreach` by continually calling the provided function `f: T => Unit` on the next element (`next()`) as long as there are further elements (`while hasNext`). Because `RichIterator` is a trait, it doesn't need to implement the abstract members of AbsIterator. + +{% endtab %} + +{% endtabs %} + We would like to combine the functionality of `StringIterator` and `RichIterator` into a single class. +{% tabs mixin-combination-class class=tabs-scala-version %} + +{% tab 'Scala 2' for=mixin-combination-class %} ```scala mdoc class RichStringIter extends StringIterator("Scala") with RichIterator val richStringIter = new RichStringIter richStringIter.foreach(println) ``` +{% endtab %} + +{% tab 'Scala 3' for=mixin-combination-class %} +```scala +class RichStringIter extends StringIterator("Scala"), RichIterator +val richStringIter = RichStringIter() +richStringIter.foreach(println) +``` +{% endtab %} + +{% endtabs %} + The new class `RichStringIter` has `StringIterator` as a superclass and `RichIterator` as a mixin. With single inheritance we would not be able to achieve this level of flexibility. diff --git a/_tour/multiple-parameter-lists.md b/_tour/multiple-parameter-lists.md index 9aa3add880..324795b6c0 100644 --- a/_tour/multiple-parameter-lists.md +++ b/_tour/multiple-parameter-lists.md @@ -1,6 +1,6 @@ --- layout: tour -title: Multiple Parameter Lists (Currying) +title: Multiple Parameter Lists partof: scala-tour num: 12 @@ -16,6 +16,9 @@ Methods may have multiple parameter lists. Here is an example, as defined on the `Iterable` trait in Scala's collections API: +{% tabs foldLeft_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=foldLeft_definition %} ```scala trait Iterable[A] { ... @@ -23,18 +26,34 @@ trait Iterable[A] { ... } ``` +{% endtab %} + +{% tab 'Scala 3' for=foldLeft_definition %} +```scala +trait Iterable[A]: + ... + def foldLeft[B](z: B)(op: (B, A) => B): B + ... +``` +{% endtab %} + +{% endtabs %} `foldLeft` applies a two-parameter function `op` to an initial value `z` and all elements of this collection, going left to right. Shown below is an example of its usage. Starting with an initial value of 0, `foldLeft` here applies the function `(m, n) => m + n` to each element in the List and the previous accumulated value. -{% scalafiddle %} +{% tabs foldLeft_use %} + +{% tab 'Scala 2 and 3' for=foldLeft_use %} ```scala mdoc val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) val res = numbers.foldLeft(0)((m, n) => m + n) println(res) // 55 ``` -{% endscalafiddle %} +{% endtab %} + +{% endtabs %} ### Use cases @@ -45,29 +64,53 @@ Suggested use cases for multiple parameter lists include: It so happens that in Scala, type inference proceeds one parameter list at a time. Say you have the following method: +{% tabs foldLeft1_definition %} + +{% tab 'Scala 2 and 3' for=foldLeft1_definition %} ```scala mdoc def foldLeft1[A, B](as: List[A], b0: B, op: (B, A) => B) = ??? ``` +{% endtab %} + +{% endtabs %} Then you'd like to call it in the following way, but will find that it doesn't compile: +{% tabs foldLeft1_wrong_use %} + +{% tab 'Scala 2 and 3' for=foldLeft1_wrong_use %} ```scala mdoc:fail def notPossible = foldLeft1(numbers, 0, _ + _) ``` +{% endtab %} + +{% endtabs %} you will have to call it like one of the below ways: +{% tabs foldLeft1_good_use %} + +{% tab 'Scala 2 and 3' for=foldLeft1_good_use %} ```scala mdoc def firstWay = foldLeft1[Int, Int](numbers, 0, _ + _) def secondWay = foldLeft1(numbers, 0, (a: Int, b: Int) => a + b) ``` +{% endtab %} + +{% endtabs %} That's because Scala won't be able to infer the type of the function `_ + _`, as it's still inferring `A` and `B`. By moving the parameter `op` to its own parameter list, `A` and `B` are inferred in the first parameter list. These inferred types will then be available to the second parameter list and `_ + _` will match the inferred type `(Int, Int) => Int` +{% tabs foldLeft2_definition_and_use %} + +{% tab 'Scala 2 and 3' for=foldLeft2_definition_and_use %} ```scala mdoc def foldLeft2[A, B](as: List[A], b0: B)(op: (B, A) => B) = ??? def possible = foldLeft2(numbers, 0)(_ + _) ``` +{% endtab %} + +{% endtabs %} This definition doesn't need any type hints and can infer all of its type parameters. @@ -78,9 +121,21 @@ To specify only certain parameters as [`implicit`](https://docs.scala-lang.org/t An example of this is: +{% tabs execute_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=execute_definition %} ```scala mdoc def execute(arg: Int)(implicit ec: scala.concurrent.ExecutionContext) = ??? ``` +{% endtab %} + +{% tab 'Scala 3' for=execute_definition %} +```scala +def execute(arg: Int)(using ec: scala.concurrent.ExecutionContext) = ??? +``` +{% endtab %} + +{% endtabs %} #### Partial application @@ -88,6 +143,9 @@ When a method is called with a fewer number of parameter lists, then this will y For example, +{% tabs foldLeft_partial class=tabs-scala-version %} + +{% tab 'Scala 2' for=foldLeft_partial %} ```scala mdoc:nest val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) val numberFunc = numbers.foldLeft(List[Int]()) _ @@ -98,3 +156,63 @@ println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) val cubes = numberFunc((xs, x) => xs :+ x*x*x) println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) ``` +{% endtab %} + +{% tab 'Scala 3' for=foldLeft_partial %} +```scala +val numbers = List(1, 2, 3, 4, 5, 6, 7, 8, 9, 10) +val numberFunc = numbers.foldLeft(List[Int]()) + +val squares = numberFunc((xs, x) => xs :+ x*x) +println(squares) // List(1, 4, 9, 16, 25, 36, 49, 64, 81, 100) + +val cubes = numberFunc((xs, x) => xs :+ x*x*x) +println(cubes) // List(1, 8, 27, 64, 125, 216, 343, 512, 729, 1000) +``` +{% endtab %} + +{% endtabs %} + +### Comparison with "currying" + +You may sometimes see a method with multiple parameter lists referred to as "curried". + +As the [Wikipedia article on currying](https://en.wikipedia.org/wiki/Currying) states, + +> Currying is the technique of converting a function that takes +> multiple arguments into a sequence of functions that each takes a +> single argument + +We discourage the use of the word "curry" in reference to Scala's multiple parameter lists, for two reasons: + +1) In Scala, multiple parameters and multiple parameter lists are +specified and implemented directly, as part of the language, rather +being derived from single-parameter functions. + +2) There is danger of confusion with the Scala standard library's +[`curried`](https://www.scala-lang.org/api/current/scala/Function2.html#curried:T1=%3E(T2=%3ER)) +and [`uncurried`](https://www.scala-lang.org/api/current/scala/Function$.html#uncurried[T1,T2,R](f:T1=%3E(T2=%3ER)):(T1,T2)=%3ER) methods, which don't involve multiple parameter lists at all. + +Regardless, there are certainly similarities to be found between +multiple parameter lists and currying. Though they are different at +the definition site, the call site might nonetheless look identical, +as in this example: + +{% tabs about_currying %} + +{% tab 'Scala 2 and 3' for=about_currying %} +```scala mdoc +// version with multiple parameter lists +def addMultiple(n1: Int)(n2: Int) = n1 + n2 +// two different ways of arriving at a curried version instead +def add(n1: Int, n2: Int) = n1 + n2 +val addCurried1 = (add _).curried +val addCurried2 = (n1: Int) => (n2: Int) => n1 + n2 +// regardless, all three call sites are identical +addMultiple(3)(4) // 7 +addCurried1(3)(4) // 7 +addCurried2(3)(4) // 7 +``` +{% endtab %} + +{% endtabs %} diff --git a/_tour/named-arguments.md b/_tour/named-arguments.md index 3dc7a4a503..cec14a5ebf 100644 --- a/_tour/named-arguments.md +++ b/_tour/named-arguments.md @@ -8,25 +8,50 @@ next-page: traits previous-page: default-parameter-values prerequisite-knowledge: function-syntax -redirect_from: "/tutorials/tour/named-arguments.html" -redirect_from: "/tutorials/tour/named-parameters.html" +redirect_from: + - "/tutorials/tour/named-arguments.html" + - "/tutorials/tour/named-parameters.html" --- When calling methods, you can label the arguments with their parameter names like so: +{% tabs named-arguments-when-good %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-good %} ```scala mdoc -def printName(first: String, last: String): Unit = { - println(first + " " + last) -} +def printName(first: String, last: String): Unit = + println(s"$first $last") -printName("John", "Smith") // Prints "John Smith" -printName(first = "John", last = "Smith") // Prints "John Smith" -printName(last = "Smith", first = "John") // Prints "John Smith" +printName("John", "Public") // Prints "John Public" +printName(first = "John", last = "Public") // Prints "John Public" +printName(last = "Public", first = "John") // Prints "John Public" +printName("Elton", last = "John") // Prints "Elton John" ``` -Notice how the order of named arguments can be rearranged. However, if some arguments are named and others are not, the unnamed arguments must come first and in the order of their parameters in the method signature. +{% endtab %} + +{% endtabs %} + +This is useful when two parameters have the same type and the arguments could be accidentally swapped. + +Notice that named arguments can be written in any order. However, once the arguments are not in parameter order, reading from left to right, then the rest of the arguments must be named. +In the following example, named arguments enable the middle parameter to be omitted. But in the error case, the first argument is out of order, so the second argument must be named. + +{% tabs named-arguments-when-error %} + +{% tab 'Scala 2 and 3' for=named-arguments-when-error %} ```scala mdoc:fail -printName(last = "Smith", "john") // error: positional after named argument +def printFullName(first: String, middle: String = "Q.", last: String): Unit = + println(s"$first $middle $last") + +printFullName(first = "John", last = "Public") // Prints "John Q. Public" +printFullName("John", last = "Public") // Prints "John Q. Public" +printFullName("John", middle = "Quincy", "Public") // Prints "John Quincy Public" +printFullName(last = "Public", first = "John") // Prints "John Q. Public" +printFullName(last = "Public", "John") // error: positional after named argument ``` +{% endtab %} + +{% endtabs %} -Named arguments work with calls to Java methods, but only if the Java library in question was compiled with `-parameters`. +Named arguments work with calls to Java methods, but only if the Java library in question was compiled with the `-parameters` flag. diff --git a/_tour/nested-functions.md b/_tour/nested-functions.md index a250fc2238..45d00e2db6 100644 --- a/_tour/nested-functions.md +++ b/_tour/nested-functions.md @@ -12,24 +12,48 @@ redirect_from: "/tutorials/tour/nested-functions.html" In Scala it is possible to nest method definitions. The following object provides a `factorial` method for computing the factorial of a given number: -{% scalafiddle %} +{% tabs Nested_functions_definition class=tabs-scala-version %} + +{% tab 'Scala 2' for=Nested_functions_definition %} ```scala mdoc - def factorial(x: Int): Int = { - def fact(x: Int, accumulator: Int): Int = { - if (x <= 1) accumulator - else fact(x - 1, x * accumulator) - } - fact(x, 1) - } - - println("Factorial of 2: " + factorial(2)) - println("Factorial of 3: " + factorial(3)) +def factorial(x: Int): Int = { + def fact(x: Int, accumulator: Int): Int = { + if (x <= 1) accumulator + else fact(x - 1, x * accumulator) + } + fact(x, 1) +} + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) ``` -{% endscalafiddle %} +{% endtab %} + +{% tab 'Scala 3' for=Nested_functions_definition %} +```scala +def factorial(x: Int): Int = + def fact(x: Int, accumulator: Int): Int = + if x <= 1 then accumulator + else fact(x - 1, x * accumulator) + fact(x, 1) + +println("Factorial of 2: " + factorial(2)) +println("Factorial of 3: " + factorial(3)) + +``` +{% endtab %} + +{% endtabs %} The output of this program is: +{% tabs Nested_functions_result %} + +{% tab 'Scala 2 and 3' for=Nested_functions_result %} ``` Factorial of 2: 2 Factorial of 3: 6 ``` +{% endtab %} + +{% endtabs %} diff --git a/_tour/operators.md b/_tour/operators.md index 38fd1a426c..fb157ce334 100644 --- a/_tour/operators.md +++ b/_tour/operators.md @@ -11,17 +11,30 @@ prerequisite-knowledge: case-classes redirect_from: "/tutorials/tour/operators.html" --- In Scala, operators are methods. Any method with a single parameter can be used as an _infix operator_. For example, `+` can be called with dot-notation: + +{% tabs operators_1 %} +{% tab 'Scala 2 and 3' for=operators_1 %} ``` 10.+(1) ``` +{% endtab %} +{% endtabs %} However, it's easier to read as an infix operator: + +{% tabs operators_2 %} +{% tab 'Scala 2 and 3' for=operators_2 %} ``` 10 + 1 ``` +{% endtab %} +{% endtabs %} ## Defining and using operators You can use any legal identifier as an operator. This includes a name like `add` or a symbol(s) like `+`. + +{% tabs operators_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_3 %} ```scala mdoc case class Vec(x: Double, y: Double) { def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) @@ -34,8 +47,26 @@ val vector3 = vector1 + vector2 vector3.x // 3.0 vector3.y // 3.0 ``` +{% endtab %} +{% tab 'Scala 3' for=operators_3 %} +```scala +case class Vec(x: Double, y: Double): + def +(that: Vec) = Vec(this.x + that.x, this.y + that.y) + +val vector1 = Vec(1.0, 1.0) +val vector2 = Vec(2.0, 2.0) + +val vector3 = vector1 + vector2 +vector3.x // 3.0 +vector3.y // 3.0 +``` +{% endtab %} +{% endtabs %} + The class Vec has a method `+` which we used to add `vector1` and `vector2`. Using parentheses, you can build up complex expressions with readable syntax. Here is the definition of class `MyBool` which includes methods `and` and `or`: +{% tabs operators_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=operators_4 %} ```scala mdoc case class MyBool(x: Boolean) { def and(that: MyBool): MyBool = if (x) that else this @@ -43,13 +74,27 @@ case class MyBool(x: Boolean) { def negate: MyBool = MyBool(!x) } ``` +{% endtab %} +{% tab 'Scala 3' for=operators_4 %} +```scala +case class MyBool(x: Boolean): + def and(that: MyBool): MyBool = if x then that else this + def or(that: MyBool): MyBool = if x then this else that + def negate: MyBool = MyBool(!x) +``` +{% endtab %} +{% endtabs %} It is now possible to use `and` and `or` as infix operators: +{% tabs operators_5 %} +{% tab 'Scala 2 and 3' for=operators_5 %} ```scala mdoc def not(x: MyBool) = x.negate def xor(x: MyBool, y: MyBool) = (x or y) and not(x and y) ``` +{% endtab %} +{% endtabs %} This helps to make the definition of `xor` more readable. @@ -60,19 +105,31 @@ When an expression uses multiple operators, the operators are evaluated based on * / % + - : -= ! < > += ! & ^ | -(all letters) +(all letters, $, _) ``` This applies to functions you define. For example, the following expression: + +{% tabs operators_7 %} +{% tab 'Scala 2 and 3' for=operators_7 %} ``` a + b ^? c ?^ d less a ==> b | c ``` +{% endtab %} +{% endtabs %} + Is equivalent to + +{% tabs operators_8 %} +{% tab 'Scala 2 and 3' for=operators_8 %} ``` ((a + b) ^? (c ?^ d)) less ((a ==> b) | c) ``` +{% endtab %} +{% endtabs %} + `?^` has the highest precedence because it starts with the character `?`. `+` has the second highest precedence, followed by `==>`, `^?`, `|`, and `less`. diff --git a/_tour/package-objects.md b/_tour/package-objects.md index 0b785361b8..8be239c933 100644 --- a/_tour/package-objects.md +++ b/_tour/package-objects.md @@ -1,29 +1,50 @@ --- layout: tour -title: Package Objects +title: Top Level Definitions in Packages partof: scala-tour num: 36 previous-page: packages-and-imports --- -# Package objects +Often, it is convenient to have definitions accessible across an entire package, and not need to invent a +name for a wrapper `object` to contain them. -Scala provides package objects as a convenient container shared across an entire package. +{% tabs pkg-obj-vs-top-lvl_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_1 %} +Scala 2 provides _package objects_ as a convenient container shared across an entire package. Package objects can contain arbitrary definitions, not just variable and method definitions. For instance, they are frequently used to hold package-wide type aliases and implicit conversions. Package objects can even inherit Scala classes and traits. +> In a future version of Scala 3, package objects will be removed in favor of top level definitions. + By convention, the source code for a package object is usually put in a source file named `package.scala`. Each package is allowed to have one package object. Any definitions placed in a package object are considered members of the package itself. +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_1 %} +In Scala 3, any kind of definition can be declared at the top level of a package. For example, classes, enums, +methods and variables. + +Any definitions placed at the top level of a package are considered members of the package itself. + +> In Scala 2, top-level method, type and variable definitions had to be wrapped in a **package object**. +> These are still usable in Scala 3 for backwards compatibility. You can see how they work by switching tabs. + +{% endtab %} +{% endtabs %} + See example below. Assume first a class `Fruit` and three `Fruit` objects in a package `gardening.fruits`: + +{% tabs pkg-obj-vs-top-lvl_2 %} +{% tab 'Scala 2 and 3' for=pkg-obj-vs-top-lvl_2 %} ``` // in file gardening/fruits/Fruit.scala package gardening.fruits @@ -33,10 +54,15 @@ object Apple extends Fruit("Apple", "green") object Plum extends Fruit("Plum", "blue") object Banana extends Fruit("Banana", "yellow") ``` +{% endtab %} +{% endtabs %} Now assume you want to place a variable `planted` and a method `showFruit` directly into package `gardening.fruits`. Here's how this is done: +{% tabs pkg-obj-vs-top-lvl_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_3 %} + ``` // in file gardening/fruits/package.scala package gardening @@ -47,13 +73,29 @@ package object fruits { } } ``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_3 %} + +``` +// in file gardening/fruits/package.scala +package gardening.fruits + +val planted = List(Apple, Plum, Banana) +def showFruit(fruit: Fruit): Unit = + println(s"${fruit.name}s are ${fruit.color}") +``` +{% endtab %} +{% endtabs %} -As an example of how the use site looks, the following object `PrintPlanted` imports `planted` and `showFruit` in exactly the same -way it imports class `Fruit`, using a wildcard import on package gardening.fruits: +As an example of how to use this, the following program imports `planted` and `showFruit` in exactly the same +way it imports class `Fruit`, using a wildcard import on package `gardening.fruits`: +{% tabs pkg-obj-vs-top-lvl_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_4 %} ``` // in file PrintPlanted.scala import gardening.fruits._ + object PrintPlanted { def main(args: Array[String]): Unit = { for (fruit <- planted) { @@ -62,11 +104,53 @@ object PrintPlanted { } } ``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_4 %} +``` +// in file printPlanted.scala +import gardening.fruits.* -Package objects are like other objects, which means you can use inheritance for building them. For example, one might mix in a couple of traits: +@main def printPlanted(): Unit = + for fruit <- planted do + showFruit(fruit) +``` +{% endtab %} +{% endtabs %} + +### Aggregating Several Definitions at the Package Level + +Often, your project may have several reusable definitions defined in various modules, that you +wish to aggregate at the top level of a package. + +For example, some helper methods in the trait `FruitHelpers` and +some term/type aliases in trait `FruitAliases`. Here is how you can put all their definitions at the level of the `fruit` +package: + +{% tabs pkg-obj-vs-top-lvl_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=pkg-obj-vs-top-lvl_5 %} + +Package objects are like other objects, which means you can use inheritance for building them. +So here we mix in the helper traits as parents of the package object. ``` -package object fruits extends FruitAliases with FruitHelpers { - // helpers and variables follows here -} +package gardening + +// `fruits` instead inherits its members from its parents. +package object fruits extends FruitAliases with FruitHelpers +``` +{% endtab %} +{% tab 'Scala 3' for=pkg-obj-vs-top-lvl_5 %} + +In Scala 3, it is preferred to use `export` to compose members from several objects into a single scope. +Here we define private objects that mix in the helper traits, then export their members at the top level: + +``` +package gardening.fruits + +private object FruitAliases extends FruitAliases +private object FruitHelpers extends FruitHelpers + +export FruitHelpers.*, FruitAliases.* ``` +{% endtab %} +{% endtabs %} diff --git a/_tour/packages-and-imports.md b/_tour/packages-and-imports.md index f18f8ae5e3..3f07344f32 100644 --- a/_tour/packages-and-imports.md +++ b/_tour/packages-and-imports.md @@ -14,11 +14,16 @@ Scala uses packages to create namespaces which allow you to modularize programs. ## Creating a package Packages are created by declaring one or more package names at the top of a Scala file. +{% tabs packages-and-imports_1 %} +{% tab 'Scala 2 and 3' for=packages-and-imports_1 %} ``` package users class User ``` +{% endtab %} +{% endtabs %} + One convention is to name the package the same as the directory containing the Scala file. However, Scala is agnostic to file layout. The directory structure of an sbt project for `package users` might look like this: ``` - ExampleProject @@ -33,8 +38,11 @@ One convention is to name the package the same as the directory containing the S UserPreferences.scala - test ``` -Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by using braces: -``` +Notice how the `users` directory is within the `scala` directory and how there are multiple Scala files within the package. Each Scala file in the package could have the same package declaration. The other way to declare packages is by nesting them inside each other: + +{% tabs packages-and-imports_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=packages-and-imports_2 %} +```scala package users { package administrators { class NormalUser @@ -44,39 +52,95 @@ package users { } } ``` +{% endtab %} +{% tab 'Scala 3' for=packages-and-imports_2 %} +```scala +package users: + package administrators: + class NormalUser + + package normalusers: + class NormalUser +``` +{% endtab %} +{% endtabs %} + As you can see, this allows for package nesting and provides greater control for scope and encapsulation. The package name should be all lower case and if the code is being developed within an organization which has a website, it should be the following format convention: `
+Note that `Long` to `Float` conversion is deprecated in new versions of Scala, because of the potential precision lost.
+
For example:
+{% tabs unified-types-2 %}
+{% tab 'Scala 2 and 3' for=unified-types-2 %}
```scala mdoc
val x: Long = 987654321
-val y: Float = x // 9.8765434E8 (note that some precision is lost in this case)
+val y: Float = x.toFloat // 9.8765434E8 (note that some precision is lost in this case)
val face: Char = '☺'
val number: Int = face // 9786
```
+{% endtab %}
+{% endtabs %}
+
Casting is unidirectional. This will not compile:
-```
+{% tabs unified-types-3 %}
+{% tab 'Scala 2 and 3' for=unified-types-3 %}
+```scala
val x: Long = 987654321
-val y: Float = x // 9.8765434E8
+val y: Float = x.toFloat // 9.8765434E8
val z: Long = y // Does not conform
```
+{% endtab %}
+{% endtabs %}
+
You can also cast a reference type to a subtype. This will be covered later in the tour.
diff --git a/_tour/upper-type-bounds.md b/_tour/upper-type-bounds.md
index 8c4b5815c7..e49f86dc3f 100644
--- a/_tour/upper-type-bounds.md
+++ b/_tour/upper-type-bounds.md
@@ -13,6 +13,8 @@ redirect_from: "/tutorials/tour/upper-type-bounds.html"
In Scala, [type parameters](generic-classes.html) and [abstract type members](abstract-type-members.html) may be constrained by a type bound. Such type bounds limit the concrete values of the type variables and possibly reveal more information about the members of such types. An _upper type bound_ `T <: A` declares that type variable `T` refers to a subtype of type `A`.
Here is an example that demonstrates upper type bound for a type parameter of class `PetContainer`:
+{% tabs upper-type-bounds class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds %}
```scala mdoc
abstract class Animal {
def name: String
@@ -39,11 +41,47 @@ class PetContainer[P <: Pet](p: P) {
val dogContainer = new PetContainer[Dog](new Dog)
val catContainer = new PetContainer[Cat](new Cat)
```
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds %}
+```scala
+abstract class Animal:
+ def name: String
+abstract class Pet extends Animal
+
+class Cat extends Pet:
+ override def name: String = "Cat"
+
+class Dog extends Pet:
+ override def name: String = "Dog"
+
+class Lion extends Animal:
+ override def name: String = "Lion"
+
+class PetContainer[P <: Pet](p: P):
+ def pet: P = p
+
+val dogContainer = PetContainer[Dog](Dog())
+val catContainer = PetContainer[Cat](Cat())
+```
+{% endtab %}
+{% endtabs %}
+
+{% tabs upper-type-bounds_error class=tabs-scala-version %}
+{% tab 'Scala 2' for=upper-type-bounds_error %}
```scala mdoc:fail
// this would not compile
val lionContainer = new PetContainer[Lion](new Lion)
```
+{% endtab %}
+{% tab 'Scala 3' for=upper-type-bounds_error %}
+```scala
+// this would not compile
+val lionContainer = PetContainer[Lion](Lion())
+```
+{% endtab %}
+{% endtabs %}
+
The `class PetContainer` takes a type parameter `P` which must be a subtype of `Pet`. `Dog` and `Cat` are subtypes of `Pet` so we can create a new `PetContainer[Dog]` and `PetContainer[Cat]`. However, if we tried to create a `PetContainer[Lion]`, we would get the following Error:
`type arguments [Lion] do not conform to class PetContainer's type parameter bounds [P <: Pet]`
diff --git a/_tour/variances.md b/_tour/variances.md
index 69f371e81e..14f40fb893 100644
--- a/_tour/variances.md
+++ b/_tour/variances.md
@@ -10,20 +10,34 @@ previous-page: generic-classes
redirect_from: "/tutorials/tour/variances.html"
---
-Variance is the correlation of subtyping relationships of complex types and the subtyping relationships of their component types. Scala supports variance annotations of type parameters of [generic classes](generic-classes.html), to allow them to be covariant, contravariant, or invariant if no annotations are used. The use of variance in the type system allows us to make intuitive connections between complex types, whereas the lack of variance can restrict the reuse of a class abstraction.
+Variance lets you control how type parameters behave with regard to subtyping. Scala supports variance annotations of type parameters of [generic classes](generic-classes.html), to allow them to be covariant, contravariant, or invariant if no annotations are used. The use of variance in the type system allows us to make intuitive connections between complex types.
+{% tabs variances_1 %}
+{% tab 'Scala 2 and 3' for=variances_1 %}
```scala mdoc
class Foo[+A] // A covariant class
class Bar[-A] // A contravariant class
class Baz[A] // An invariant class
```
+{% endtab %}
+{% endtabs %}
-### Covariance
+### Invariance
-A type parameter `T` of a generic class can be made covariant by using the annotation `+T`. For some `class List[+T]`, making `T` covariant implies that for two types `A` and `B` where `B` is a subtype of `A`, then `List[B]` is a subtype of `List[A]`. This allows us to make very useful and intuitive subtyping relationships using generics.
+By default, type parameters in Scala are invariant: subtyping relationships between the type parameters aren't reflected in the parameterized type. To explore why this works the way it does, we look at a simple parameterized type, the mutable box.
+
+{% tabs invariance_1 %}
+{% tab 'Scala 2 and 3' for=invariance_1 %}
+```scala mdoc
+class Box[A](var content: A)
+```
+{% endtab %}
+{% endtabs %}
-Consider this simple class structure:
+We're going to be putting values of type `Animal` in it. This type is defined as follows:
+{% tabs invariance_2 class=tabs-scala-version %}
+{% tab 'Scala 2' for=invariance_2 %}
```scala mdoc
abstract class Animal {
def name: String
@@ -31,111 +45,178 @@ abstract class Animal {
case class Cat(name: String) extends Animal
case class Dog(name: String) extends Animal
```
+{% endtab %}
+{% tab 'Scala 3' for=invariance_2 %}
+```scala
+abstract class Animal:
+ def name: String
-Both `Cat` and `Dog` are subtypes of `Animal`. The Scala standard library has a generic immutable `sealed abstract class List[+A]` class, where the type parameter `A` is covariant. This means that a `List[Cat]` is a `List[Animal]` and a `List[Dog]` is also a `List[Animal]`. Intuitively, it makes sense that a list of cats and a list of dogs are each lists of animals, and you should be able to use either of them for in place of `List[Animal]`.
+case class Cat(name: String) extends Animal
+case class Dog(name: String) extends Animal
+```
+{% endtab %}
+{% endtabs %}
-In the following example, the method `printAnimalNames` will accept a list of animals as an argument and print their names each on a new line. If `List[A]` were not covariant, the last two method calls would not compile, which would severely limit the usefulness of the `printAnimalNames` method.
+We can say that `Cat` is a subtype of `Animal`, and that `Dog` is also a subtype of `Animal`. That means that the following is well-typed:
+{% tabs invariance_3 %}
+{% tab 'Scala 2 and 3' for=invariance_3 %}
```scala mdoc
-def printAnimalNames(animals: List[Animal]): Unit =
- animals.foreach {
- animal => println(animal.name)
- }
-
-val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom"))
-val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex"))
+val myAnimal: Animal = Cat("Felix")
+```
+{% endtab %}
+{% endtabs %}
-// prints: Whiskers, Tom
-printAnimalNames(cats)
+What about boxes? Is `Box[Cat]` a subtype of `Box[Animal]`, like `Cat` is a subtype of `Animal`? At first sight, it looks like that may be plausible, but if we try to do that, the compiler will tell us we have an error:
-// prints: Fido, Rex
-printAnimalNames(dogs)
+{% tabs invariance_4 class=tabs-scala-version %}
+{% tab 'Scala 2' for=invariance_4 %}
+```scala mdoc:fail
+val myCatBox: Box[Cat] = new Box[Cat](Cat("Felix"))
+val myAnimalBox: Box[Animal] = myCatBox // this doesn't compile
+val myAnimal: Animal = myAnimalBox.content
```
+{% endtab %}
+{% tab 'Scala 3' for=invariance_4 %}
+```scala
+val myCatBox: Box[Cat] = Box[Cat](Cat("Felix"))
+val myAnimalBox: Box[Animal] = myCatBox // this doesn't compile
+val myAnimal: Animal = myAnimalBox.content
+```
+{% endtab %}
+{% endtabs %}
-### Contravariance
+Why could this be a problem? We can get the cat from the box, and it's still an Animal, isn't it? Well, yes. But that's not all we can do. We can also replace the cat in the box with a different animal
-A type parameter `A` of a generic class can be made contravariant by using the annotation `-A`. This creates a subtyping relationship between the class and its type parameter that is similar, but opposite to what we get with covariance. That is, for some `class Writer[-A]`, making `A` contravariant implies that for two types `A` and `B` where `A` is a subtype of `B`, `Writer[B]` is a subtype of `Writer[A]`.
+{% tabs invariance_5 %}
+{% tab 'Scala 2 and 3' for=invariance_5 %}
+```scala
+ myAnimalBox.content = Dog("Fido")
+```
+{% endtab %}
+{% endtabs %}
-Consider the `Cat`, `Dog`, and `Animal` classes defined above for the following example:
+There now is a Dog in the Animal box. That's all fine, you can put Dogs in Animal boxes, because Dogs are Animals. But our Animal Box is a Cat Box! You can't put a Dog in a Cat box. If we could, and then try to get the cat from our Cat Box, it would turn out to be a dog, breaking type soundness.
-```scala mdoc
-abstract class Printer[-A] {
- def print(value: A): Unit
-}
+{% tabs invariance_6 %}
+{% tab 'Scala 2 and 3' for=invariance_6 %}
+```scala
+ val myCat: Cat = myCatBox.content //myCat would be Fido the dog!
```
+{% endtab %}
+{% endtabs %}
-A `Printer[A]` is a simple class that knows how to print out some type `A`. Let's define some subclasses for specific types:
+From this, we have to conclude that `Box[Cat]` and `Box[Animal]` can't have a subtyping relationship, even though `Cat` and `Animal` do.
-```scala mdoc
-class AnimalPrinter extends Printer[Animal] {
- def print(animal: Animal): Unit =
- println("The animal's name is: " + animal.name)
-}
+### Covariance
-class CatPrinter extends Printer[Cat] {
- def print(cat: Cat): Unit =
- println("The cat's name is: " + cat.name)
-}
-```
+The problem we ran in to above, is that because we could put a Dog in an Animal Box, a Cat Box can't be an Animal Box.
-If a `Printer[Cat]` knows how to print any `Cat` to the console, and a `Printer[Animal]` knows how to print any `Animal` to the console, it makes sense that a `Printer[Animal]` would also know how to print any `Cat`. The inverse relationship does not apply, because a `Printer[Cat]` does not know how to print any `Animal` to the console. Therefore, we should be able to use a `Printer[Animal]` in place of `Printer[Cat]`, if we wish, and making `Printer[A]` contravariant allows us to do exactly that.
+But what if we couldn't put a Dog in the box? Then, we could just get our Cat back out without a problem, and it would adhere to the subtyping relationship. It turns out that that's possible to do.
+{% tabs covariance_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=covariance_1 %}
```scala mdoc
-def printMyCat(printer: Printer[Cat], cat: Cat): Unit =
- printer.print(cat)
+class ImmutableBox[+A](val content: A)
+val catbox: ImmutableBox[Cat] = new ImmutableBox[Cat](Cat("Felix"))
+val animalBox: ImmutableBox[Animal] = catbox // now this compiles
+```
+{% endtab %}
+{% tab 'Scala 3' for=covariance_1 %}
+```scala
+class ImmutableBox[+A](val content: A)
+val catbox: ImmutableBox[Cat] = ImmutableBox[Cat](Cat("Felix"))
+val animalBox: ImmutableBox[Animal] = catbox // now this compiles
+```
+{% endtab %}
+{% endtabs %}
-val catPrinter: Printer[Cat] = new CatPrinter
-val animalPrinter: Printer[Animal] = new AnimalPrinter
+We say that `ImmutableBox` is *covariant* in `A`, and this is indicated by the `+` before the `A`.
-printMyCat(catPrinter, Cat("Boots"))
-printMyCat(animalPrinter, Cat("Boots"))
-```
+More formally, that gives us the following relationship: given some `class Cov[+T]`, then if `A` is a subtype of `B`, `Cov[A]` is a subtype of `Cov[B]`. This allows us to make very useful and intuitive subtyping relationships using generics.
-The output of this program will be:
+In the following less contrived example, the method `printAnimalNames` will accept a list of animals as an argument and print their names each on a new line. If `List[A]` were not covariant, the last two method calls would not compile, which would severely limit the usefulness of the `printAnimalNames` method.
+{% tabs covariance_2 %}
+{% tab 'Scala 2 and 3' for=covariance_2 %}
+```scala mdoc
+def printAnimalNames(animals: List[Animal]): Unit =
+ animals.foreach {
+ animal => println(animal.name)
+ }
+
+val cats: List[Cat] = List(Cat("Whiskers"), Cat("Tom"))
+val dogs: List[Dog] = List(Dog("Fido"), Dog("Rex"))
+
+// prints: Whiskers, Tom
+printAnimalNames(cats)
+
+// prints: Fido, Rex
+printAnimalNames(dogs)
```
-The cat's name is: Boots
-The animal's name is: Boots
-```
+{% endtab %}
+{% endtabs %}
-### Invariance
+### Contravariance
-Generic classes in Scala are invariant by default. This means that they are neither covariant nor contravariant. In the context of the following example, `Container` class is invariant. A `Container[Cat]` is _not_ a `Container[Animal]`, nor is the reverse true.
+We've seen we can accomplish covariance by making sure that we can't put something in the covariant type, but only get something out. What if we had the opposite, something you can put something in, but can't take out? This situation arises if we have something like a serializer, that takes values of type A, and converts them to a serialized format.
+{% tabs contravariance_1 class=tabs-scala-version %}
+{% tab 'Scala 2' for=contravariance_1 %}
```scala mdoc
-class Container[A](value: A) {
- private var _value: A = value
- def getValue: A = _value
- def setValue(value: A): Unit = {
- _value = value
- }
+abstract class Serializer[-A] {
+ def serialize(a: A): String
}
+
+val animalSerializer: Serializer[Animal] = new Serializer[Animal] {
+ def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }"""
+}
+val catSerializer: Serializer[Cat] = animalSerializer
+catSerializer.serialize(Cat("Felix"))
```
+{% endtab %}
+{% tab 'Scala 3' for=contravariance_1 %}
+```scala
+abstract class Serializer[-A]:
+ def serialize(a: A): String
-It may seem like a `Container[Cat]` should naturally also be a `Container[Animal]`, but allowing a mutable generic class to be covariant would not be safe. In this example, it is very important that `Container` is invariant. Supposing `Container` was actually covariant, something like this could happen:
+val animalSerializer: Serializer[Animal] = new Serializer[Animal]():
+ def serialize(animal: Animal): String = s"""{ "name": "${animal.name}" }"""
+val catSerializer: Serializer[Cat] = animalSerializer
+catSerializer.serialize(Cat("Felix"))
```
-val catContainer: Container[Cat] = new Container(Cat("Felix"))
-val animalContainer: Container[Animal] = catContainer
-animalContainer.setValue(Dog("Spot"))
-val cat: Cat = catContainer.getValue // Oops, we'd end up with a Dog assigned to a Cat
-```
+{% endtab %}
+{% endtabs %}
-Fortunately, the compiler stops us long before we could get this far.
+We say that `Serializer` is *contravariant* in `A`, and this is indicated by the `-` before the `A`. A more general serializer is a subtype of a more specific serializer.
-### Other Examples
+More formally, that gives us the reverse relationship: given some `class Contra[-T]`, then if `A` is a subtype of `B`, `Contra[B]` is a subtype of `Contra[A]`.
-Another example that can help one understand variance is `trait Function1[-T, +R]` from the Scala standard library. `Function1` represents a function with one parameter, where the first type parameter `T` represents the parameter type, and the second type parameter `R` represents the return type. A `Function1` is contravariant over its parameter type, and covariant over its return type. For this example we'll use the literal notation `A => B` to represent a `Function1[A, B]`.
+### Immutability and Variance
+Immutability constitutes an important part of the design decision behind using variance. For example, Scala's collections systematically distinguish between [mutable and immutable collections](https://docs.scala-lang.org/overviews/collections-2.13/overview.html). The main issue is that a covariant mutable collection can break type safety. This is why `List` is a covariant collection, while `scala.collection.mutable.ListBuffer` is an invariant collection. `List` is a collection in package `scala.collection.immutable`, therefore it is guaranteed to be immutable for everyone. Whereas, `ListBuffer` is mutable, that is, you can change, add, or remove elements of a `ListBuffer`.
-Assume the similar `Cat`, `Dog`, `Animal` inheritance tree used earlier, plus the following:
+To illustrate the problem of covariance and mutability, suppose that `ListBuffer` was covariant, then the following problematic example would compile (in reality it fails to compile):
-```scala mdoc
-abstract class SmallAnimal extends Animal
-case class Mouse(name: String) extends SmallAnimal
+{% tabs immutability_and_variance_2 %}
+{% tab 'Scala 2 and 3' %}
+```scala mdoc:fail
+import scala.collection.mutable.ListBuffer
+
+val bufInt: ListBuffer[Int] = ListBuffer[Int](1,2,3)
+val bufAny: ListBuffer[Any] = bufInt
+bufAny(0) = "Hello"
+val firstElem: Int = bufInt(0)
```
+{% endtab %}
+{% endtabs %}
+
+If the above code was possible then evaluating `firstElem` would fail with `ClassCastException`, because `bufInt(0)` now contains a `String`, not an `Int`.
-Suppose we're working with functions that accept types of animals, and return the types of food they eat. If we would like a `Cat => SmallAnimal` (because cats eat small animals), but are given a `Animal => Mouse` instead, our program will still work. Intuitively an `Animal => Mouse` will still accept a `Cat` as an argument, because a `Cat` is an `Animal`, and it returns a `Mouse`, which is also a `SmallAnimal`. Since we can safely and invisibly substitute the former with the latter, we can say `Animal => Mouse` is a subtype of `Cat => SmallAnimal`.
+The invariance of `ListBuffer` means that `ListBuffer[Int]` is not a subtype of `ListBuffer[Any]`, despite the fact that `Int` is a subtype of `Any`, and so `bufInt` cannot be assigned as the value of `bufAny`.
### Comparison With Other Languages
Variance is supported in different ways by some languages that are similar to Scala. For example, variance annotations in Scala closely resemble those in C#, where the annotations are added when a class abstraction is defined (declaration-site variance). In Java, however, variance annotations are given by clients when a class abstraction is used (use-site variance).
+
+Scala's tendency towards immutable types makes it that covariant and contravariant types are more common than in other languages, since a mutable generic type must be invariant.
diff --git a/_uk/cheatsheets/index.md b/_uk/cheatsheets/index.md
new file mode 100644
index 0000000000..24412df349
--- /dev/null
+++ b/_uk/cheatsheets/index.md
@@ -0,0 +1,624 @@
+---
+layout: cheatsheet
+title: Scala Cheatsheet
+
+partof: cheatsheet
+
+by: Dmytro Kazanzhy
+about: Ця шпаргалка створена завдяки Brendan O'Connor, та призначена для швидкого ознайомлення з синтаксичними конструкціями Scala. Ліцензовано Brendan O'Connor за ліцензією CC-BY-SA 3.0.
+
+language: uk
+---
+
+###### Contributed by {{ page.by }}
+
+{{ page.about }}
+
+| змінні | ++ | |
Вірно |
+ Змінна. | +|
Невірно |
+ Константа (значення). | +|
|
+ Явне вказання типу. | +|
| функції | ++ | |
ВірноНевірно |
+ Визначення функції. Прихована помилка: без = це процедура, що повертає Unit та може ввести в оману. Не підтримується зі Scala 2.13. |
+ |
ВірноНевірно |
+ Визначення функції. Синтаксична помилка: для кожного аргументу має бути вказано тип. |
+ |
|
+ Псевдонім (синонім) типу. | +|
|
+ Виклик-за-значенням. Виклик-за-іменем (аргумент обчислюється кожен раз як до нього звертаються). |
+ |
|
+ Анонімна функція. | +|
|
+ Анонімна функція: підкреслення це позиційний аргумент, тобто місце, куди буде підставлено аргумент функції. | +|
|
+ Анонімна функція: щоб використати аргумент двічі, треба його назвати. Зліва від => задається ім'я змінної, якій буде присвоєно аргумент та яку можна використати справа. |
+ |
|
+ Анонімна функція: блоковий стиль (фігурні дужки означають блок) повертає останній вираз. | +|
|
+ Анонімна функція: конвеєрний стиль. | +|
|
+ Анонімна функція: для передачі кількох блоків потрібні зовнішні дужки. | +|
|
+ Каррування, явний синтакси. | +|
|
+ Каррування, явний синтаксис. | +|
|
+ Каррування, синтаксичний цукор. Але: | +|
|
+ Потрібне кінцеве підкреслення, щоб отримати частково застосовану функцію (лише для версії з синтаксичним цукром). | +|
|
+ Узагальнений тип (параметричний поліморфізм). | +|
|
+ Інфіксний цукор (метод з одним аргументом може бути викликано як оператор). | +|
|
+ Varargs (аргументи змінної довжини). | +|
| пакети | ++ | |
|
+ Імпорт всього вмісту пакету. | +|
|
+ Вибірковий імпорт. | +|
|
+ Імпорт з перейменуванням. | +|
|
+ Імпорт всього з java.util окрім Date. |
+ |
На початку файлу: Пакет в певних межах: Пакет одиночка (singleton): |
+ Оголошення пакету. | +|
| структури даних | ++ | |
|
+ Кортеж (Tuple). Трансформується у виклик Tuple3. |
+ |
|
+ Деструктивна прив'язка: кортеж розпаковується через зіставлення зі зразком (pattern matching). | +|
Невірно |
+ Прихована помилка: кожна змінна прив'язана до всього кортежу. | +|
|
+ Список (імутабельний, тобто такий, що не змінюється). | +|
|
+ Індексація через дужки (slides). | +|
|
+ Додавання елементу до голови списку. | +|
|
+ Синтаксичний цукор для діапазонів. | +|
|
+ Пусті дужки це єдине значення для типу Unit. Еквівалентно до void у C та Java. |
+ |
| управляючі конструкти | ++ | |
|
+ Умовний конструкт. | +|
так само, як і + |
+ Умовний конструкт (синтаксичний цукор). | +|
|
+ Цикл while. | +|
|
+ Цикл do-while. | +|
|
+ Break (slides). | +|
так само, як і + |
+ Цикл for: filter/map. | +|
так само, як і + |
+ Цикл for: деструктивна прив'язка. | +|
так само, як і + |
+ Цикл for: декартів добуток. | +|
|
+ Цикл for: імперативізм. стиль sprintf. |
+ |
|
+ Цикл for: ітерація з включенням верхньої межі. | +|
|
+ Цикл for: ітерація без включення верхньої межі. | +|
| зіставлення із зразком (pattern matching) | ++ | |
ВірноНевірно |
+ Для зіставлення зі зразком необхідно використати case перед аргументами анонімної функції. |
+ |
| Невірно + |
+ v42 буде інтерпретовано як ім'я змінної у зразку, яка буде вірно зіставлена з будь-яким Int значенням, і буде виведено “42”. |
+ |
| Вірно + |
+ `v42` у зворотних галочках буде інтерпретовано як значення наявної змінної v42, і буде виведено “Not 42”. |
+ |
| Вірно + |
+ UppercaseVal буде інтерпретовано так само як наявна змінна, а не нова змінна в патерні. Тому значення, що міститься в UppercaseVal буде порівняно з 24, і буде виведено “Not 42”. |
+ |
| об'єктна орієнтація | ++ | |
|
+ Параметри конструктора - тільки x доступний в тілі класу. |
+ |
|
+ Параметри конструктора - автоматичне створення публічного об'єкта. | +|
|
+ Тіло класу є конструктором. Оголосити відкритий (public) атрибут. Оголосити атрибут, доступний тільки на читання. Оголосити закритий (private) атрибут. Альтернативний конструктор. |
+ |
|
+ Анонімний клас. | +|
|
+ Визначити абстрактний клас (без можливості створення об'єкту). | +|
|
+ Визначити клас, що наслідує інший. | +|
|
+ Наслідування та параметри конструктора (за замовчуванням відбувається передача аргументів). | +|
|
+ Визначити єдиний екземпляр (singleton). | +|
|
+ Риси - трейти (traits). Інтерфейси-з-імплементацією. У трейту немає параметрів конструктора. композиція з домішками (mixin). |
+ |
|
+ Множинні трейти. | +|
|
+ При реалізації вже наявного методу необхідно вказати overrides. |
+ |
|
+ Створення об'єкту. | +|
НевірноВірно |
+ Помилка типу: абстрактний тип. Натомість, існує конвенція у таких випадках використовувати фабричний метод обʼєкту компаньйону, що приховує конкретний тип. |
+ |
|
+ Літерал класу (Class[String] = class java.lang.String). |
+ |
|
+ Перевірка типу під час виконання (runtime). | +|
|
+ Приведення типу під час виконання (runtime). | +|
|
+ Приписування типу під час компіляції (compile time). | ++ |
| опції (options) | ++ | |
|
+ Конструктор для непустого опціонального значення (тип Some[T]). |
+ |
|
+ Одинак (Singleton) пустого опціонального значення (тип None). |
+ |
|
+ Null-safe фабрика опціональних значень. | +|
|
+ Явна типізація опціонального значення. Фабричний метод для створення пустих опціональних значень. |
+ |
|
+ Конвеєрний стиль. | +|
|
+ Синтаксис for-виразу. | +|
|
+ Застосування функції до опціонального значення. | +|
|
+ Так само, як і mapб але функція має повернути опціональне значення. |
+ |
|
+ Вилучення вкладених опціональних значень. | +|
|
+ Застосувати процедуру на опціональному значенні. | +|
|
+ Застосувати функцію на опціональному значенні та повернути значення, якщо воно порожнє. | +|
|
+ Виконати часткове зіставлення зі зразком опціонального значення. | +|
|
+ true якщо не порожнє. |
+ |
|
+ true якщо порожнє. |
+ |
|
+ true якщо не порожнє. |
+ |
|
+ 0 якщо порожнє, інакше 1. |
+ |
|
+ Обчислити та повернути альтернативне опціональне значення, якщо порожнє. | +|
|
+ Обчислити та повернути значення за замовчуванням, якщо порожнє. | +|
|
+ Повернути значення, або згенерувати виключення, якщо порожнє. | +|
|
+ Повернути значення, null якщо порожнє. |
+ |
|
+ Фільтрація опціонального значення. Повернути значення, якщо предикат істинний. | +|
|
+ Фільтрація опціонального значення. Повернути значення, якщо предикат хибний. | +|
|
+ Повернути значення предикату на опціональному значенні або false якщо порожнє. |
+ |
|
+ Повернути значення предикату на опціональному значенні або true якщо порожнє.. |
+ |
|
+ Перевіряє чи дорівнює опціональне значення параметру, false якщо порожнє. |
+
-
- * Scala的容器类
- * [简介](/zh-cn/overviews/collections/introduction.html)
- * [Mutable和Immutable集合](/zh-cn/overviews/collections/overview.html)
- * [Trait Traversable](/zh-cn/overviews/collections/trait-traversable.html)
- * [Trait Iterable](/zh-cn/overviews/collections/trait-iterable.html)
- * [序列trait：Seq、IndexedSeq 及 LinearSeq](/zh-cn/overviews/collections/seqs.html)
- * [集合](/zh-cn/overviews/collections/sets.html)
- * [映射](/zh-cn/overviews/collections/maps.html)
- * [具体的不可变集实体类](/zh-cn/overviews/collections/concrete-immutable-collection-classes.html)
- * [具体的可变容器类](/zh-cn/overviews/collections/concrete-mutable-collection-classes.html)
- * [数组](/zh-cn/overviews/collections/arrays.html)
- * [字符串](/zh-cn/overviews/collections/strings.html)
- * [性能特点](/zh-cn/overviews/collections/performance-characteristics.html)
- * [等价性](/zh-cn/overviews/collections/equality.html)
- * [视图](/zh-cn/overviews/collections/views.html)
- * [Iterators](/zh-cn/overviews/collections/iterators.html)
- * [从头定义新容器](/zh-cn/overviews/collections/creating-collections-from-scratch.html)
- * [Java和Scala容器的转换](/zh-cn/overviews/collections/conversions-between-java-and-scala-collections.html)
- * [Scala 2.7迁移指南](/zh-cn/overviews/collections/migrating-from-scala-27.html)
- * [Scala容器类体系结构](/zh-cn/overviews/core/architecture-of-scala-collections.html)
- * [字符串插值](/zh-cn/overviews/core/string-interpolation.html) New in 2.10
- * [Implicit Classes](/zh-cn/overviews/core/implicit-classes.html) New in 2.10
- * [Value Classes and Universal Traits](/zh-cn/overviews/core/value-classes.html) New in 2.10
-
-核心库
-
-
- * [Future和Promise](/zh-cn/overviews/core/futures.html) New in 2.10
- * Scala的并行容器类
- * [概述](/zh-cn/overviews/parallel-collections/overview.html)
- * [具体并行集合类](/zh-cn/overviews/parallel-collections/concrete-parallel-collections.html)
- * [并行容器的转换](/zh-cn/overviews/parallel-collections/conversions.html)
- * [并发字典树](/zh-cn/overviews/parallel-collections/ctries.html)
- * [并行集合库的架构](/zh-cn/overviews/parallel-collections/architecture.html)
- * [创建自定义并行容器](/zh-cn/overviews/parallel-collections/custom-parallel-collections.html)
- * [配置并行集合](/zh-cn/overviews/parallel-collections/configuration.html)
- * [测量性能](/zh-cn/overviews/parallel-collections/performance.html)
- * [Scala Actors迁移指南](/zh-cn/overviews/core/actors-migration-guide.html) New in 2.10
- * [The Scala Actors API](/zh-cn/overviews/core/actors.html) Deprecated
-
-Parallel and Concurrent Programming
-
-
-* [致谢名单](/zh-cn/overviews/thanks.html)
+
diff --git a/_zh-cn/overviews/reflection/overview.md b/_zh-cn/overviews/reflection/overview.md
index 02adf8ecc2..25f54810e9 100644
--- a/_zh-cn/overviews/reflection/overview.md
+++ b/_zh-cn/overviews/reflection/overview.md
@@ -85,7 +85,7 @@ decls: Iterable[ru.Symbol] = List(constructor List, method companion, method isE
#### 1.1.2 运行时实例化一个类型
-通过反射获得的类型，可以通过使用适当的“调用器”镜像调用它们的构造函数来实例化（镜像`mirros`的概念在[后续文档中说明](https://docs.scala-lang.org/overviews/reflection/overview.html#mirrors)）。
+通过反射获得的类型，可以通过使用适当的“调用器”镜像调用它们的构造函数来实例化（镜像`mirrors`的概念在[后续文档中说明](https://docs.scala-lang.org/overviews/reflection/overview.html#mirrors)）。
让我们通过一个REPL的示例说明：
@@ -269,7 +269,7 @@ Scala反射实现了允许在编译阶段就对程序进行修改的一种元编
这个反射环境根据是在运行时环境完成反射任务还是在编译时环境完成反射任务而有所区别。
这个区别被封装于所谓的`universe`中。
反射环境的另一个重要方面就是我们可以访问想反射的那组实体，
-这组实体由所谓的镜像`mirros`去确定。
+这组实体由所谓的镜像`mirrors`去确定。
镜像不仅决定反射化操作有哪些实体要被访问到，而且它还提供了反射操作去执行那些实体。
比如在运行时反射过程中可以调用镜像去操作类中一个方法或构造器。
@@ -279,7 +279,7 @@ Scala反射实现了允许在编译阶段就对程序进行修改的一种元编
`Universe`是Scala反射的切入点。
`universe`提供了使用反射所关联的很多核心概念，比如`Types`，`Trees`，以及`Annotations`。
-更多细节请参阅指南中[Universes](https://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html)部分，或者看`scala.reflect.api`包的[Universes API文档](https://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Universe.html)。
+更多细节请参阅指南中[Universes](https://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html)部分，或者看`scala.reflect.api`包的[Universes API文档](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Universe.html)。
本指南中提供了大多数情况下Scala反射要用到的部分，一般在使用运行时反射的场景下，直接导入所有`universe`成员去用即可：
@@ -293,4 +293,4 @@ import scala.reflect.runtime.universe._
反射所能提供的信息都是通过镜像去访问的。
根据不同的类型信息或不同的反射操作，必须要使用不同类型的镜像。
-更多细节请参阅指南中[Mirros](https://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html)部分，或者看`scala.reflect.api`包的[Mirrors API文档](https://www.scala-lang.org/api/current/scala-reflect/scala/reflect/api/Mirrors.html)。
+更多细节请参阅指南中[Mirrors](https://docs.scala-lang.org/overviews/reflection/environment-universes-mirrors.html)部分，或者看`scala.reflect.api`包的[Mirrors API文档](https://www.scala-lang.org/api/2.x/scala-reflect/scala/reflect/api/Mirrors.html)。
diff --git a/_zh-cn/overviews/scala3-book/ca-context-bounds.md b/_zh-cn/overviews/scala3-book/ca-context-bounds.md
new file mode 100644
index 0000000000..9e9c84238c
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/ca-context-bounds.md
@@ -0,0 +1,114 @@
+---
+title: 上下文绑定
+type: section
+description: This page demonstrates Context Bounds in Scala 3.
+language: zh-cn
+num: 62
+previous-page: ca-context-parameters
+next-page: ca-given-imports
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+在许多情况下，[上下文参数]({% link _overviews/scala3-book/ca-context-parameters.md %}#context-parameters) 的名称不必显式提及，因为它仅在编译器为其他上下文参数合成实参的时候用到。
+在这种情况下，您不必定义参数名称，只需提供参数类型即可。
+
+## 背景
+
+例如，假设一个 `maxElement` 方法返回一个集合里的最大值：
+
+{% tabs context-bounds-max-named-param class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def maxElement[A](as: List[A])(implicit ord: Ord[A]): A =
+ as.reduceLeft(max(_, _)(ord))
+```
+{% endtab %}
+{% tab 'Scala 3' %}
+```scala
+def maxElement[A](as: List[A])(using ord: Ord[A]): A =
+ as.reduceLeft(max(_, _)(using ord))
+```
+{% endtab %}
+{% endtabs %}
+
+上面这个 `maxElement` 方法只接受一个类型为 `Ord[A]` 的 _上下文参数_ 并将其作为实参传给 `max` 方法。
+
+完整起见，以下是 `max` 和 `Ord` 的定义（注意，在实践中我们会使用 `List` 中已有的 `max` 方法 ，
+但我们为了说明目的而编造了这个例子）：
+
+{% tabs context-bounds-max-ord class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+/** Defines how to compare values of type `A` */
+trait Ord[A] {
+ def greaterThan(a1: A, a2: A): Boolean
+}
+
+/** Returns the maximum of two values */
+def max[A](a1: A, a2: A)(implicit ord: Ord[A]): A =
+ if (ord.greaterThan(a1, a2)) a1 else a2
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+/** Defines how to compare values of type `A` */
+trait Ord[A]:
+ def greaterThan(a1: A, a2: A): Boolean
+
+/** Returns the maximum of two values */
+def max[A](a1: A, a2: A)(using ord: Ord[A]): A =
+ if ord.greaterThan(a1, a2) then a1 else a2
+```
+{% endtab %}
+{% endtabs %}
+
+`max` 方法用了类型为 `Ord[A]` 的上下文参数, 就像 `maxElement` 方法一样。
+
+## 省略上下文参数
+
+因为 `ord` 是 `max` 方法的上下文参数，当我们调用方法 `max` 时， 编译器可以在 `maxElement` 的实现中为我们提供它：
+
+{% tabs context-bounds-context class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def maxElement[A](as: List[A])(implicit ord: Ord[A]): A =
+ as.reduceLeft(max(_, _))
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def maxElement[A](as: List[A])(using Ord[A]): A =
+ as.reduceLeft(max(_, _))
+```
+
+注意，因为我们不用显示传递给 `max` 方法，我们可以在 `maxElement` 定义里不命名。
+这是 _匿名上下文参数_ 。
+{% endtab %}
+{% endtabs %}
+
+## 上下文绑定
+
+鉴于此背景，_上下文绑定_ 是一种简写语法，用于表达“依赖于类型参数的上下文参数”模式。
+
+使用上下文绑定，`maxElement` 方法可以这样写：
+
+{% tabs context-bounds-max-rewritten %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def maxElement[A: Ord](as: List[A]): A =
+ as.reduceLeft(max(_, _))
+```
+{% endtab %}
+{% endtabs %}
+
+方法或类的类型参数 `A`，有类似 `:Ord` 的绑定，它表示有 `Ord[A]` 的上下文参数。
+在后台，编译器将此语法转换为“背景”部分中显示的语法。
+
+有关上下文绑定的更多信息，请参阅 Scala 常见问题解答的 [“什么是上下文绑定？”](https://docs.scala-lang.org/tutorials/FAQ/context-bounds.html) 部分。
diff --git a/_zh-cn/overviews/scala3-book/ca-context-parameters.md b/_zh-cn/overviews/scala3-book/ca-context-parameters.md
new file mode 100644
index 0000000000..3742d36de1
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/ca-context-parameters.md
@@ -0,0 +1,152 @@
+---
+title: Given 实例和 Using 语句
+type: section
+description: This page demonstrates how to use 'given' instances and 'using' clauses in Scala 3.
+language: zh-cn
+num: 61
+previous-page: ca-extension-methods
+next-page: ca-context-bounds
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Acknowledgements
-使用上下文抽象仅限Scala 3
+ +Scala 3 提供了两个重要的上下文抽象特性： + +- **Using 语句** 允许你指定参数，这些参数程序员可以在调用时省略，这些参数由上下文自动提供。 +- **Given 实例** 让您定义 Scala 编译器可以用来填充缺失参数的术语。 + +## Using 语句 + +在设计系统时，通常需要向系统的不同组件提供上下文信息，如_配置_或设置。 +实现此目的的一种常见方法是将配置作为附加参数传递给您的方法。 + +在下面的示例中，我们定义了一个样例类 `Config` 来模拟一些网站配置并在不同的方法中传递它。 + +{% tabs nonusing %} +{% tab 'Scala 2 and 3' %} + +```scala +case class Config(port: Int, baseUrl: String) + +def renderWebsite(path: String, c: Config): String = + "" + renderWidget(List("cart"), c) + "" + +def renderWidget(items: List[String], c: Config): String = ??? + +val config = Config(8080, "docs.scala-lang.org") +renderWebsite("/home", config) +``` + +{% endtab %} +{% endtabs %} + +让我们假设配置在我们的大部分代码库中都没有改变。 +将 `c` 传递给每个方法调用（如 `renderWidget`）变得非常乏味并且使我们的程序更难阅读，因为我们需要忽略 `c` 参数。 + +#### 使用 `using` 将参数标记为上下文 + +在 Scala 3 中，我们可以将方法的一些参数标记为_上下文_。 + +{% tabs using1 %} +{% tab 'Scala 3 Only' %} + +```scala +def renderWebsite(path: String)(using c: Config): String = + "" + renderWidget(List("cart")) + "" + // ^^^ + // no argument c required anymore + +def renderWidget(items: List[String])(using c: Config): String = ??? +``` + +{% endtab %} +{% endtabs %} + +通过使用关键字 `using` 开始参数部分，我们告诉 Scala 编译器它应该在调用处自动找到具有正确类型的参数。 +因此，Scala 编译器执行**术语推断**。 + +在我们对 `renderWidget(List("cart"))` 的调用中，Scala 编译器将看到作用域（`c`）中有一个类型为 `Config` 的术语，并自动将其提供给 `renderWidget`。 +所以程序等同于上面的程序。 + +事实上，由于我们不再需要在 `renderWebsite` 的实现中引用 `c`，我们甚至可以在签名中省略它的名字： + +{% tabs using2 %} +{% tab 'Scala 3 Only' %} + +```scala +// no need to come up with a parameter name +// vvvvvvvvvvvvv +def renderWebsite(path: String)(using Config): String = + "" + renderWidget(List("cart")) + "" +``` + +{% endtab %} +{% endtabs %} + +#### 明确提供上下文参数 + +我们已经了解了如何_抽象_上下文参数，并且 Scala 编译器可以自动为我们提供参数。 +但是我们如何指定调用 `renderWebsite` 时使用的配置呢？ + +就像我们使用 `using` 指定参数部分一样，我们也可以使用 `using` 显式提供上下文参数： + +{% tabs using3 %} +{% tab 'Scala 3 Only' %} + +```scala +renderWebsite("/home")(using config) +``` + +{% endtab %} +{% endtabs %} + +如果我们在范围内有多个有意义的不同值，并且我们希望确保将正确的值传递给函数，则显式提供上下文参数可能很有用。 + +对于所有其他情况，正如我们将在下一节中看到的，还有另一种方法可以将上下文值引入范围。 + +## Give 实例 + +我们已经看到，我们可以通过使用 `using` 标记 _调用_的参数部分来显式地将参数作为上下文参数传递。 +但是，如果某个特定类型有一个_单一的规范值_，则还有另一种首选方法可以使其对 Scala 编译器可用：将其标记为 `given`。 + +{% tabs given1 %} +{% tab 'Scala 3 Only' %} + +```scala +val config = Config(8080, "docs.scala-lang.org") +// this is the type that we want to provide the +// canonical value for +// vvvvvv +given Config = config +// ^^^^^^ +// this is the value the Scala compiler will infer +// as argument to contextual parameters of type Config +``` + +{% endtab %} +{% endtabs %} + +在上面的示例中，我们指定每当在当前范围内省略 `Config` 类型的上下文参数时，编译器应该将 `config` 推断为参数。 + +为 `Config` 定义了 given，我们可以简单地调用 `renderWebsite`： + +{% tabs given2 %} +{% tab 'Scala 3 Only' %} + +```scala +renderWebsite("/home") +// ^^^^^ +// again no argument +``` + +{% endtab %} +{% endtabs %} + +[reference]: {{ site.scala3ref }}/overview.html +[blog-post]: /2020/11/06/explicit-term-inference-in-scala-3.html diff --git a/_zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md b/_zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md new file mode 100644 index 0000000000..4b6a82db3b --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md @@ -0,0 +1,88 @@ +--- +title: 上下文抽象 +type: chapter +description: This chapter provides an introduction to the Scala 3 concept of Contextual Abstractions. +language: zh-cn +num: 59 +previous-page: types-others +next-page: ca-extension-methods + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +## 背景 + +隐式是Scala 2中的一个主要的设计特色。隐式是进行上下文抽象的基本方式。它们代表了具有多种用例的统一范式，其中包括： + +- 实现类型类 +- 建立上下文 +- 依赖注入 +- 表达能力 +- 计算新类型，并证明它们之间的关系 + +此后，其他语言也纷纷效仿，例如 Rust 的 traits 或 Swift 的协议扩展。对于编译期的依赖解析方案，Kotlin 的设计方案也被提上日程，而对 C# 而言是 Shapes 和 Extensions 或对 F# 来说是 Traits。Implicits 也是 Coq 或 Agda 等定理证明器的共同特色。 + +尽管这些设计使用不同的术语，但它们都是*术语推理*核心思想的变体： +给定一个类型，编译器会合成一个具有该类型的“canonical”术语。 + +## 重新设计 + +Scala 3 重新设计了 Scala 中的上下文抽象。 +虽然这些概念是在 Scala 2 中逐渐“发现”的，但它们现在已广为人知和理解，并且重新设计利用了这些知识。 + +Scala 3 的设计侧重于 **意图** 而不是 **机制**。 +Scala 3 没有提供一个非常强大的隐式特性，而是提供了几个面向用例的特性： + +- **抽象上下文信息**。 + [使用子句][givens] 允许程序员对调用上下文中可用的信息进行抽象，并且应该隐式传递。 + 作为对 Scala 2 隐式的改进，可以按类型指定 using 子句，从而将函数签名从从未显式引用的术语变量名称中释放出来。 + +- **提供类型类实例**。 + [给定实例][type-classes]允许程序员定义某种类型的_规范值(canonical value)_。 + 这使得使用类型类的编程更加简单，而不会泄露实现细节。 + +- **追溯扩展类**。 + 在 Scala 2 中，扩展方法必须使用隐式转换或隐式类进行编码。 + 相比之下，在 Scala 3 [扩展方法][extension-methods] 现在直接内置到语言中，产生了更好的错误消息和改进的类型推断。 + +- **将一种类型视为另一种类型**。 + 隐式转换已从头开始[重新设计][implicit-conversions]，作为类型类 `Conversion` 的实例。 + +- **高阶上下文抽象**。 + [上下文函数][contextual-functions] 的_全新_特性使上下文抽象成为一等公民。 + 它们是库作者的重要工具，可以表达简洁的领域特定语言。 + +- **来自编译器的可操作反馈**。 + 如果编译器无法解析隐式参数，它现在会为您提供 [导入建议](https://www.scala-lang.org/blog/2020/05/05/scala-3-import-suggestions.html) 来解决问题。 + +## 好处 + +Scala 3 中的这些更改实现了术语推理与语言其余部分的更好分离： + +- 仅有一种定义 given 的方法 +- 仅有一种方法可以引入隐式参数和自变量 +- [导入 givens][given-imports] 仅有一种单独的方法，不允许它们隐藏在正常导入的海洋中 +- 定义 [隐式转换][implicit-conversions] 的方法仅有一种，它被清楚地标记为这样，并且不需要特殊的语法 + +这些变化的好处包括： + +- 新设计避免了特性交织，从而使语言更加一致 +- 它使隐式更容易学习和更难滥用 +- 它极大地提高了 95% 使用隐式的 Scala 程序的清晰度 +- 它有可能以一种易于理解和友好的原则方式进行术语推理 + +本章将在以下各节中介绍其中的许多新功能。 + + +[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %} +[given-imports]: {% link _zh-cn/overviews/scala3-book/ca-given-imports.md %} +[implicit-conversions]: {% link _zh-cn/overviews/scala3-book/ca-implicit-conversions.md %} +[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %} +[context-bounds]: {% link _zh-cn/overviews/scala3-book/ca-context-bounds.md %} +[type-classes]: {% link _zh-cn/overviews/scala3-book/ca-type-classes.md %} +[equality]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} +[contextual-functions]: {% link _zh-cn/overviews/scala3-book/types-dependent-function.md %} diff --git a/_zh-cn/overviews/scala3-book/ca-extension-methods.md b/_zh-cn/overviews/scala3-book/ca-extension-methods.md new file mode 100644 index 0000000000..be1237733b --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-extension-methods.md @@ -0,0 +1,127 @@ +--- +title: 扩展方法 +type: section +description: This page demonstrates how Extension Methods work in Scala 3. +language: zh-cn +num: 60 +previous-page: ca-contextual-abstractions-intro +next-page: ca-context-parameters + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +在 Scala 2 中，用 [implicit classes]({% link _overviews/core/implicit-classes.md %}) 可以得到类似的结果。 + +--- + +扩展方法允许您在定义类型后向类型添加方法，即它们允许您向封闭类添加新方法。 +例如，假设其他人创建了一个 `Circle` 类： + +{% tabs ext1 %} +{% tab 'Scala 2 and 3' %} +```scala +case class Circle(x: Double, y: Double, radius: Double) +``` +{% endtab %} +{% endtabs %} + +现在想象一下，你需要一个 `circumference` 方法，但是你不能修改它们的源代码。 +在将术语推理的概念引入编程语言之前，您唯一能做的就是在单独的类或对象中编写一个方法，如下所示： + +{% tabs ext2 class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +object CircleHelpers { + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +object CircleHelpers: + def circumference(c: Circle): Double = c.radius * math.Pi * 2 +``` +{% endtab %} +{% endtabs %} + +你可以像这样用该方法： + +{% tabs ext3 %} +{% tab 'Scala 2 and 3' %} +```scala +val aCircle = Circle(2, 3, 5) + +// without extension methods +CircleHelpers.circumference(aCircle) +``` +{% endtab %} +{% endtabs %} + +但是使用扩展方法，您可以创建一个 `circumference` 方法来处理 `Circle` 实例： + +{% tabs ext4 %} +{% tab 'Scala 3 Only' %} +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 +``` +{% endtab %} +{% endtabs %} + +在这段代码中： + +- 扩展方法 `circumference` 将添加到 `Circle` 类型里 +- `c: Circle` 语法允许您在扩展方法中引用变量 `c` + +然后在您的代码中使用 `circumference`，就像它最初是在 `Circle` 类中定义的一样： + +{% tabs ext5 %} +{% tab 'Scala 3 Only' %} +```scala +aCircle.circumference +``` +{% endtab %} +{% endtabs %} + +### 导入扩展方法 + +想象一下，`circumference` 定义在`lib` 包中，你可以通过以下方式导入它 + +{% tabs ext6 %} +{% tab 'Scala 3 Only' %} +```scala +import lib.circumference + +aCircle.circumference +``` +{% endtab %} +{% endtabs %} + +如果缺少导入，编译器还会通过显示详细的编译错误消息来支持您，如下所示： + +```text +value circumference is not a member of Circle, but could be made available as an extension method. + +The following import might fix the problem: + + import lib.circumference +``` + +## 讨论 + +`extension` 关键字声明您将要在括号中的类型上定义一个或多个扩展方法。 +要在一个类型上定义多个扩展方法，请使用以下语法： + +{% tabs ext7 %} +{% tab 'Scala 3 Only' %} +```scala +extension (c: Circle) + def circumference: Double = c.radius * math.Pi * 2 + def diameter: Double = c.radius * 2 + def area: Double = math.Pi * c.radius * c.radius +``` +{% endtab %} +{% endtabs %} diff --git a/_zh-cn/overviews/scala3-book/ca-given-imports.md b/_zh-cn/overviews/scala3-book/ca-given-imports.md new file mode 100644 index 0000000000..ba56af52f0 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-given-imports.md @@ -0,0 +1,54 @@ +--- +title: Given 导入 +type: section +description: This page demonstrates how 'given' import statements work in Scala 3. +language: zh-cn +num: 63 +previous-page: ca-context-bounds +next-page: ca-type-classes + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +为了更清楚地说明当前作用域中的 given 来自何处，我们使用一种特殊形式的 `import` 语句来导入 `given` 实例。 +此示例中显示了基本形式： + +```scala +object A: + class TC + given tc: TC = ??? + def f(using TC) = ??? + +object B: + import A.* // import all non-given members + import A.given // import the given instance +``` + +在此代码中，对象 `B` 的 `import A.*` 子句导入 `A` 的所有成员*除了* `given` 实例 `tc`。 +相反，第二个导入 `import A.given` *仅*导入 `given` 实例。 +两个 `import` 子句也可以合并为一个： + +```scala +object B: + import A.{given, *} +``` + +## 讨论 + +通配符选择器 `*` 将除 given 或扩展之外的所有定义都导入作用域，而 `given` 选择器将所有 *given* 定义---包括由扩展而来的定义---导入作用域。 + +这些规则有两个主要优点： + +- 更清楚当前作用域内 given 的来源。 + 特别是，在一长串其他通配符导入中无法隐藏导入的 given 。 +- 它可以导入所有 given ，而无需导入任何其他内容。 + 这很重要，因为 given 是可以匿名的，因此通常使用命名导入是不切实际的。 + +“导入 given”语法的更多示例见 [package 和 import 章节][imports]。 + + +[imports]: {% link _zh-cn/overviews/scala3-book/packaging-imports.md %} diff --git a/_zh-cn/overviews/scala3-book/ca-implicit-conversions.md b/_zh-cn/overviews/scala3-book/ca-implicit-conversions.md new file mode 100644 index 0000000000..5ab40c8064 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-implicit-conversions.md @@ -0,0 +1,53 @@ +--- +title: 隐式转换 +type: section +description: This page demonstrates how to implement Implicit Conversions in Scala 3. +language: zh-cn +num: 66 +previous-page: ca-multiversal-equality +next-page: ca-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +隐式转换由 `scala.Conversion` 类的 `given` 实例定义。 +例如，不考虑可能的转换错误，这段代码定义了从 `String` 到 `Int` 的隐式转换： + +```scala +given Conversion[String, Int] with + def apply(s: String): Int = Integer.parseInt(s) +``` + +使用别名可以更简洁地表示为： + +```scala +given Conversion[String, Int] = Integer.parseInt(_) +``` + +使用这些转换中的任何一种，您现在可以在需要 `Int` 的地方使用 `String`： + +```scala +import scala.language.implicitConversions + +// a method that expects an Int +def plus1(i: Int) = i + 1 + +// pass it a String that converts to an Int +plus1("1") +``` + +> 注意开头的子句 `import scala.language.implicitConversions`， +> 在文件中启用隐式转换。 + +## 讨论 + +Predef 包包含“自动装箱”转换，将基本数字类型映射到 `java.lang.Number` 的子类。 +例如，从 `Int` 到 `java.lang.Integer` 的转换可以定义如下： + +```scala +given int2Integer: Conversion[Int, java.lang.Integer] = + java.lang.Integer.valueOf(_) +``` diff --git a/_zh-cn/overviews/scala3-book/ca-multiversal-equality.md b/_zh-cn/overviews/scala3-book/ca-multiversal-equality.md new file mode 100644 index 0000000000..9c6d2f422c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-multiversal-equality.md @@ -0,0 +1,204 @@ +--- +title: 多元相等性 +type: section +description: This page demonstrates how to implement Multiversal Equality in Scala 3. +language: zh-cn +num: 65 +previous-page: ca-type-classes +next-page: ca-implicit-conversions + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +以前，Scala 具有*通用相等性*：任何类型的两个值都可以使用 `==` 和 `!=` 相互比较。 +这是因为 `==` 和 `!=` 是根据 Java 的 `equals` 方法实现的，该方法还可以比较任何两种引用类型的值。 + +通用相等性很方便，但也很危险，因为它破坏了类型安全。 +例如，假设在一些重构之后，你会得到一个错误的程序，其中值 `y` 的类型为 `S` 而不是正确的类型 `T`： + +```scala +val x = ... // of type T +val y = ... // of type S, but should be T +x == y // typechecks, will always yield false + +``` + +如果 `y` 与其他类型为 `T` 的值进行比较，程序仍然会进行类型检查，因为所有类型的值都可以相互比较。 +但它可能会产生意想不到的结果并在运行时失败。 + +类型安全的编程语言可以做得更好，多元等价是使普遍平等更安全的一种选择方式。 +它使用二元类型类“CanEqual”来指示两个给定类型的值可以相互比较。 + +## 允许比较类实例 + +默认情况下，在 Scala 3 中，您仍然可以像这样创建相等比较： + +```scala +case class Cat(name: String) +case class Dog(name: String) +val d = Dog("Fido") +val c = Cat("Morris") + +d == c // false, but it compiles +``` + +但是使用 Scala 3，您可以禁用此类比较。 +通过 (a) 导入 `scala.language.strictEquality` 或 (b) 使用 `-language:strictEquality` 编译器标志，此比较不再编译： + +```scala +import scala.language.strictEquality + +val rover = Dog("Rover") +val fido = Dog("Fido") +println(rover == fido) // compiler error + +// compiler error message: +// Values of types Dog and Dog cannot be compared with == or != +``` + +## 启用比较 + +有两种方法可以使用 Scala 3 `CanEqual` 类型类来启用这种比较。 +对于像这样的简单情况，您的类可以*派生* `CanEqual` 类： + +```scala +// Option 1 +case class Dog(name: String) derives CanEqual +``` + +稍后您将看到，当您需要更多的灵活性时，您还可以使用以下语法： + +```scala +// Option 2 +case class Dog(name: String) +given CanEqual[Dog, Dog] = CanEqual.derived +``` + +现在，这两种方法中的任何一种都可以让 `Dog` 实例相互比较。 + +## 一个更真实的例子 + +在一个更真实的示例中，假设您有一家在线书店，并且想要允许或禁止比较实体书、打印的书和有声读物。 +在 Scala 3 中，您首先启用多元平等性，如前面的示例所示： + +```scala +// [1] add this import, or this command line flag: -language:strictEquality +import scala.language.strictEquality +``` + +然后像往常一样创建你的领域对象： + +```scala +// [2] create your class hierarchy +trait Book: + def author: String + def title: String + def year: Int + +case class PrintedBook( + author: String, + title: String, + year: Int, + pages: Int +) extends Book + +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book +``` + +最后，使用 `CanEqual` 定义您想要允许的比较： + +```scala +// [3] create type class instances to define the allowed comparisons. +// allow `PrintedBook == PrintedBook` +// allow `AudioBook == AudioBook` +given CanEqual[PrintedBook, PrintedBook] = CanEqual.derived +given CanEqual[AudioBook, AudioBook] = CanEqual.derived + +// [4a] comparing two printed books works as desired +val p1 = PrintedBook("1984", "George Orwell", 1961, 328) +val p2 = PrintedBook("1984", "George Orwell", 1961, 328) +println(p1 == p2) // true + +// [4b] you can’t compare a printed book and an audiobook +val pBook = PrintedBook("1984", "George Orwell", 1961, 328) +val aBook = AudioBook("1984", "George Orwell", 2006, 682) +println(pBook == aBook) // compiler error +``` + +最后一行代码导致此编译器错误消息： + +```` +Values of types PrintedBook and AudioBook cannot be compared with == or != +```` + +这就是多元相等性在编译时捕获非法类型比较的方式。 + +### 启用“PrintedBook == AudioBook” + +这可以按需要工作，但在某些情况下，您可能希望允许将实体书与有声读物进行比较。 +如果需要，请创建以下两个额外的相等比较： + +```scala +// allow `PrintedBook == AudioBook`, and `AudioBook == PrintedBook` +given CanEqual[PrintedBook, AudioBook] = CanEqual.derived +given CanEqual[AudioBook, PrintedBook] = CanEqual.derived +``` + +现在，您可以将实体书与有声书进行比较，而不会出现编译错误： + +```scala +println(pBook == aBook) // false +println(aBook == pBook) // false +``` + +#### 实现 “equals” 以使它们真正起作用 + +虽然现在允许进行这些比较，但它们将始终为 `false`，因为它们的 `equals` 方法不知道如何进行这些比较。 +因此，解决方案是覆盖每个类的 `equals` 方法。 +例如，当您覆盖 `AudioBook` 的 `equals` 方法时： + +```scala +case class AudioBook( + author: String, + title: String, + year: Int, + lengthInMinutes: Int +) extends Book: + // override to allow AudioBook to be compared to PrintedBook + override def equals(that: Any): Boolean = that match + case a: AudioBook => + if this.author == a.author + && this.title == a.title + && this.year == a.year + && this.lengthInMinutes == a.lengthInMinutes + then true else false + case p: PrintedBook => + if this.author == p.author && this.title == p.title + then true else false + case _ => + false +``` + +您现在可以将 `AudioBook` 与 `PrintedBook` 进行比较： + +```scala +println(aBook == pBook) // true (works because of `equals` in `AudioBook`) +println(pBook == aBook) // false +``` + +目前 `PrintedBook` 书没有 `equals` 方法，所以第二个比较返回 `false`。 +要启用该比较，只需覆盖 `PrintedBook` 中的 `equals` 方法。 + +您可以在参考文档中找到有关[多元相等性][ref-equal] 的更多信息。 + + +[ref-equal]: {{ site.scala3ref }}/contextual/multiversal-equality.html diff --git a/_zh-cn/overviews/scala3-book/ca-summary.md b/_zh-cn/overviews/scala3-book/ca-summary.md new file mode 100644 index 0000000000..60b1fd01a5 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-summary.md @@ -0,0 +1,37 @@ +--- +title: 总结 +type: section +description: This page provides a summary of the Contextual Abstractions lessons. +language: zh-cn +num: 67 +previous-page: ca-implicit-conversions +next-page: concurrency + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍了大多数上下文抽象主题，包括： + +- 给定实例和使用子句 +- 上下文绑定 +- 给定导入 +- 扩展方法 +- 实现类型类 +- 多元相等性 +- 隐式转换 + +这里没有涉及一些更高级的主题，包括： + +- 类型类派生 +- 上下文函数 +- 传名上下文参数 +- 与 Scala 2 隐式转换 的关系 + +这些主题在 [参考文档][ref] 中有详细讨论。 + + +[ref]: {{ site.scala3ref }}/contextual diff --git a/_zh-cn/overviews/scala3-book/ca-type-classes.md b/_zh-cn/overviews/scala3-book/ca-type-classes.md new file mode 100644 index 0000000000..7adffa0594 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/ca-type-classes.md @@ -0,0 +1,193 @@ +--- +title: 实现类型类 +type: section +description: This page demonstrates how to create and use type classes in Scala 3. +language: zh-cn +num: 64 +previous-page: ca-given-imports +next-page: ca-multiversal-equality + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +_类型类_ 是一种抽象的参数化类型，它允许您在不使用子类型的情况下向任何封闭数据类型添加新行为。 +如果你从 Java 那边过来，你可以将类型类视为类似于 [`java.util.Comparator[T]`][comparator] 的东西。 + +> Oliveira 等人写的论文 [“Type Classes as Objects and Implicits”][typeclasses-paper] (2010) 讨论了在 Scala 中类型类背后的基本观点。 +> 虽然论文用了旧的 Scala 版本，但其中的观点至今依然有用。 + +这在多用例中很有用，例如： + +- 表达你不拥有的类型——来自标准库或第三方库——如何符合这种行为 +- 为多种类型表达这种行为，而不涉及这些类型之间的子类型关系 + +类型类只是具有一个或多个参数的 traits，其实现在 Scala 3 中，由 `given` 实例提供，在 Scala 2 中用 `implicit` 值。 + +## 例子 + +例如，`Show` 是 Haskell 中众所周知的类型类，下面的代码显示了在 Scala 中实现它的一种方法。 +如果您认为 Scala 类没有 `toString` 方法，您可以定义一个 `Show` 类型类，然后把此行为添加到任意的类，这个类是能够转换为自定义字符串。 + +### 类型类 + +创建类型类的第一步是声明具有一个或多个抽象方法的参数化 trait。 +因为 `Showable` 只有一个名为 `show` 的方法，所以写成这样： + +{% tabs 'definition' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +// a type class +trait Showable[A] { + def show(a: A): String +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +// a type class +trait Showable[A]: + extension(a: A) def show: String +``` +{% endtab %} +{% endtabs %} + +请注意，通常当你要定义 `Show` trait时，下面这样的办法接近普通的面向对象的办法： + +{% tabs 'trait' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +// a trait +trait Show { + def show: String +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +// a trait +trait Show: + def show: String +``` +{% endtab %} +{% endtabs %} + +有几件重要的事情需要指出： + +1. 像 `Showable` 这样的类型类有一个类型参数 `A` 来说明我们为哪种类型提供了 `show` 的实现；相反，像 `Show` 这样的传统的 trait 不会。 +2. 要将 show 功能添加到特定类型 `A`，传统的 trait 需要 `A extends Show`，而对于类型类，我们需要实现 `Showable[A]`。 +3. 在 Scala 3 中，为了在两个 `Showable` 中允许相同的方法调用语法来模仿 `Show`，我们将 `Showable.show` 定义为扩展方法。 + +### 实现具体实例 + +下一步是确定在应用程序中，`Showable` 适用于哪些类，然后为它们实现该行为。 +例如，为这个 `Person` 类实现 `Showable`： + +{% tabs 'person' %} +{% tab 'Scala 2 and 3' %} +```scala +case class Person(firstName: String, lastName: String) +``` +{% endtab %} +{% endtabs %} + +你将为 `Showable[Person]` 定义一个 _规范值_ ，例如下面的代码为 `Person` 类提供了一个 `Showable` 的实例： + +{% tabs 'instance' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +implicit val showablePerson: Showable[Person] = new Showable[Person] { + def show(p: Person): String = + s"${p.firstName} ${p.lastName}" +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +given Showable[Person] with + extension(p: Person) def show: String = + s"${p.firstName} ${p.lastName}" +``` +{% endtab %} +{% endtabs %} + +### 使用类型类 + +现在你可以像这样使用这个类型类： + +{% tabs 'usage' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val person = Person("John", "Doe") +println(showablePerson.show(person)) +``` + +注意，在实践中，类型类一般与类型未知的值一起使用，而不像下面章节展示的 `Person` 类。 +{% endtab %} +{% tab 'Scala 3' %} +```scala +val person = Person("John", "Doe") +println(person.show) +``` +{% endtab %} +{% endtabs %} + +同样，如果 Scala 没有可用于每个类的 `toString` 方法，您可以使用此技术将 `Showable` 行为添加到您希望能够转换为 `String` 的任何类。 + +### 编写使用类型类的方法 + +与继承一样，您可以定义使用 `Showable` 作为类型参数的方法： + +{% tabs 'method' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +def showAll[A](as: List[A])(implicit showable: Showable[A]): Unit = + as.foreach(a => println(showable.show(a))) + +showAll(List(Person("Jane"), Person("Mary"))) +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +def showAll[A: Showable](as: List[A]): Unit = + as.foreach(x => println(a.show)) + +showAll(List(Person("Jane"), Person("Mary"))) +``` +{% endtab %} +{% endtabs %} + +### 具有多种方法的类型类 + +请注意，如果要创建具有多个方法的类型类，则初始语法如下所示： + +{% tabs 'multiple-methods' class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +trait HasLegs[A] { + def walk(a: A): Unit + def run(a: A): Unit +} +``` +{% endtab %} +{% tab 'Scala 3' %} +```scala +trait HasLegs[A]: + extension (a: A) + def walk(): Unit + def run(): Unit +``` +{% endtab %} +{% endtabs %} + +### 一个真实的例子 + +有关如何在 Scala 3 中使用类型类的真实示例，请参阅[多元相等性部分][multiversal]中的 `CanEqual` 讨论。 + +[typeclasses-paper]: https://infoscience.epfl.ch/record/150280/files/TypeClasses.pdf +[typeclasses-chapter]: {% link _overviews/scala3-book/ca-type-classes.md %} +[comparator]: https://docs.oracle.com/javase/8/docs/api/java/util/Comparator.html +[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %} diff --git a/_zh-cn/overviews/scala3-book/collections-classes.md b/_zh-cn/overviews/scala3-book/collections-classes.md new file mode 100644 index 0000000000..47ccd58bbe --- /dev/null +++ b/_zh-cn/overviews/scala3-book/collections-classes.md @@ -0,0 +1,861 @@ +--- +title: 集合类型 +type: section +description: This page introduces the common Scala 3 collections types and some of their methods. +language: zh-cn +num: 38 +previous-page: collections-intro +next-page: collections-methods + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +{% comment %} +TODO: mention Array, ArrayDeque, ListBuffer, Queue, Stack, StringBuilder? +LATER: note that methods like `+`, `++`, etc., are aliases for other methods +LATER: add links to the Scaladoc for the major types shown here +{% endcomment %} + +本页演示了常见的 Scala 3 集合及其附带的方法。 +Scala 提供了丰富的集合类型，但您可以从其中的几个开始，然后根据需要使用其他的。 +同样，每种集合类型都有数十种方法可以让您的生活更轻松，但您可以从其中的少数几个开始使用，就可以有很多收获。 + +因此，本节介绍并演示了在开始时，需要使用的最常见的类型和方法。 +当您需要更大的灵活性时，请参阅本节末尾的这些页面以获取更多细节。 + +## 三大类集合 + +从高层次看 Scala 集合，有三个主要类别可供选择： + +- **序列**是元素的顺序集合，可以是_有索引的_（如数组）或_线性的_（如链表） +- **映射** 包含键/值对的集合，例如 Java `Map`、Python 字典或 Ruby `Hash` +- **集合** 是无重复元素的无序集合 + +所有这些都是基本类型，并且具有用于特定目的的子类型，例如并发、缓存和流式传输。 +除了这三个主要类别之外，还有其他有用的集合类型，包括范围、堆栈和队列。 + +### 集合层次结构 + +作为简要概述，接下来的三个图显示了 Scala 集合中类和 trait 的层次结构。 + +第一张图显示了_scala.collection_包中的集合类型。 +这些都是高级抽象类或 traits，它们通常有_不可变_和_可变_的实现。 + +![一般集合层次结构][collections1] + +此图显示包 _scala.collection.immutable_ 中的所有集合： + +![不可变集合层次结构][collections2] + +此图显示包 _scala.collection.mutable_ 中的所有集合： + +![可变集合层次结构][collections3] + +在查看了所有集合类型的详细视图后，以下部分将介绍一些经常使用的常见类型。 + +{% comment %} +NOTE: those images come from this page: https://docs.scala-lang.org/overviews/collections-2.13/overview.html +{% endcomment %} + +## 常用集合 + +您经常使用的主要集合是： + +| 集合类型 | 不可变 | 可变 | 说明 | +| ------------- | --------- | -------- | ------------ | +| `List` | ✓ | | 线性（链表）、不可变序列 | +| `Vector` | ✓ | | 一个索引的、不可变的序列 | +| `LazyList` | ✓ | | 一个惰性不可变链表，它的元素仅在需要时才计算；适用于大型或无限序列。 | +| `ArrayBuffer` | | ✓ | 可变索引序列的首选类型 | +| `ListBuffer` | | ✓ | 当你想要一个可变的 `List` 时使用；通常转换为“列表” | +| `Map` | ✓ | ✓ | 由键和值对组成的可迭代集合。 | +| `Set` | ✓ | ✓ | 没有重复元素的可迭代集合 | + +如图所示，`Map` 和 `Set` 有不可变和可变版本。 + +以下部分演示了每种类型的基础知识。 + +> 在 Scala 中，_缓冲_——例如 `ArrayBuffer` 和 `ListBuffer`——是一个可以增长和缩小的序列。 + +### 关于不可变集合的说明 + +在接下来的部分中，无论何时使用_不可变_这个词，都可以安全地假设该类型旨在用于_函数式编程_(FP) 风格。 +使用这些类型，您无需修改集合；您将函数式方法应用于该集合以创建新的结果。 + +## 选择序列 + +选择_序列_ -- 一个顺序集合元素时 -- 您有两个主要决定： + +- 是否应该对序列进行索引（如数组），允许快速访问任何元素，还是应该将其实现为线性链表？ +- 你想要一个可变的还是不可变的集合？ + +此处显示了推荐的通用顺序集合，用于可变/不可变和索引/线性组合： + +| 类型/类别 | 不可变 | 可变 | +| --------------------- | --------- | ------------ | +|索引 | `Vector` |`ArrayBuffer` | +|线性（链表） | `List` |`ListBuffer` | + +例如，如果您需要一个不可变的索引集合，通常您应该使用 `Vector`。 +相反，如果您需要一个可变的索引集合，请使用 `ArrayBuffer`。 + +> `List` 和 `Vector` 在以函数式风格编写代码时经常使用。 +> `ArrayBuffer` 通常在以命令式风格编写代码时使用。 +> `ListBuffer` 用于混合样式时，例如构建列表。 + +接下来的几节简要介绍了 `List`、`Vector` 和 `ArrayBuffer` 类型。 + +## `List` + +[列表类型](https://www.scala-lang.org/api/current/scala/collection/immutable/List.html) 是一个线性的、不可变的序列。 +这只是意味着它是一个您无法修改的链表。 +任何时候你想添加或删除 `List` 元素，你都可以从现有的 `List` 中创建一个新的 `List`。 + +### 创建列表 + +这是创建初始“列表”的方式： + +{% tabs list-creation %} +{% tab 'Scala 2 and 3' %} +```scala +val ints = List(1, 2, 3) +val names = List("Joel", "Chris", "Ed") + +// another way to construct a List +val namesAgain = "Joel" :: "Chris" :: "Ed" :: Nil +``` +{% endtab %} +{% endtabs %} + +如果您愿意，也可以声明 `List` 的类型，但通常不是必需的： + +{% tabs list-type %} +{% tab 'Scala 2 and 3' %} +```scala +val ints: List[Int] = List(1, 2, 3) +val names: List[String] = List("Joel", "Chris", "Ed") +``` +{% endtab %} +{% endtabs %} + +一个例外是集合中有混合类型时。在这种情况下，您可能需要明确指定其类型： + +{% tabs list-mixed-types class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +val things: List[Any] = List(1, "two", 3.0) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +val things: List[String | Int | Double] = List(1, "two", 3.0) // with union types +val thingsAny: List[Any] = List(1, "two", 3.0) // with any +``` +{% endtab %} +{% endtabs %} + +### 将元素添加到列表 + +因为 `List` 是不可变的，所以你不能向它添加新元素。 +相反，您可以通过将元素添加到现有 `List` 来创建新列表。 +例如，给定这个 `List`： + +{% tabs adding-elements-init %} +{% tab 'Scala 2 and 3' %} +```scala +val a = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +使用 `List` 时，用 `::` 来_附加_一个元素，用 `:::` 把另一个 `List` 插在这个 `List` 之前，如下所示： + +{% tabs adding-elements-example %} +{% tab 'Scala 2 and 3' %} +```scala +val b = 0 :: a // List(0, 1, 2, 3) +val c = List(-1, 0) ::: a // List(-1, 0, 1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +你也可以在 `List` 中添加元素，但是因为 `List` 是一个单链表，你通常应该只在它前面添加元素； +在它的后面添加元素是一个相对较慢的操作，尤其是在处理大型序列时。 + +> 提示：如果您想将元素添加到不可变序列的前面或者后面时，请改用 `Vector`。 + +因为 `List` 是一个链表，你不应该尝试通过索引值来访问大列表的元素。 +例如，如果您有一个包含一百万个元素的 `List` ，则访问像 `myList(999_999)` 这样的元素将花费相对较长的时间，因为该请求必须遍历所有这些元素。 +如果您有一个大型集合并希望通过索引访问元素，请改用 `Vector` 或 `ArrayBuffer`。 + +### 如何记住方法名 + +现在 IDE 为我们提供了极大的帮助，但是记住这些方法名称的一种方法是，认为 `:` 字符代表序列所在的一侧，因此当您使用 `+:` 时，您知道列表需要在右边，像这样： + +{% tabs list-prepending %} +{% tab 'Scala 2 and 3' %} +```scala +0 +： a +``` +{% endtab %} +{% endtabs %} + +同样，当您使用 `:+` 时，您知道列表需要在左侧： + +{% tabs list-appending %} +{% tab 'Scala 2 and 3' %} +```scala +a ：+ 4 +``` +{% endtab %} +{% endtabs %} + +有更多的技术方法可以考虑这一点，但这可能是记住方法名称的有用方法。 + +{% comment %} +LATER: Add a discussion of `:` on method names, right-associativity, and infix operators. +{% endcomment %} + +此外，这些符号方法名称的一个好处是它们是一致的。 +相同的方法名称用于其他不可变序列，例如 `Seq` 和 `Vector`。 +如果您愿意，还可以使用非符号方法名称来附加元素和在头部插入元素。 + +### 如何遍历列表 + +给定一个名称 `List`： + +{% tabs list-loop-init %} +{% tab 'Scala 2 and 3' %} +```scala +val names = List("Joel", "Chris", "Ed") +``` +{% endtab %} +{% endtabs %} + +您可以像这样打印每个字符串： + +{% tabs list-loop-example class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +for (name <- names) println(name) +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +for name <- names do println(name) +``` +{% endtab %} +{% endtabs %} + +这是它在 REPL 中的样子： + +{% tabs list-loop-repl class=tabs-scala-version %} +{% tab 'Scala 2' %} +```scala +scala> for (name <- names) println(name) +Joel +Chris +Ed +``` +{% endtab %} + +{% tab 'Scala 3' %} +```scala +scala> for name <-names do println(name) +Joel +Chris +Ed +``` +{% endtab %} +{% endtabs %} + +将 `for` 循环与集合一起使用的一个好处是 Scala 是一致的，并且相同的方法适用于所有序列，包括 `Array`、`ArrayBuffer`、`List`、`Seq`、`Vector`、`Map` ，`Set` 等。 + +### 一点历史 + +对于那些对历史感兴趣的人，Scala `List` 类似于 [Lisp 编程语言](https://en.wikipedia.org/wiki/Lisp_(programming_language)) 中的 `List`，它是最初于 1958 年确定的。 +实际上，除了像这样创建一个 `List` 之外： + +{% tabs list-history-init %} +{% tab 'Scala 2 and 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +您也可以通过这种方式创建完全相同的列表： + +{% tabs list-history-init2 %} +{% tab 'Scala 2 and 3' %} +```scala +val list = 1 :: 2 :: 3 :: Nil +``` +{% endtab %} +{% endtabs %} + +REPL 展示了它是如何工作的： + +{% tabs list-history-repl %} +{% tab 'Scala 2 and 3' %} +```scala +scala> val list = 1 :: 2 :: 3 :: Nil +list: List[Int] = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +这是因为 `List` 是一个以 `Nil` 元素结尾的单链表，而 `::` 是一个 `List` 方法，其工作方式类似于 Lisp 的“cons”运算符。 + +### 旁白：LazyList + +Scala 集合还包括一个 [LazyList](https://www.scala-lang.org/api/current/scala/collection/immutable/LazyList.html)，它是一个 _惰性_不可变链表。 +它被称为“惰性”——或非严格——因为它仅在需要时计算其元素。 + +你可以看到 REPL 中的 `LazyList` 有多懒惰： + +{% tabs lazylist-example %} +{% tab 'Scala 2 and 3' %} +```scala +val x = LazyList.range(1, Int.MaxValue) +x.take(1) // LazyList(+ 这是 Scala 3 里的新东西，在 Scala 2 里不支持。 ++ +如果您愿意，可以选择在每个表达式的末尾包含 `end if` 语句： + +{% tabs control-structures-5 %} +{% tab 'Scala 3 Only' %} + +```scala +if x == 1 then + println("x is 1, as you can see:") + println(x) +end if +``` + +{% endtab %} +{% endtabs %} + +### `if`/`else` 表达式总是有返回值 + +请注意， `if` / `else` 比较形式为 _表达式_，这意味着它们返回一个可以分配给变量的值。 +因此，不需要特殊的三元运算符： + +{% tabs control-structures-6 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-6 %} + +```scala +val minValue = if (a < b) a else b +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-6 %} + +```scala +val minValue = if a < b then a else b +``` + +{% endtab %} +{% endtabs %} + +由于它们返回一个值，因此可以使用 `if`/`else` 表达式作为方法的主体： + +{% tabs control-structures-7 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-7 %} + +```scala +def compare(a: Int, b: Int): Int = + if (a < b) + -1 + else if (a == b) + 0 + else + 1 +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-7 %} + +```scala +def compare(a: Int, b: Int): Int = + if a < b then + -1 + else if a == b then + 0 + else + 1 +``` + +{% endtab %} +{% endtabs %} + +### 题外话：面向表达式的编程 + +作为一般编程的简要说明，当您编写的每个表达式都返回一个值时，该样式称为面向 _面向表达式的编程_ 或 EOP。 +例如，这是一个 _表达式_： + +{% tabs control-structures-8 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-8 %} + +```scala +val minValue = if (a < b) a else b +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-8 %} + +```scala +val minValue = if a < b then a else b +``` + +{% endtab %} +{% endtabs %} + +相反，不返回值的代码行称为 _语句_，用它们的 _副作用_。 +例如，这些代码行不返回值，因此用它们的副作用： + +{% tabs control-structures-9 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-9 %} + +```scala +if (a == b) action() +println("Hello") +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-9 %} + +```scala +if a == b then action() +println("Hello") +``` + +{% endtab %} +{% endtabs %} + +第一个示例在 `a` 等于 `b` 时将 `action` 方法作为副作用运行。 +第二个示例用于将字符串打印到 STDOUT 的副作用。 +随着你对Scala的了解越来越多，你会发现自己写的 _表达式_ 越来越多，_语句_ 也越来越少。 + +## `for` 循环 + +在最简单的用法中，Scala `for` 循环可用于迭代集合中的元素。 +例如，给定一个整数序列，您可以循环访问其元素并打印其值，如下所示： + +{% tabs control-structures-10 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-10 %} + +```scala +val ints = Seq(1, 2, 3) +for (i <- ints) println(i) +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-10 %} + +```scala +val ints = Seq(1, 2, 3) +for i <- ints do println(i) +``` + +{% endtab %} +{% endtabs %} + +代码 `i <- ints` 被称为 _生成器_。 + +这是在 Scala REPL 中的结果： + +{% tabs control-structures-11 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for (i <- ints) println(i) +1 +2 +3 +```` +{% endtab %} +{% tab 'Scala 3' for=control-structures-11 %} +```` +scala> val ints = Seq(1,2,3) +ints: Seq[Int] = List(1, 2, 3) + +scala> for i <- ints do println(i) +1 +2 +3 +```` + +{% endtab %} +{% endtabs %} + +如果需要在 `for` 生成器后面显示多行代码块，请使用以下语法：ddu + +{% tabs control-structures-12 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-12 %} + +```scala +for (i <- ints) { + val x = i * 2 + println(s"i = $i, x = $x") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-12 %} + +```scala +for + i <- ints +do + val x = i * 2 + println(s"i = $i, x = $x") +``` + +{% endtab %} +{% endtabs %} + +### 多生成器 + +`for` 循环可以有多个生成器，如以下示例所示： + +{% tabs control-structures-13 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-13 %} + +```scala +for { + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +} { + println(s"i = $i, j = $j, k = $k") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-13 %} + +```scala +for + i <- 1 to 2 + j <- 'a' to 'b' + k <- 1 to 10 by 5 +do + println(s"i = $i, j = $j, k = $k") +``` + +{% endtab %} +{% endtabs %} + +那个表达式的输出： + +```` +i = 1, j = a, k = 1 +i = 1, j = a, k = 6 +i = 1, j = b, k = 1 +i = 1, j = b, k = 6 +i = 2, j = a, k = 1 +i = 2, j = a, k = 6 +i = 2, j = b, k = 1 +i = 2, j = b, k = 6 +```` + +### 守卫 + +`for` 循环也可以包含 `if` 语句，这些语句称为 _守卫_： + +{% tabs control-structures-14 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-14 %} + +```scala +for { + i <- 1 to 5 + if i % 2 == 0 +} { + println(i) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-14 %} + +```scala +for + i <- 1 to 5 + if i % 2 == 0 +do + println(i) +``` + +{% endtab %} +{% endtabs %} + +以上循环的输出是： + +```` +2 +4 +```` + +`for` 循环可以根据需要有任意数量的守卫。 +此示例显示了打印数字`4`的一种方法： + +{% tabs control-structures-15 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-15 %} + +```scala +for { + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +} { + println(i) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-15 %} + +```scala +for + i <- 1 to 10 + if i > 3 + if i < 6 + if i % 2 == 0 +do + println(i) +``` + +{% endtab %} +{% endtabs %} + +### 把 `for` 用在 `Map` 上 + +您还可以将 `for` 循环与 `Map` 一起使用。 +例如，给定州缩写及其全名的 `Map`： + +{% tabs map %} +{% tab 'Scala 2 and 3' for=map %} + +```scala +val states = Map( + "AK" -> "Alaska", + "AL" -> "Alabama", + "AR" -> "Arizona" +) +``` + +{% endtab %} +{% endtabs %} + +您可以使用 `for` 打印键和值，如下所示： + +{% tabs control-structures-16 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-16 %} + +```scala +for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-16 %} + +```scala +for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +``` + +{% endtab %} +{% endtabs %} + +以下是 REPL 中的样子： + +{% tabs control-structures-17 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-17 %} + +```scala +scala> for ((abbrev, fullName) <- states) println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-17 %} + +```scala +scala> for (abbrev, fullName) <- states do println(s"$abbrev: $fullName") +AK: Alaska +AL: Alabama +AR: Arizona +``` + +{% endtab %} +{% endtabs %} + +当 `for` 循环遍历映射时，每个键/值对都绑定到变量 `abbrev` 和 `fullName` ，它们位于元组中： + +{% tabs tuple %} +{% tab 'Scala 2 and 3' for=tuple %} + +```scala +(abbrev, fullName) <- states +``` + +{% endtab %} +{% endtabs %} + +当循环运行时，变量 `abbrev` 被分配给映射中的当前 _键_，变量 `fullName` 被分配给当前map 的 _值_。 + +## `for` 表达式 + +在前面的 `for` 循环示例中，这些循环都用于 _副作用_，特别是使用 `println` 将这些值打印到STDOUT。 + +重要的是要知道，您还可以创建有返回值的 `for` _表达式_。 +您可以通过添加 `yield` 关键字和要返回的表达式来创建 `for` 表达式，如下所示： + +{% tabs control-structures-18 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-18 %} + +```scala +val list = + for (i <- 10 to 12) + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` +{% endtab %} +{% tab 'Scala 3' for=control-structures-18 %} + +```scala +val list = + for i <- 10 to 12 + yield i * 2 + +// list: IndexedSeq[Int] = Vector(20, 22, 24) +``` + +{% endtab %} +{% endtabs %} + +在 `for` 表达式运行后，变量 `list` 是包含所示值的 `Vector` 。 +这是表达式的工作原理： + +1. `for` 表达式开始循环访问范围 `(10, 11, 12)` 中的值。 + 它首先处理值`10`，将其乘以`2`，然后 _产生_ 结果为`20`的值。 +2. 接下来，它处理`11`---该范围中的第二个值。 + 它乘以`2`，然后产生值`22`。 + 您可以将这些产生的值看作它们累积在某个临时位置。 +3. 最后，循环从范围中获取数字 `12`，将其乘以 `2`，得到数字 `24`。 + 循环此时完成并产生最终结果 `Vector(20, 22, 24)`。 + +{% comment %} +NOTE: This is a place where it would be great to have a TIP or NOTE block: +{% endcomment %} + +虽然本节的目的是演示 `for` 表达式，但它可以帮助知道显示的 `for` 表达式等效于以下 `map` 方法调用： + +{% tabs map-call %} +{% tab 'Scala 2 and 3' for=map-call %} + +```scala +val list = (10 to 12).map(i => i * 2) +``` + +{% endtab %} +{% endtabs %} + +只要您需要遍历集合中的所有元素，并将算法应用于这些元素以创建新列表，就可以使用 `for` 表达式。 + +下面是一个示例，演示如何在 `yield` 之后使用代码块： + +{% tabs control-structures-19 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-19 %} + +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for (name <- names) yield { + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName +} + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-19 %} + +```scala +val names = List("_olivia", "_walter", "_peter") + +val capNames = for name <- names yield + val nameWithoutUnderscore = name.drop(1) + val capName = nameWithoutUnderscore.capitalize + capName + +// capNames: List[String] = List(Olivia, Walter, Peter) +``` + +{% endtab %} +{% endtabs %} + +### 使用 `for` 表达式作为方法的主体 + +由于 `for` 表达式产生结果，因此可以将其用作返回有用值的方法的主体。 +此方法返回给定整数列表中介于`3`和`10`之间的所有值： + +{% tabs control-structures-20 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-20 %} + +```scala +def between3and10(xs: List[Int]): List[Int] = + for { + x <- xs + if x >= 3 + if x <= 10 + } yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-20 %} + +```scala +def between3and10(xs: List[Int]): List[Int] = + for + x <- xs + if x >= 3 + if x <= 10 + yield x + +between3and10(List(1, 3, 7, 11)) // : List[Int] = List(3, 7) +``` + +{% endtab %} +{% endtabs %} + +## `while` 循环 + +Scala `while` 循环语法如下： + +{% tabs control-structures-21 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-21 %} + +```scala +var i = 0 + +while (i < 3) { + println(i) + i += 1 +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-21 %} + +```scala +var i = 0 + +while i < 3 do + println(i) + i += 1 +``` + +{% endtab %} +{% endtabs %} + +## `match` 表达式 + +模式匹配是函数式编程语言的一个主要特征，Scala包含一个具有许多功能的 `match` 表达式。 + +在最简单的情况下，您可以使用 `match` 表达式，象Java `switch` 语句，根据整数值匹配。 +请注意，这实际上是一个表达式，因为它计算出一个结果： + +{% tabs control-structures-22 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-22 %} + +```scala +// `i` is an integer +val day = i match { + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // the default, catch-all +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-22 %} + +```scala +import scala.annotation.switch + +// `i` is an integer +val day = i match + case 0 => "Sunday" + case 1 => "Monday" + case 2 => "Tuesday" + case 3 => "Wednesday" + case 4 => "Thursday" + case 5 => "Friday" + case 6 => "Saturday" + case _ => "invalid day" // the default, catch-all +``` + +{% endtab %} +{% endtabs %} + +在此示例中，变量 `i` 根据所示情况进行测试。 +如果它介于`0`和`6`之间，则 `day` 绑定到一个字符串，该字符串表示一周中的某一天。 +否则，捕获所有情况，这些情况用 `_` 字符表示，这样 `day` 绑定到字符串 `"invalid day"`。 + +> 在编写像这样的简单 `match` 表达式时，建议在变量 `i` 上使用 `@switch` 注释。 +> 如果开关无法编译为 `tableswitch` 或 `lookupswitch`，则此注释会提供编译时警告，这个开关对性能更好。 + +### 使用缺省值 + +当您需要访问 `match` 表达式中匹配所有情况，也就是默认值时，只需在 `case` 语句的左侧提供一个变量名而不是 `_`，然后根据需要在语句的右侧使用该变量名称： + +{% tabs control-structures-23 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-23 %} + +```scala +i match { + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-23 %} + +```scala +i match + case 0 => println("1") + case 1 => println("2") + case what => println(s"You gave me: $what" ) +``` + +{% endtab %} +{% endtabs %} + +在模式中使用的名称必须以小写字母开头。 +以大写字母开头的名称并不引入变量，而是匹配该范围内的一个值： + +{% tabs control-structures-24 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-24 %} + +```scala +val N = 42 +i match { + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-24 %} + +```scala +val N = 42 +i match + case 0 => println("1") + case 1 => println("2") + case N => println("42") + case n => println(s"You gave me: $n" ) +``` + +{% endtab %} +{% endtabs %} + +如果 `i` 等于`42`，则 `case N` 将匹配，然后打印字符串`"42"`。它不会到达默认分支。 + +### 在一行上处理多个可能的匹配项 + +如前所述，`match` 表达式具有许多功能。 +此示例演示如何在每个 `case` 语句中使用多个可能的模式匹配： + +{% tabs control-structures-25 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-25 %} + +```scala +val evenOrOdd = i match { + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-25 %} + +```scala +val evenOrOdd = i match + case 1 | 3 | 5 | 7 | 9 => println("odd") + case 2 | 4 | 6 | 8 | 10 => println("even") + case _ => println("some other number") +``` + +{% endtab %} +{% endtabs %} + +### 在 `case` 子句中使用 `if` 守卫 + +您还可以在匹配表达式的 `case` 中使用守卫装置。 +在此示例中，第二个和第三个 `case` 都使用守卫来匹配多个整数值： + +{% tabs control-structures-26 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-26 %} + +```scala +i match { + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-26 %} + +```scala +i match + case 1 => println("one, a lonely number") + case x if x == 2 || x == 3 => println("two’s company, three’s a crowd") + case x if x > 3 => println("4+, that’s a party") + case _ => println("i’m guessing your number is zero or less") +``` + +{% endtab %} +{% endtabs %} + +下面是另一个示例，它显示了如何将给定值与数字范围进行匹配： + +{% tabs control-structures-27 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-27 %} + +```scala +i match { + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-27 %} + +```scala +i match + case a if 0 to 9 contains a => println(s"0-9 range: $a") + case b if 10 to 19 contains b => println(s"10-19 range: $b") + case c if 20 to 29 contains c => println(s"20-29 range: $c") + case _ => println("Hmmm...") +``` + +{% endtab %} +{% endtabs %} + +#### 样例类和 match 表达式 + +您还可以从 `case` 类中提取字段 —— 以及正确编写了 `apply`/`unapply` 方法的类 —— 并在守卫条件下使用这些字段。 +下面是一个使用简单 `Person` 案例类的示例： + +{% tabs control-structures-28 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-28 %} + +```scala +case class Person(name: String) + +def speak(p: Person) = p match { + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") +} + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-28 %} + +```scala +case class Person(name: String) + +def speak(p: Person) = p match + case Person(name) if name == "Fred" => println(s"$name says, Yubba dubba doo") + case Person(name) if name == "Bam Bam" => println(s"$name says, Bam bam!") + case _ => println("Watch the Flintstones!") + +speak(Person("Fred")) // "Fred says, Yubba dubba doo" +speak(Person("Bam Bam")) // "Bam Bam says, Bam bam!" +``` + +{% endtab %} +{% endtabs %} + +### 使用 `match` 表达式作为方法的主体 + +由于 `match` 表达式返回一个值，因此它们可以用作方法的主体。 +此方法采用 `Matchable` 值作为输入参数，并根据 `match` 表达式的结果返回 `Boolean`： + +{% tabs control-structures-29 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-29 %} + +```scala +def isTruthy(a: Matchable) = a match { + case 0 | "" | false => false + case _ => true +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-29 %} + +```scala +def isTruthy(a: Matchable) = a match + case 0 | "" | false => false + case _ => true +``` + +{% endtab %} +{% endtabs %} + +输入参数 `a` 被定义为 [`Matchable`类型][matchable]---这是可以对其执行模式匹配的所有Scala类型的根。 +该方法通过在输入上进行匹配来实现，提供两种情况： +第一个检查给定值是整数`0`，空字符串还是 `false`，在这种情况下返回 `false`。 +在默认情况下，我们为任何其他值返回 `true`。 +以下示例演示此方法的工作原理： + +{% tabs is-truthy-call %} +{% tab 'Scala 2 and 3' for=is-truthy-call %} + +```scala +isTruthy(0) // false +isTruthy(false) // false +isTruthy("") // false +isTruthy(1) // true +isTruthy(" ") // true +isTruthy(2F) // true +``` + +{% endtab %} +{% endtabs %} + +使用 `match` 表达式作为方法的主体是一种非常常见的用法。 + +#### 匹配表达式支持许多不同类型的模式 + +有许多不同形式的模式可用于编写 `match` 表达式。 +示例包括： + +- 常量模式（如 `case 3 => `） +- 序列模式（如 `case List(els : _*) =>`） +- 元组模式（如 `case (x, y) =>`） +- 构造函数模式（如 `case Person(first, last) =>`） +- 类型测试模式（如 `case p: Person =>`） + +所有这些类型的模式匹配都展示在以下 `pattern` 方法中，该方法采用类型为 `Matchable` 的输入参数并返回 `String` ： + +{% tabs control-structures-30 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-30 %} + +```scala +def pattern(x: Matchable): String = x match { + + // constant patterns + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // sequence patterns + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // tuple patterns + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // constructor patterns + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // type test patterns + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // the default wildcard pattern + case _ => "Unknown" +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-30 %} + +```scala +def pattern(x: Matchable): String = x match + + // constant patterns + case 0 => "zero" + case true => "true" + case "hello" => "you said 'hello'" + case Nil => "an empty List" + + // sequence patterns + case List(0, _, _) => "a 3-element list with 0 as the first element" + case List(1, _*) => "list, starts with 1, has any number of elements" + case Vector(1, _*) => "vector, starts w/ 1, has any number of elements" + + // tuple patterns + case (a, b) => s"got $a and $b" + case (a, b, c) => s"got $a, $b, and $c" + + // constructor patterns + case Person(first, "Alexander") => s"Alexander, first name = $first" + case Dog("Zeus") => "found a dog named Zeus" + + // type test patterns + case s: String => s"got a string: $s" + case i: Int => s"got an int: $i" + case f: Float => s"got a float: $f" + case a: Array[Int] => s"array of int: ${a.mkString(",")}" + case as: Array[String] => s"string array: ${as.mkString(",")}" + case d: Dog => s"dog: ${d.name}" + case list: List[?] => s"got a List: $list" + case m: Map[?, ?] => m.toString + + // the default wildcard pattern + case _ => "Unknown" +``` + +{% endtab %} +{% endtabs %} + +{% comment %} +TODO: Add in the new Scala 3 syntax shown on this page: +http://dotty.epfl.ch/docs/reference/changed-features/match-syntax.html +{% endcomment %} + +## try/catch/finally + +与Java一样，Scala也有一个 `try`/`catch`/`finally` 结构，让你可以捕获和管理异常。 +为了保持一致性，Scala使用与 `match` 表达式相同的语法，并支持在可能发生的不同可能的异常上进行模式匹配。 + +在下面的示例中，`openAndReadAFile` 是一个执行其名称含义的方法：它打开一个文件并读取其中的文本，将结果分配给可变变量 `text` ： + +{% tabs control-structures-31 class=tabs-scala-version %} +{% tab 'Scala 2' for=control-structures-31 %} + +```scala +var text = "" +try { + text = openAndReadAFile(filename) +} catch { + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +} finally { + // close your resources here + println("Came to the 'finally' clause.") +} +``` + +{% endtab %} +{% tab 'Scala 3' for=control-structures-31 %} + +```scala +var text = "" +try + text = openAndReadAFile(filename) +catch + case fnf: FileNotFoundException => fnf.printStackTrace() + case ioe: IOException => ioe.printStackTrace() +finally + // close your resources here + println("Came to the 'finally' clause.") +``` + +{% endtab %} +{% endtabs %} + +假设 `openAndReadAFile` 方法使用 Java `java.io.*` 类来读取文件并且不捕获其异常，则尝试打开和读取文件可能会导致 `FileNotFoundException` 和 `IOException` 异常，本例中，这两个异常在 `catch` 块中被捕获。 + +[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-fp.md b/_zh-cn/overviews/scala3-book/domain-modeling-fp.md new file mode 100644 index 0000000000..46797dfc7e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-fp.md @@ -0,0 +1,817 @@ +--- +title: 函数式领域建模 +type: section +description: This chapter provides an introduction to FP domain modeling with Scala 3. +language: zh-cn +num: 23 +previous-page: domain-modeling-oop +next-page: methods-intro + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍了在 Scala 3 中使用函数式编程 (FP) 进行领域建模。 +当使用 FP 对我们周围的世界进行建模时，您通常会使用以下 Scala 构造： + +- 枚举 +- 样例类 +- Traits + +> 如果您不熟悉代数数据类型 (ADT) 及其泛型版本 (GADT)，您可能需要先阅读 [代数数据类型][adts] 部分，然后再阅读本节。 + +## 介绍 + +在 FP 中，*数据*和*对该数据的操作*是两个独立的东西；您不必像使用 OOP 那样将它们封装在一起。 + +这个概念类似于数值代数。 +当您考虑值大于或等于零的整数时，您有一*组*可能的值，如下所示： + +```` +0, 1, 2 ... Int.MaxValue +```` + +忽略整数的除法，对这些值可能的*操作*是： + +```` ++, -, * +```` + +FP设计以类似的方式实现： + +- 你描述你的值的集合（你的数据） +- 您描述了对这些值起作用的操作（您的函数） + +> 正如我们将看到的，这种风格的程序推理与面向对象的编程完全不同。 +> FP 中的数据只**是**： +> 将功能与数据分离，让您无需担心行为即可检查数据。 + +在本章中，我们将为披萨店中的“披萨”建模数据和操作。 +您将看到如何实现 Scala/FP 模型的“数据”部分，然后您将看到几种不同的方式来组织对该数据的操作。 + +## 数据建模 + +在 Scala 中，描述编程问题的数据模型很简单： + +- 如果您想使用不同的替代方案对数据进行建模，请使用 `enum` 结构，（或者在 Scala 2 中用 `case object`）。 +- 如果您只想对事物进行分组（或需要更细粒度的控制），请使用 样例类 + +### 描述替代方案 + +简单地由不同的选择组成的数据，如面饼大小、面饼类型和馅料，在 Scala 中使用枚举进行简洁的建模： + +{% tabs data_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_1 %} + +在 Scala 2 中，一个 `sealed class` 和若干个继承自该类的 `case object` 组合在一起来表示枚举： + +```scala +sealed abstract class CrustSize +object CrustSize { + case object Small extends CrustSize + case object Medium extends CrustSize + case object Large extends CrustSize +} + +sealed abstract class CrustType +object CrustType { + case object Thin extends CrustType + case object Thick extends CrustType + case object Regular extends CrustType +} + +sealed abstract class Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_1 %} + +在 Scala 3 中，用 `enum` 结构简洁地表示： + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +> 描述不同选择的数据类型（如 `CrustSize`）有时也称为_归纳类型_。 + +### 描述复合数据 + +可以将披萨饼视为上述不同属性的_组件_容器。 +我们可以使用 样例类来描述 `Pizza` 由 `crustSize`、`crustType` 和可能的多个 `Topping` 组成： + +{% tabs data_2 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_2 %} + +```scala +import CrustSize._ +import CrustType._ +import Topping._ + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% tab 'Scala 3' for=data_2 %} + +```scala +import CrustSize.* +import CrustType.* +import Topping.* + +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) +``` + +{% endtab %} +{% endtabs %} + +> 聚合多个组件的数据类型（如`Pizza`）有时也称为_乘积类型_。 + +就是这样。 +这就是 FP 式披萨系统的数据模型。 +该解决方案非常简洁，因为它不需要将披萨饼上的操作与数据模型相结合。 +数据模型易于阅读，就像声明关系数据库的设计一样。 +创建数据模型的值并检查它们也很容易： + +{% tabs data_3 %} +{% tab 'Scala 2 and 3' for=data_3 %} + +```scala +val myFavPizza = Pizza(Small, Regular, Seq(Cheese, Pepperoni)) +println(myFavPizza.crustType) // prints Regular +``` + +{% endtab %} +{% endtabs %} + +#### 更多数据模型 + +我们可能会以同样的方式对整个披萨订购系统进行建模。 +下面是一些用于对此类系统建模的其他 样例类： + +{% tabs data_4 %} +{% tab 'Scala 2 and 3' for=data_4 %} + +```scala +case class Address( + street1: String, + street2: Option[String], + city: String, + state: String, + zipCode: String +) + +case class Customer( + name: String, + phone: String, + address: Address +) + +case class Order( + pizzas: Seq[Pizza], + customer: Customer +) +``` + +{% endtab %} +{% endtabs %} + +#### “瘦领域对象（贫血模型）” + +Debasish Ghosh 在他的《*函数式和反应式领域建模*》一书中指出，OOP 从业者将他们的类描述为封装数据和行为的“富领域模型（充血模型）”，而 FP 数据模型可以被认为是“瘦领域对象”。 +这是因为——正如本课所示——数据模型被定义为具有属性但没有行为的样例类，从而产生了简短而简洁的数据结构。 + +## 操作建模 + +这就引出了一个有趣的问题：因为 FP 将数据与对该数据的操作分开，那么如何在 Scala 中实现这些操作？ + +答案实际上很简单：您只需编写对我们刚刚建模的数据值进行操作的函数（或方法）。 +例如，我们可以定义一个计算披萨价格的函数。 + +{% tabs data_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match { + case Pizza(crustSize, crustType, toppings) => { + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops + } +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_5 %} + +```scala +def pizzaPrice(p: Pizza): Double = p match + case Pizza(crustSize, crustType, toppings) => + val base = 6.00 + val crust = crustPrice(crustSize, crustType) + val tops = toppings.map(toppingPrice).sum + base + crust + tops +``` + +{% endtab %} +{% endtabs %} + +您注意到函数的实现如何简单地遵循数据的样式：由于 `Pizza` 是一个样例类，我们使用模式匹配来提取组件并调用辅助函数来计算各个部分单独的价格。 + +{% tabs data_6 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match { + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +} +``` + +{% endtab %} +{% tab 'Scala 3' for=data_6 %} + +```scala +def toppingPrice(t: Topping): Double = t match + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +``` + +{% endtab %} +{% endtabs %} + +同样，由于 `Topping` 是一个枚举，我们使用模式匹配来区分不同的变量。 +奶酪和洋葱的价格为 50ct，其余的价格为 75ct。 + +{% tabs data_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match { + // if the crust size is small or medium, + // the type is not important + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 + } +``` + +{% endtab %} +{% tab 'Scala 3' for=data_7 %} + +```scala +def crustPrice(s: CrustSize, t: CrustType): Double = + (s, t) match + // if the crust size is small or medium, + // the type is not important + case (Small | Medium, _) => 0.25 + case (Large, Thin) => 0.50 + case (Large, Regular) => 0.75 + case (Large, Thick) => 1.00 +``` + +{% endtab %} +{% endtabs %} + +为了计算面饼的价格，我们同时对面饼的大小和类型进行模式匹配。 + +> 关于上面显示的所有函数的重要一点是它们是*纯函数*：它们不会改变任何数据或有其他副作用（如抛出异常或写入文件）。 +> 他们所做的只是简单地接收值并计算结果。 + +{% comment %} +I’ve added this comment per [this Github comment](https://github.com/scalacenter/docs.scala-lang/pull/3#discussion_r543372428). +To that point, I’ve added these definitions here from our Slack conversation, in case anyone wants to update the “pure function” definition. If not, please delete this comment. + +Sébastien: +---------- +A function `f` is pure if, given the same input `x`, it will always return the same output `f(x)`, and it never modifies any state outside of it (therefore potentially causing other functions to behave differently in the future). + +Jonathan: +--------- +We say a function is 'pure' if it does not depend on or modify the context it is called in. + +Wikipedia +--------- +The function always evaluates to the same result value given the same argument value(s). It cannot depend on any hidden state or value, and it cannot depend on any I/O. +Evaluation of the result does not cause any semantically observable side effect or output, such as mutation of mutable objects or output to I/O devices. + +Mine (Alvin, now modified, from fp-pure-functions.md): +------------------------------------------------------ +- A function `f` is pure if, given the same input `x`, it always returns the same output `f(x)` +- The function’s output depends *only* on its input variables and its internal algorithm +- It doesn’t modify its input parameters +- It doesn’t mutate any hidden state +- It doesn’t have any “back doors”: It doesn’t read data from the outside world (including the console, web services, databases, files, etc.), or write data to the outside world +{% endcomment %} + +## 如何组织功能 + +在实现上面的 `pizzaPrice` 函数时，我们没有说我们将在*哪里*定义它。 +在 Scala 3 中，在文件的顶层定义它是完全有效的。 +但是，该语言为我们提供了许多很棒的工具在不同命名空间和模块中组织我们的逻辑。 + +有几种不同的方式来实现和组织行为： + +- 在伴生对象中定义您的函数 +- 使用模块化编程风格 +- 使用“函数式对象”方法 +- 在扩展方法中定义功能 + +在本节的其余部分将展示这些不同的解决方案。 + +### 伴生对象 + +第一种方法是在伴生对象中定义行为——函数。 + +> 正如在领域建模 [工具部分][modeling-tools] 中所讨论的，_伴生对象_ 是一个与类同名的 `object` ，并在与类相同的文件中声明。 + +使用这种方法，除了枚举或样例类之外，您还定义了一个包含该行为的同名伴生对象。 + +{% tabs org_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// the companion object of case class Pizza +object Pizza { + // the implementation of `pizzaPrice` from above + def price(p: Pizza): Double = ... +} + +sealed abstract class Topping + +// the companion object of enumeration Topping +object Topping { + case object Cheese extends Topping + case object Pepperoni extends Topping + case object BlackOlives extends Topping + case object GreenOlives extends Topping + case object Onions extends Topping + + // the implementation of `toppingPrice` above + def price(t: Topping): Double = ... +} +``` + +{% endtab %} +{% tab 'Scala 3' for=org_1 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +// the companion object of case class Pizza +object Pizza: + // the implementation of `pizzaPrice` from above + def price(p: Pizza): Double = ... + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions + +// the companion object of enumeration Topping +object Topping: + // the implementation of `toppingPrice` above + def price(t: Topping): Double = t match + case Cheese | Onions => 0.5 + case Pepperoni | BlackOlives | GreenOlives => 0.75 +``` + +{% endtab %} +{% endtabs %} + +使用这种方法，您可以创建一个 `Pizza` 并计算其价格，如下所示： + +{% tabs org_2 %} +{% tab 'Scala 2 and 3' for=org_2 %} + +```scala +val pizza1 = Pizza(Small, Thin, Seq(Cheese, Onions)) +Pizza.price(pizza1) +``` + +{% endtab %} +{% endtabs %} + +以这种方式对功能进行分组有几个优点： + +- 它将功能与数据相关联，让程序员（和编译器）更容易找到它。 +- 它创建了一个命名空间，例如让我们使用 `price` 作为方法名称，而不必依赖重载。 +- `Topping.price` 的实现可以访问枚举值，例如 `Cheese` ，而无需导入它们。 + +但是，还应权衡： + +- 它将功能与您的数据模型紧密结合。 + 特别是，伴生对象需要在与您的样例类相同的文件中定义。 +- 可能不清楚在哪里定义像 `crustPrice` 这样同样可以放置在 `CrustSize` 或 `CrustType` 的伴生对象中的函数。 + +## 模块 + +组织行为的第二种方法是使用“模块化”方法。 +这本书，*Programming in Scala*，将 *模块* 定义为“具有良好定义的接口和隐藏实现的‘较小的程序片段’”。 +让我们看看这意味着什么。 + +### 创建一个 `PizzaService` 接口 + +首先要考虑的是 `Pizza` 的“行为”。 +执行此操作时，您可以像这样草拟一个 `PizzaServiceInterface` trait： + +{% tabs module_1 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_1 %} + +```scala +trait PizzaServiceInterface { + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +} +``` + +{% endtab %} +{% tab 'Scala 3' for=module_1 %} + +```scala +trait PizzaServiceInterface: + + def price(p: Pizza): Double + + def addTopping(p: Pizza, t: Topping): Pizza + def removeAllToppings(p: Pizza): Pizza + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza + def updateCrustType(p: Pizza, ct: CrustType): Pizza +``` + +{% endtab %} +{% endtabs %} + +如图所示，每个方法都将 `Pizza` 作为输入参数——连同其他参数——然后返回一个 `Pizza` 实例作为结果 + +当你写一个像这样的纯接口时，你可以把它想象成一个约定，“所有扩展这个特性的非抽象类*必须*提供这些服务的实现。” + +此时您还可以做的是想象您是此 API 的使用者。 +当你这样做时，它有助于草拟一些示例“消费者”代码，以确保 API 看起来像你想要的： + +{% tabs module_2 %} +{% tab 'Scala 2 and 3' for=module_2 %} + +```scala +val p = Pizza(Small, Thin, Seq(Cheese)) + +// how you want to use the methods in PizzaServiceInterface +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) +``` + +{% endtab %} +{% endtabs %} + +如果该代码看起来没问题，您通常会开始草拟另一个 API ——例如用于订单的 API ——但由于我们现在只关注披萨饼，我们将停止考虑接口，然后创建这个接口的具体实现。 + +> 请注意，这通常是一个两步过程。 +> 在第一步中，您将 API 的合同草拟为*接口*。 +> 在第二步中，您创建该接口的具体*实现*。 +> 在某些情况下，您最终会创建基本接口的多个具体实现。 + +### 创建一个具体的实现 + +现在您知道了 `PizzaServiceInterface` 的样子，您可以通过为接口中定义的所有方法体来创建它的具体实现： + +{% tabs module_3 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface { + + def price(p: Pizza): Double = + ... // implementation from above + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=module_3 %} + +```scala +object PizzaService extends PizzaServiceInterface: + + def price(p: Pizza): Double = + ... // implementation from above + + def addTopping(p: Pizza, t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings(p: Pizza): Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(p: Pizza, cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(p: Pizza, ct: CrustType): Pizza = + p.copy(crustType = ct) + +end PizzaService +``` + +{% endtab %} +{% endtabs %} + +虽然创建接口和实现的两步过程并不总是必要的，但明确考虑 API 及其使用是一种好方法。 + +一切就绪后，您可以使用 `Pizza` 类和 `PizzaService`： + +{% tabs module_4 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_4 %} + +```scala +import PizzaService._ + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// use the PizzaService methods +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // prints 8.75 +``` + +{% endtab %} +{% tab 'Scala 3' for=module_4 %} + +```scala +import PizzaService.* + +val p = Pizza(Small, Thin, Seq(Cheese)) + +// use the PizzaService methods +val p1 = addTopping(p, Pepperoni) +val p2 = addTopping(p1, Onions) +val p3 = updateCrustType(p2, Thick) +val p4 = updateCrustSize(p3, Large) + +println(price(p4)) // prints 8.75 +``` + +{% endtab %} +{% endtabs %} + +### 函数对象 + +在 *Programming in Scala* 一书中，作者将术语“函数对象”定义为“不具有任何可变状态的对象”。 +`scala.collection.immutable` 中的类型也是如此。 +例如，`List` 上的方法不会改变内部状态，而是创建 `List` 的副本作为结果。 + +您可以将此方法视为“混合 FP/OOP 设计”，因为您： + +- 使用不可变的 样例类对数据进行建模。 +- 定义_同类型_数据中的行为（方法）。 +- 将行为实现为纯函数：它们不会改变任何内部状态；相反，他们返回一个副本。 + +> 这确实是一种混合方法：就像在 **OOP 设计**中一样，方法与数据一起封装在类中， +> 但作为典型的 **FP 设计**，方法被实现为纯函数，该函数不改变数据 + +#### 例子 + +使用这种方法，您可以在样例类中直接实现披萨上的功能： + +{% tabs module_5 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) { + + // the operations on the data model + def price: Double = + pizzaPrice(this) // implementation from above + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +} +``` + +{% endtab %} +{% tab 'Scala 3' for=module_5 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +): + + // the operations on the data model + def price: Double = + pizzaPrice(this) // implementation from above + + def addTopping(t: Topping): Pizza = + this.copy(toppings = this.toppings :+ t) + + def removeAllToppings: Pizza = + this.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + this.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + this.copy(crustType = ct) +``` + +{% endtab %} +{% endtabs %} + +请注意，与之前的方法不同，因为这些是 `Pizza` 类上的方法，它们不会将 `Pizza` 引用作为输入参数。 +相反，他们用 `this` 作为当前披萨实例的引用。 + +现在你可以像这样使用这个新设计： + +{% tabs module_6 %} +{% tab 'Scala 2 and 3' for=module_6 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +### 扩展方法 + +最后，我们展示了一种介于第一个（在伴生对象中定义函数）和最后一个（将函数定义为类型本身的方法）之间的方法。 + +扩展方法让我们创建一个类似于函数对象的 API，而不必将函数定义为类型本身的方法。 +这可以有多个优点： + +- 我们的数据模型再次_非常简洁_并且没有提及任何行为。 +- 我们可以_追溯性地_为类型配备额外的方法，而无需更改原始定义。 +- 除了伴生对象或类型上的直接方法外，扩展方法可以在_外部_另一个文件中定义。 + +让我们再次回顾一下我们的例子。 + +{% tabs module_7 class=tabs-scala-version %} +{% tab 'Scala 2' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +implicit class PizzaOps(p: Pizza) { + def price: Double = + pizzaPrice(p) // implementation from above + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +} +``` +在上面的代码中，我们将披萨上的不同方法定义为_implicit class_。 +用 `implicit class PizzaOps(p: Pizza)`，不管什么时候导入 `PizzaOps`，它的方法在 `Pizza` 的实例上都是可用的。 +在本例中接收者是 `p`。 + +{% endtab %} +{% tab 'Scala 3' for=module_7 %} + +```scala +case class Pizza( + crustSize: CrustSize, + crustType: CrustType, + toppings: Seq[Topping] +) + +extension (p: Pizza) + def price: Double = + pizzaPrice(p) // implementation from above + + def addTopping(t: Topping): Pizza = + p.copy(toppings = p.toppings :+ t) + + def removeAllToppings: Pizza = + p.copy(toppings = Seq.empty) + + def updateCrustSize(cs: CrustSize): Pizza = + p.copy(crustSize = cs) + + def updateCrustType(ct: CrustType): Pizza = + p.copy(crustType = ct) +``` +在上面的代码中，我们将披萨上的不同方法定义为_扩展方法_。 +对于 `extension (p: Pizza)`，我们想在 `Pizza` 的实例上让方法可用。在本例中接收者是 `p`。 + +{% endtab %} +{% endtabs %} + +使用扩展方法，我们可以获得和之前一样的 API： + +{% tabs module_8 %} +{% tab 'Scala 2 and 3' for=module_8 %} + +```scala +Pizza(Small, Thin, Seq(Cheese)) + .addTopping(Pepperoni) + .updateCrustType(Thick) + .price +``` + +{% endtab %} +{% endtabs %} + +通常，如果您是数据模型的设计者，您将在伴生对象中定义您的扩展方法。 +这样，它们已经可供所有用户使用。 +否则，扩展方法需要显式导入才能使用。 + +## 这种方法的总结 + +在 Scala/FP 中定义数据模型往往很简单：只需使用枚举对数据的变体进行建模，并使用 样例类对复合数据进行建模。 +然后，为了对行为建模，定义对数据模型的值进行操作的函数。 +我们已经看到了组织函数的不同方法： + +- 你可以把你的方法放在伴生对象中 +- 您可以使用模块化编程风格，分离接口和实现 +- 您可以使用“函数对象”方法并将方法存储在定义的数据类型上 +- 您可以使用扩展方法把函数装配到数据模型上 + +[adts]: {% link _zh-cn/overviews/scala3-book/types-adts-gadts.md %} +[modeling-tools]: {% link _zh-cn/overviews/scala3-book/domain-modeling-tools.md %} diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-intro.md b/_zh-cn/overviews/scala3-book/domain-modeling-intro.md new file mode 100644 index 0000000000..f2d91f71a3 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-intro.md @@ -0,0 +1,18 @@ +--- +title: 领域建模 +description: This chapter provides an introduction to domain modeling in Scala 3. +num: 20 +previous-page: control-structures +next-page: domain-modeling-tools + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +本章介绍如何使用 Scala 3 对周围的世界进行建模： + +- 工具部分介绍了可供您使用的工具，包括类、traits 、枚举等 +- OOP 建模部分着眼于面向对象编程 （OOP） 风格中的建模属性和行为 +- FP 建模部分以函数式编程 （FP） 风格来看领域建模 diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-oop.md b/_zh-cn/overviews/scala3-book/domain-modeling-oop.md new file mode 100644 index 0000000000..0c71a3f65c --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-oop.md @@ -0,0 +1,588 @@ +--- +title: OOP 领域建模 +type: section +description: This chapter provides an introduction to OOP domain modeling with Scala 3. +language: zh-cn +num: 22 +previous-page: domain-modeling-tools +next-page: domain-modeling-fp + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +本章介绍了在 Scala 3 中使用面向对象编程 (OOP) 进行领域建模。 + +## 介绍 + +Scala 为面向对象设计提供了所有必要的工具： + +- **Traits** 让您指定（抽象）接口以及具体实现。 +- **Mixin Composition** 为您提供了从较小的部分组成组件的工具。 +- **类**可以实现trait指定的接口。 +- 类的**实例**可以有自己的私有状态。 +- **Subtyping** 允许您在需要超类实例的地方使用一个类的实例。 +- **访问修饰符**允许您控制类的哪些成员可以被代码的哪个部分访问。 + +## Traits + +可能与支持 OOP 的其他语言（例如 Java）不同，Scala 中分解的主要工具不是类，而是trait。 +它们可以用来描述抽象接口，例如： + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String +``` + +{% endtab %} +{% endtabs %} + +并且还可以包含具体的实现： + +{% tabs traits_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Showable { + def show: String + def showHtml = "
" + show + "
" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Showable: + def show: String + def showHtml = "" + show + "
" +``` + +{% endtab %} +{% endtabs %} + +你可以看到我们用抽象方法 `show` 来定义方法 `showHtml`。 + +[Odersky and Zenger][scalable] 展示了 _面向服务的组件模型_ 和视图： + +- **抽象成员**作为_必须_服务：它们仍然需要由子类实现。 +- **具体成员**作为_提供_服务：它们被提供给子类。 + +我们已经可以在 `Showable` 的示例中看到这一点：定义一个扩展 `Showable` 的类 `Document`，我们仍然必须定义 `show`，但我们提供了 `showHtml`： + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Document(text: String) extends Showable { + def show = text +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Document(text: String) extends Showable: + def show = text +``` + +{% endtab %} +{% endtabs %} + +#### 抽象成员 + +抽象方法并不是trait中唯一可以抽象的东西。 +一个trait可以包含： + +- 抽象方法（`def m(): T`） +- 抽象值定义（`val x: T`） +- 抽象类型成员（`type T`），可能有界限（`type T <: S`） +- 抽象given（`given t: T`） +Scala 3 only + +上述每个特性都可用于指定对 trait 实现者的某种形式的要求。 + +## 混入组合 + +traits 不仅可以包含抽象和具体的定义，Scala 还提供了一种组合多个 trait 的强大方法：这个特性通常被称为 _混入组合_。 + +让我们假设以下两个（可能独立定义的）traits： + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait GreetingService { + def translate(text: String): String + def sayHello = translate("Hello") +} + +trait TranslationService { + def translate(text: String): String = "..." +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait GreetingService: + def translate(text: String): String + def sayHello = translate("Hello") + +trait TranslationService: + def translate(text: String): String = "..." +``` + +{% endtab %} +{% endtabs %} + +要组合这两个服务，我们可以简单地创建一个扩展它们的新trait： + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait ComposedService extends GreetingService with TranslationService +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait ComposedService extends GreetingService, TranslationService +``` + +{% endtab %} +{% endtabs %} + +一个 trait 中的抽象成员（例如 `GreetingService` 中的 `translate`）会自动与另一个 trait 中的具体成员匹配。 +这不仅适用于本例中的方法，而且适用于上述所有其他抽象成员（即类型、值定义等）。 + +## 类 + +Traits 非常适合模块化组件和描述接口（必需和提供）。 +但在某些时候，我们会想要创建它们的实例。 +在 Scala 中设计软件时，只考虑在继承模型的叶子中使用类通常很有帮助： + +{% comment %} +NOTE: I think “leaves” may technically be the correct word to use, but I prefer “leafs.” +{% endcomment %} + +{% tabs table-traits-cls-summary class=tabs-scala-version %} +{% tab 'Scala 2' %} +| Traits | `T1`, `T2`, `T3` +| 组合traits | `S1 extends T1 with T2`, `S2 extends T2 with T3` +| 类 | `C extends S1 with T3` +| 实例 | `new C()` +{% endtab %} +{% tab 'Scala 3' %} +| Traits | `T1`, `T2`, `T3` +| 组合 traits | `S extends T1, T2`, `S extends T2, T3` +| 类 | `C extends S, T3` +| 实例 | `C()` +{% endtab %} +{% endtabs %} + +在 Scala 3 中更是如此，trait 现在也可以接受参数，进一步消除了对类的需求。 + +#### 定义类 + +像trait一样，类可以扩展多个trait（但只有一个超类）： + +{% tabs class_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class MyService(name: String) extends ComposedService with Showable { + def show = s"$name says $sayHello" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class MyService(name: String) extends ComposedService, Showable: + def show = s"$name says $sayHello" +``` + +{% endtab %} +{% endtabs %} + +#### 子类型化 + +我们可以创建一个 `MyService` 的实例，如下所示： + +{% tabs class_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1: MyService = new MyService("Service 1") +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s1: MyService = MyService("Service 1") +``` + +{% endtab %} +{% endtabs %} + +通过子类型化的方式，我们的实例 `s1` 可以在任何扩展了trait的地方使用： + +{% tabs class_3 %} +{% tab 'Scala 2 and 3' %} + +```scala +val s2: GreetingService = s1 +val s3: TranslationService = s1 +val s4: Showable = s1 +// ... and so on ... +``` + +{% endtab %} +{% endtabs %} + +#### 扩展规划 + +如前所述，可以扩展另一个类： + +{% tabs class_4 %} +{% tab 'Scala 2 and 3' %} + +```scala +class Person(name: String) +class SoftwareDeveloper(name: String, favoriteLang: String) + extends Person(name) +``` + +{% endtab %} +{% endtabs %} + +然而，由于 _traits_ 被设计为主要的分解手段，在一个文件中定义的类_不能_在另一个文件中扩展。 +为了允许这样做，需要将基类标记为 `open`： + +{% tabs class_5 %} +{% tab 'Scala 3 Only' %} + +```scala +open class Person(name: String) +``` + +{% endtab %} +{% endtabs %} + +用 [`open`][open] 标记类是 Scala 3 的一个新特性。必须将类显式标记为开放可以避免面向对象设计中的许多常见缺陷。 +特别是，它要求库设计者明确计划扩展，例如用额外的扩展契约来记录那些被标记为开放的类。 + +{% comment %} +NOTE/FWIW: In his book, “Effective Java,” Joshua Bloch describes this as “Item 19: Design and document for inheritance or else prohibit it.” +Unfortunately I can’t find any good links to this on the internet. +I only mention this because I think that book and phrase is pretty well known in the Java world. +{% endcomment %} + +## 实例和私有可变状态 + +与其他支持 OOP 的语言一样，Scala 中的trait和类可以定义可变字段： + +{% tabs instance_6 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Counter { + // can only be observed by the method `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Counter: + // can only be observed by the method `count` + private var currentCount = 0 + + def tick(): Unit = currentCount += 1 + def count: Int = currentCount +``` + +{% endtab %} +{% endtabs %} + +`Counter` 类的每个实例都有自己的私有状态，只能通过方法 `count` 观察到，如下面的交互所示： + +{% tabs instance_7 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val c1 = new Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val c1 = Counter() +c1.count // 0 +c1.tick() +c1.tick() +c1.count // 2 +``` + +{% endtab %} +{% endtabs %} + +#### 访问修饰符 + +默认情况下，Scala 中的所有成员定义都是公开可见的。 +要隐藏实现细节，可以将成员（方法、字段、类型等）定义为 `private` 或 `protected`。 +通过这种方式，您可以控制访问或覆盖它们的方式。 +私有成员仅对类/trait本身及其伴生对象可见。 +受保护的成员对类的子类也是可见的。 + +## 高级示例：面向服务的设计 + +在下文中，我们展示了 Scala 的一些高级特性，并展示了如何使用它们来构建更大的软件组件。 +这些示例改编自 Martin Odersky 和 Matthias Zenger 的论文 ["Scalable Component Abstractions"][scalable]。 +如果您不了解示例的所有细节，请不要担心；它的主要目的是演示如何使用多种类型特性来构造更大的组件。 + +我们的目标是定义一个_种类丰富_的软件组件，而对组件的细化，可以放到以后的实现中 +具体来说，以下代码将组件 `SubjectObserver` 定义为具有两个抽象类型成员的trait， `S` （用于主题）和 `O` （用于观察者）： + +{% tabs example_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait SubjectObserver { + + type S <: Subject + type O <: Observer + + trait Subject { self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = { + observers = obs :: observers + } + def publish() = { + for ( obs <- observers ) obs.notify(this) + } + } + + trait Observer { + def notify(sub: S): Unit + } +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait SubjectObserver: + + type S <: Subject + type O <: Observer + + trait Subject: + self: S => + private var observers: List[O] = List() + def subscribe(obs: O): Unit = + observers = obs :: observers + def publish() = + for obs <- observers do obs.notify(this) + + trait Observer: + def notify(sub: S): Unit +``` + +{% endtab %} +{% endtabs %} + +有几件事需要解释。 + +#### 抽象类型成员 + +声明 `type S <: Subject` 表示在 trait `SubjectObserver` 中我们可以引用一些我们称为 `S` 的_未知_（即抽象）类型。 +然而，该类型并不是完全未知的：我们至少知道它是trait `Subject` 的_某个子类型_。 +只要选择的类型是 `Subject` 的子类型，所有扩展自 `SubjectObserver` 的trait和类都可以自由地用于 `S`的类型。 +声明的 `<: Subject` 部分也称为 _`S` 的上界_。 + +#### 嵌套trait + +在 trait `SubjectObserver` _内_，我们定义了另外两个traits。 +让我们从 trait `Observer` 开始，它只定义了一个抽象方法 `notify`，它接受一个类型为 `S` 的参数。 +正如我们稍后将看到的，重要的是参数的类型为 `S` 而不是 `Subject` 类型。 + +第二个trait，`Subject`，定义了一个私有字段`observers`来存储所有订阅这个特定主题的观察者。 +订阅主题只是将对象存储到此列表中。 +同样，参数 `obs` 的类型是 `O`，而不是 `Observer`。 + +#### 自类型注解 + +最后，你可能想知道 trait `Subject` 上的 `self: S =>` 应该是什么意思。 +这称为 _自类型注解_。 +它要求 `Subject` 的子类型也是 `S` 的子类型。 +这对于能够使用 `this` 作为参数调用 `obs.notify` 是必要的，因为它需要 `S` 类型的值。 +如果 `S` 是一个_具体_类型，自类型注解可以被 `trait Subject extends S` 代替。 + +### 实现组件 + +我们现在可以实现上述组件并将抽象类型成员定义为具体类型： + +{% tabs example_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object SensorReader extends SubjectObserver { + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject { + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = { + currentValue = v + publish() + } + } + + class Display extends Observer { + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") + } +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object SensorReader extends SubjectObserver: + type S = Sensor + type O = Display + + class Sensor(val label: String) extends Subject: + private var currentValue = 0.0 + def value = currentValue + def changeValue(v: Double) = + currentValue = v + publish() + + class Display extends Observer: + def notify(sub: Sensor) = + println(s"${sub.label} has value ${sub.value}") +``` + +{% endtab %} +{% endtabs %} + +具体来说，我们定义了一个扩展 `SubjectObserver` 的_单例_对象 `SensorReader`。 +在 `SensorReader` 的实现中，我们说 `S` 类型现在被定义为 `Sensor` 类型，`O` 类型被定义为等于 `Display` 类型。 +`Sensor` 和 `Display` 都被定义为 `SensorReader` 中的嵌套类，相应地实现了 `Subject` 和 `Observer` 特性。 + +除了作为面向服务设计的示例之外，这段代码还突出了面向对象编程的许多方面： + +- `Sensor` 类引入了它自己的私有状态（`currentValue`），并在方法`changeValue` 后面封装了对状态的修改。 +- `changeValue` 的实现使用扩展trait中定义的方法 `publish`。 +- 类 `Display` 扩展了 `Observer` 特性，并实现了缺失的方法 `notify`。 + +{% comment %} +NOTE: You might say “the abstract method `notify`” in that last sentence, but I like “missing.” +{% endcomment %} + +有一点很重要，需要指出，`notify` 的实现只能安全地访问 `sub` 的标签和值，因为我们最初将参数声明为 `S` 类型。 + +### 使用组件 + +最后，下面的代码说明了如何使用我们的 `SensorReader` 组件： + +{% tabs example_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import SensorReader._ + +// setting up a network +val s1 = new Sensor("sensor1") +val s2 = new Sensor("sensor2") +val d1 = new Display() +val d2 = new Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// propagating updates through the network +s1.changeValue(2) +s2.changeValue(3) + +// prints: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 + +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import SensorReader.* + +// setting up a network +val s1 = Sensor("sensor1") +val s2 = Sensor("sensor2") +val d1 = Display() +val d2 = Display() +s1.subscribe(d1) +s1.subscribe(d2) +s2.subscribe(d1) + +// propagating updates through the network +s1.changeValue(2) +s2.changeValue(3) + +// prints: +// sensor1 has value 2.0 +// sensor1 has value 2.0 +// sensor2 has value 3.0 +``` + +{% endtab %} +{% endtabs %} + +借助我们掌握的所有面向对象的编程工具，在下一节中，我们将演示如何以函数式风格设计程序。 + +{% comment %} +NOTE: One thing I occasionally do is flip things like this around, so I first show how to use a component, and then show how to implement that component. I don’t have a rule of thumb about when to do this, but sometimes it’s motivational to see the use first, and then see how to create the code to make that work. +{% endcomment %} + +[scalable]: https://doi.org/10.1145/1094811.1094815 +[open]: {{ site.scala3ref }}/other-new-features/open-classes.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_zh-cn/overviews/scala3-book/domain-modeling-tools.md b/_zh-cn/overviews/scala3-book/domain-modeling-tools.md new file mode 100644 index 0000000000..08aa972f0a --- /dev/null +++ b/_zh-cn/overviews/scala3-book/domain-modeling-tools.md @@ -0,0 +1,1345 @@ +--- +title: 工具 +type: section +description: This chapter provides an introduction to the available domain modeling tools in Scala 3, including classes, traits, enums, and more. +language: zh-cn +num: 21 +previous-page: domain-modeling-intro +next-page: domain-modeling-oop + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +Scala 3提供了许多不同的结构，因此我们可以对周围的世界进行建模： + +- 类 +- 对象 +- 伴生对象 +- Traits +- 抽象类 +- 枚举 +Scala 3 独有 +- 样例类 +- 样例对象 + +本节简要介绍其中的每种语言功能。 + +## 类 + +与其他语言一样，Scala中的_类_是用于创建对象实例的模板。 +下面是一些类的示例： + +{% tabs class_1 %} +{% tab 'Scala 2 and 3' %} + +```scala +class Person(var name: String, var vocation: String) +class Book(var title: String, var author: String, var year: Int) +class Movie(var name: String, var director: String, var year: Int) +``` + +{% endtab %} +{% endtabs %} + +这些例子表明，Scala有一种非常轻量级的方式来声明类。 + +我们的示例类的所有参数都定义为 `var` 字段，这意味着它们是可变的：您可以读取它们，也可以修改它们。 +如果您希望它们是不可变的---仅读取---请改为将它们创建为 `val` 字段，或者使用样例类。 + +在Scala 3之前，您使用 `new` 关键字来创建类的新实例： + +{% tabs class_2 %} +{% tab 'Scala 2 Only' %} + +```scala +val p = new Person("Robert Allen Zimmerman", "Harmonica Player") +// --- +``` + +{% endtab %} +{% endtabs %} + +然而，通过[通用 apply 方法][creator]，在 Scala 3 里面不要求使用 `new`： +Scala 3 独有 + +{% tabs class_3 %} +{% tab 'Scala 3 Only' %} + +```scala +val p = Person("Robert Allen Zimmerman", "Harmonica Player") +``` + +{% endtab %} +{% endtabs %} + +一旦你有了一个类的实例，比如 `p`，你就可以访问它的字段，在此示例中，这些字段都是构造函数的参数： + +{% tabs class_4 %} +{% tab 'Scala 2 and 3' %} + +```scala +p.name // "Robert Allen Zimmerman" +p.vocation // "Harmonica Player" +``` + +{% endtab %} +{% endtabs %} + +如前所述，所有这些参数都是作为 `var` 字段创建的，因此您也可以更改它们： + +{% tabs class_5 %} +{% tab 'Scala 2 and 3' %} + +```scala +p.name = "Bob Dylan" +p.vocation = "Musician" +``` + +{% endtab %} +{% endtabs %} + +### 字段和方法 + +类还可以具有不属于构造函数的方法和其他字段。 +它们在类的主体中定义。 +主体初始化为默认构造函数的一部分： + +{% tabs method class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person(var firstName: String, var lastName: String) { + + println("initialization begins") + val fullName = firstName + " " + lastName + + // a class method + def printFullName: Unit = + // access the `fullName` field, which is created above + println(fullName) + + printFullName + println("initialization ends") +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Person(var firstName: String, var lastName: String): + + println("initialization begins") + val fullName = firstName + " " + lastName + + // a class method + def printFullName: Unit = + // access the `fullName` field, which is created above + println(fullName) + + printFullName + println("initialization ends") +``` + +{% endtab %} +{% endtabs %} + +以下 REPL 会话演示如何使用这个类创建新的 `Person` 实例： + +{% tabs demo-person class=tabs-scala-version %} +{% tab 'Scala 2' %} +```` +scala> val john = new Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` +{% endtab %} +{% tab 'Scala 3' %} + +```` +scala> val john = Person("John", "Doe") +initialization begins +John Doe +initialization ends +val john: Person = Person@55d8f6bb + +scala> john.printFullName +John Doe +```` + +{% endtab %} +{% endtabs %} + +类还可以扩展 traits和抽象类，我们将在下面专门部分中介绍这些内容。 + +### 默认参数值 + +快速浏览一下其他功能，类构造函数参数也可以具有默认值： + +{% tabs default-values_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000) { + override def toString = s"timeout: $timeout, linger: $linger" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Socket(val timeout: Int = 5_000, val linger: Int = 5_000): + override def toString = s"timeout: $timeout, linger: $linger" +``` + +{% endtab %} +{% endtabs %} + +此功能的一大优点是，它允许代码的使用者以各种不同的方式创建类，就好像该类有别的构造函数一样： + +{% tabs default-values_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s = new Socket() // timeout: 5000, linger: 5000 +val s = new Socket(2_500) // timeout: 2500, linger: 5000 +val s = new Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = new Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = new Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s = Socket() // timeout: 5000, linger: 5000 +val s = Socket(2_500) // timeout: 2500, linger: 5000 +val s = Socket(10_000, 10_000) // timeout: 10000, linger: 10000 +val s = Socket(timeout = 10_000) // timeout: 10000, linger: 5000 +val s = Socket(linger = 10_000) // timeout: 5000, linger: 10000 +``` + +{% endtab %} +{% endtabs %} + +创建类的新实例时，还可以使用命名参数。 +当许多参数具有相同的类型时，这特别有用，如以下比较所示： + +{% tabs default-values_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// option 1 +val s = new Socket(10_000, 10_000) + +// option 2 +val s = new Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// option 1 +val s = Socket(10_000, 10_000) + +// option 2 +val s = Socket( + timeout = 10_000, + linger = 10_000 +) +``` + +{% endtab %} +{% endtabs %} + +### 辅助构造函数 + +可以为类定义多个构造函数，以便类的使用者用不同的方式来生成这个类。 +例如，假设您需要编写一些代码给大学招生系统中的学生进行建模。 +在分析需求时，您已经看到您需要能够以三种方式构建 `Student` 实例： + +- 当他们第一次开始招生过程时，带有姓名和政府 ID， +- 当他们提交申请时，带有姓名，政府 ID 和额外的申请日期 +- 在他们被录取后，带有姓名，政府 ID 和学生证 + +在 OOP 风格中处理这种情况的一种方法是使用以下代码： + +{% tabs structor_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import java.time._ + +// [1] the primary constructor +class Student( + var name: String, + var govtId: String +) { + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] a constructor for when the student has completed + // their application + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = { + this(name, govtId) + _applicationDate = Some(applicationDate) + } + + // [3] a constructor for when the student is approved + // and now has a student id + def this( + name: String, + govtId: String, + studentId: Int + ) = { + this(name, govtId) + _studentId = studentId + } +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import java.time.* + +// [1] the primary constructor +class Student( + var name: String, + var govtId: String +): + private var _applicationDate: Option[LocalDate] = None + private var _studentId: Int = 0 + + // [2] a constructor for when the student has completed + // their application + def this( + name: String, + govtId: String, + applicationDate: LocalDate + ) = + this(name, govtId) + _applicationDate = Some(applicationDate) + + // [3] a constructor for when the student is approved + // and now has a student id + def this( + name: String, + govtId: String, + studentId: Int + ) = + this(name, govtId) + _studentId = studentId +``` + +{% endtab %} +{% endtabs %} + +{% comment %} +// for testing that code +override def toString = s""" +|Name: $name +|GovtId: $govtId +|StudentId: $_studentId +|Date Applied: $_applicationDate +""".trim.stripMargin +{% endcomment %} + +该类有三个构造函数，由代码中编号的注释给出： + +1. 主构造函数，由类定义中的 `name` 和 `govtId` 给出 +2. 具有参数 `name` 、 `govtId` 和 `applicationDate` 的辅助构造函数 +3. 另一个带有参数 `name` 、 `govtId` 和 `studentId` 的辅助构造函数 + +这些构造函数可以这样调用： + +{% tabs structor_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s1 = new Student("Mary", "123") +val s2 = new Student("Mary", "123", LocalDate.now) +val s3 = new Student("Mary", "123", 456) +``` + +{% endtab %} + +{% tab 'Scala 3' %} + +```scala +val s1 = Student("Mary", "123") +val s2 = Student("Mary", "123", LocalDate.now) +val s3 = Student("Mary", "123", 456) +``` + +{% endtab %} +{% endtabs %} + +虽然可以使用此技术，但请记住，构造函数参数也可以具有默认值，这使得一个类看起来具有多个构造函数。 +这在前面的 `Socket` 示例中所示。 + +## 对象 + +对象是一个正好有一个实例的类。 +当其成员是引用类时，它会延迟初始化，类似于 `lazy val` 。 +Scala 中的对象允许在一个命名空间下对方法和字段进行分组，类似于我们在 Java，Javascript（ES6）中使用 `static` 方法或在 Python 中使用 `@staticmethod` 方法。 + +声明 `object` 类似于声明 `class` 。 +下面是一个“字符串实用程序”对象的示例，其中包含一组用于处理字符串的方法： + +{% tabs object_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object StringUtils { + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object StringUtils: + def truncate(s: String, length: Int): String = s.take(length) + def containsWhitespace(s: String): Boolean = s.matches(".*\\s.*") + def isNullOrEmpty(s: String): Boolean = s == null || s.trim.isEmpty +``` + +{% endtab %} +{% endtabs %} + +我们可以这样使用对象： + +{% tabs object_2 %} +{% tab 'Scala 2 and 3' %} + +```scala +StringUtils.truncate("Chuck Bartowski", 5) // "Chuck" +``` + +{% endtab %} +{% endtabs %} + +在 Scala 中导入非常灵活，并允许我们导入对象的_所有_ 成员： + +{% tabs object_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import StringUtils._ +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import StringUtils.* +truncate("Chuck Bartowski", 5) // "Chuck" +containsWhitespace("Sarah Walker") // true +isNullOrEmpty("John Casey") // false +``` + +{% endtab %} +{% endtabs %} + +或者只是 _部分_ 成员： + +{% tabs object_4 %} +{% tab 'Scala 2 and 3' %} + +```scala +import StringUtils.{truncate, containsWhitespace} +truncate("Charles Carmichael", 7) // "Charles" +containsWhitespace("Captain Awesome") // true +isNullOrEmpty("Morgan Grimes") // Not found: isNullOrEmpty (error) +``` + +{% endtab %} +{% endtabs %} + +对象还可以包含字段，这些字段也可以像静态成员一样访问： + +{% tabs object_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +object MathConstants { + val PI = 3.14159 + val E = 2.71828 +} + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +object MathConstants: + val PI = 3.14159 + val E = 2.71828 + +println(MathConstants.PI) // 3.14159 +``` + +{% endtab %} +{% endtabs %} + +## 伴生对象 + +与类同名且在与类在相同的文件中声明的 `object` 称为_“伴生对象”_。 +同样，相应的类称为对象的伴生类。 +伴生类或对象可以访问其伴生的私有成员。 + +伴生对象用于不特定于伴生类实例的方法和值。 +例如，在下面的示例中，类 `Circle` 具有一个名为 `area` 的成员，该成员特定于每个实例，其伴生对象具有一个名为 `calculateArea` 的方法，该方法(a)不特定于实例，并且(b)可用于每个实例： + +{% tabs companion class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +import scala.math._ + +class Circle(val radius: Double) { + def area: Double = Circle.calculateArea(radius) +} + +object Circle { + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) +} + +val circle1 = new Circle(5.0) +circle1.area +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +import scala.math.* + +case class Circle(radius: Double): + def area: Double = Circle.calculateArea(radius) + +object Circle: + private def calculateArea(radius: Double): Double = Pi * pow(radius, 2.0) + +val circle1 = Circle(5.0) +circle1.area +``` + +{% endtab %} +{% endtabs %} + +在此示例中，每个实例可用的 `area` 方法使用伴生对象中定义的 `calculateArea` 方法。 +再一次， `calculateArea` 类似于Java中的静态方法。 +此外，由于 `calculateArea` 是私有的，因此其他代码无法访问它，但如图所示，它可以被 `Circle` 类的实例看到。 + +### 其他用途 + +伴生对象可用于多种用途： + +- 如图所示，它们可用于将“静态”方法分组到命名空间下 + - 这些方法可以是公共的，也可以是私有的 + - 如果 `calculateArea` 是公开的，它将被访问为 `Circle.calculateArea` +- 它们可以包含 `apply` 方法，这些方法---感谢一些语法糖---作为工厂方法来构建新实例 +- 它们可以包含 `unapply` 方法，用于解构对象，例如模式匹配 + +下面快速了解如何将 `apply` 方法当作工厂方法来创建新对象： + +{% tabs companion-use class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person { + var name = "" + var age = 0 + override def toString = s"$name is $age years old" +} + +object Person { + // a one-arg factory method + def apply(name: String): Person = { + var p = new Person + p.name = name + p + } + + // a two-arg factory method + def apply(name: String, age: Int): Person = { + var p = new Person + p.name = name + p.age = age + p + } +} + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +此处不涉及 `unapply` 方法，但在[语言规范](https://scala-lang.org/files/archive/spec/2.13/08-pattern-matching.html#extractor-patterns)中对此进行了介绍。 + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Person: + var name = "" + var age = 0 + override def toString = s"$name is $age years old" + +object Person: + + // a one-arg factory method + def apply(name: String): Person = + var p = new Person + p.name = name + p + + // a two-arg factory method + def apply(name: String, age: Int): Person = + var p = new Person + p.name = name + p.age = age + p + +end Person + +val joe = Person("Joe") +val fred = Person("Fred", 29) + +//val joe: Person = Joe is 0 years old +//val fred: Person = Fred is 29 years old +``` + +{% endtab %} +{% endtabs %} + +此处不涉及 `unapply` 方法，但在 [参考文档][unapply] 中对此进行了介绍。 + +## Traits + +如果你熟悉Java，Scala trait 类似于Java 8+中的接口。Traits 可以包含： + +- 抽象方法和成员 +- 具体方法和成员 + +在基本用法中，trait 可以用作接口，仅定义将由其他类实现的抽象成员： + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Employee { + def id: Int + def firstName: String + def lastName: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Employee: + def id: Int + def firstName: String + def lastName: String +``` + +{% endtab %} +{% endtabs %} + +但是，traits 也可以包含具体成员。 +例如，以下 traits定义了两个抽象成员---`numLegs` 和 `walk()`---并且还具有`stop()`方法的具体实现： + +{% tabs traits_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Employee { + def id: Int + def firstName: String + def lastName: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait HasLegs: + def numLegs: Int + def walk(): Unit + def stop() = println("Stopped walking") +``` + +{% endtab %} +{% endtabs %} + +下面是另一个具有抽象成员和两个具体实现的 trait： + +{% tabs traits_3 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait HasTail { + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait HasTail: + def tailColor: String + def wagTail() = println("Tail is wagging") + def stopTail() = println("Tail is stopped") +``` + +{% endtab %} +{% endtabs %} + +请注意，每个 trait 只处理非常特定的属性和行为：`HasLegs` 只处理腿，而 `HasTail` 只处理与尾部相关的功能。 +Traits可以让你构建这样的小模块。 + +在代码的后面部分，类可以混合多个 traits 来构建更大的组件： + +{% tabs traits_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class IrishSetter(name: String) extends HasLegs with HasTail { + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class IrishSetter(name: String) extends HasLegs, HasTail: + val numLegs = 4 + val tailColor = "Red" + def walk() = println("I’m walking") + override def toString = s"$name is a Dog" +``` + +{% endtab %} +{% endtabs %} + +请注意，`IrishSetter` 类实现了在 `HasLegs` 和 `HasTail` 中定义的抽象成员。 +现在，您可以创建新的 `IrishSetter` 实例： + +{% tabs traits_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val d = new IrishSetter("Big Red") // "Big Red is a Dog" +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val d = IrishSetter（“Big Red”） // “Big Red is a Dog” +``` + +{% endtab %} +{% endtabs %} + +这只是你对 trait 可以完成的事情的一种体验。 +有关更多详细信息，请参阅这些建模课程的其余部分。 + +## 抽象类 + +{% comment %} +LATER: If anyone wants to update this section, our comments about abstract classes and traits are on Slack. The biggest points seem to be: +- The `super` of a trait is dynamic +- At the use site, people can mix in traits but not classes +- It remains easier to extend a class than a trait from Java, if the trait has at least a field +- Similarly, in Scala.js, a class can be imported from or exported to JavaScript. A trait cannot +- There are also some point that unrelated classes can’t be mixed together, and this can be a modeling advantage +{% endcomment %} + +当你想写一个类，但你知道它将有抽象成员时，你可以创建一个 trait 或一个抽象类。 +在大多数情况下，你会使用 trait，但从历史上看，有两种情况，使用抽象类比使用 trait 更好： + +- 您想要创建一个使用构造函数参数的基类 +- 代码将从 Java 代码调用 + +### 使用构造函数参数的基类 + +在 Scala 3 之前，当基类需要使用构造函数参数时，你可以将其声明为 `abstract class`： + +{% tabs abstract_1 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +abstract class Pet(name: String) { + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" +} + +class Dog(name: String, var age: Int) extends Pet(name) { + val greeting = "Woof" +} + +val d = new Dog("Fido", 1) +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +abstract class Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +Trait 参数 Scala 3 独有
+ +但是，在 Scala 3 中，trait 现在可以具有[参数][trait-params]，因此您现在可以在相同情况下使用 trait： + +{% tabs abstract_2 %} +{% tab 'Scala 3 Only' %} + +```scala +trait Pet(name: String): + def greeting: String + def age: Int + override def toString = s"My name is $name, I say $greeting, and I’m $age" + +class Dog(name: String, var age: Int) extends Pet(name): + val greeting = "Woof" + +val d = Dog("Fido", 1) +``` + +{% endtab %} +{% endtabs %} + +trait 的组成更加灵活---您可以混合多个 trait，但只能扩展一个类---并且大多数时候应该优先于类和抽象类。 +经验法则是，每当要创建特定类型的实例时，就使用类；如果要分解和重用行为时，应使用trait。 + +枚举Scala 3 独有
+ +枚举可用于定义由一组有限的命名值组成的类型（在[FP建模][fp-modeling]一节中，我们将看到枚举比这更灵活）。 +基本枚举用于定义常量集，如一年中的月份、一周中的天数、北/南/东/西方向等。 + +例如，这些枚举定义了与披萨饼相关的属性集： + +{% tabs enum_1 %} +{% tab 'Scala 3 Only' %} + + +```scala +enum CrustSize: + case Small, Medium, Large + +enum CrustType: + case Thin, Thick, Regular + +enum Topping: + case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions +``` + +{% endtab %} +{% endtabs %} + +若要在其他代码中使用它们，请先导入它们，然后使用它们： + +{% tabs enum_2 %} +{% tab 'Scala 3 Only' %} + +```scala +import CrustSize.* +val currentCrustSize = Small +``` + +{% endtab %} +{% endtabs %} + +枚举值可以使用等于 （`==`） 进行比较，也可以用匹配的方式： + +{% tabs enum_3 %} +{% tab 'Scala 3 Only' %} + +```scala +// if/then +if (currentCrustSize == Large) + println("You get a prize!") + +// match +currentCrustSize match + case Small => println("small") + case Medium => println("medium") + case Large => println("large") +``` + +{% endtab %} +{% endtabs %} + +### 更多枚举特性 + +枚举也可以参数化： + +{% tabs enum_4 %} +{% tab 'Scala 3 Only' %} + +```scala +enum Color(val rgb: Int): + case Red extends Color(0xFF0000) + case Green extends Color(0x00FF00) + case Blue extends Color(0x0000FF) +``` + +{% endtab %} +{% endtabs %} + +它们还可以具有成员（如字段和方法）： + +{% tabs enum_5 %} +{% tab 'Scala 3 Only' %} + +```scala +enum Planet(mass: Double, radius: Double): + private final val G = 6.67300E-11 + def surfaceGravity = G * mass / (radius * radius) + def surfaceWeight(otherMass: Double) = + otherMass * surfaceGravity + + case Mercury extends Planet(3.303e+23, 2.4397e6) + case Earth extends Planet(5.976e+24, 6.37814e6) + // more planets here ... +``` + +{% endtab %} +{% endtabs %} + +### 与 Java 枚举的兼容性 + +如果要将 Scala 定义的枚举用作 Java 枚举，可以通过扩展类 `java.lang.Enum`（默认情况下导入）来实现，如下所示： + +{% tabs enum_6 %} +{% tab 'Scala 3 Only' %} + +```scala +enum Color extends Enum[Color] { case Red, Green, Blue } +``` + +{% endtab %} +{% endtabs %} + +类型参数来自 Java `enum` 定义，并且应与枚举的类型相同。 +在扩展时，无需向`java.lang.Enum`提供构造函数参数（如Java API文档中所定义的那样）---编译器会自动生成它们。 + +像这样定义 `Color` 之后，你可以像使用 Java 枚举一样使用它： + +```` +scala> Color.Red.compareTo（Color.Green） +val res0： Int = -1 +```` + +关于[代数数据类型][adts]和[参考文档][ref-enums]的部分更详细地介绍了枚举。 + +## 样例类 + +样例类用于对不可变数据结构进行建模。 +举个例子： + +{% tabs case-classes_1 %} +{% tab 'Scala 2 and 3' %} + +```scala +case class Person(name: String, relation: String) +``` + +{% endtab %} +{% endtabs %} + +由于我们将 `Person` 声明为样例类，因此默认情况下，字段 `name` 和 `relation` 是公共的和不可变的。 +我们可以创建 样例类的实例，如下所示： + +{% tabs case-classes_2 %} +{% tab 'Scala 2 and 3' %} + +```scala +val christina = Person("Christina", "niece") +``` + +{% endtab %} +{% endtabs %} + +请注意，这些字段不能发生更改： + +{% tabs case-classes_3 %} +{% tab 'Scala 2 and 3' %} + +```scala +christina.name = "Fred" // error: reassignment to val +``` + +{% endtab %} +{% endtabs %} + +由于 样例类的字段被假定为不可变的，因此 Scala 编译器可以为您生成许多有用的方法： + +* 生成一个 `unapply` 方法，该方法允许您对样例类执行模式匹配（即，`case Person（n， r） => ...`）。 +* 在类中生成一个 `copy` 方法，这对于创建实例的修改副本非常有用。 +* 生成使用结构相等的 `equals` 和 `hashCode` 方法，允许您在 `Map` 中使用样例类的实例。 +* 生成默认的 `toString` 方法，对调试很有帮助。 + +以下示例演示了这些附加功能： + +{% tabs case-classes_4 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +// Case classes can be used as patterns +christina match { + case Person(n, r) => println("name is " + n) +} + +// `equals` and `hashCode` methods generated for you +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// `toString` method +println(christina) // Person(Christina,niece) + +// built-in `copy` method +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// result: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) + +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +// Case classes can be used as patterns +christina match + case Person(n, r) => println("name is " + n) + +// `equals` and `hashCode` methods generated for you +val hannah = Person("Hannah", "niece") +christina == hannah // false + +// `toString` method +println(christina) // Person(Christina,niece) + +// built-in `copy` method +case class BaseballTeam(name: String, lastWorldSeriesWin: Int) +val cubs1908 = BaseballTeam("Chicago Cubs", 1908) +val cubs2016 = cubs1908.copy(lastWorldSeriesWin = 2016) +// result: +// cubs2016: BaseballTeam = BaseballTeam(Chicago Cubs,2016) +``` + +{% endtab %} +{% endtabs %} + +### 支持函数式编程 + +如前所述，样例类支持函数式编程 （FP）： + +- 在FP中，您尽量避免改变数据结构。 + 因此，构造函数字段默认为 `val` 是有道理的。 + 由于无法更改样例类的实例，因此可以轻松共享它们，而不必担心突变或争用条件。 +- 您可以使用 `copy` 方法作为模板来创建新的（可能已更改的）实例，而不是改变实例。 + 此过程可称为“复制时更新”。 +- 自动为您生成 `unapply` 方法，还允许以模式匹配的高级方式使用样例类。 + +{% comment %} +NOTE: We can use this following text, if desired. If it’s used, it needs to be updated a little bit. + +### 一种 `unapply` 的方法 + +样例类的一大优点是，它可以为您的类自动生成一个 `unapply` 方法，因此您不必编写一个方法。 + +为了证明这一点，假设你有这个 trait： + +{% tabs case-classes_5 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +trait Person { + def name: String +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +trait Person: + def name: String +``` + +{% endtab %} +{% endtabs %} + +然后，创建以下样例类以扩展该 trait： + +{% tabs case-classes_6 %} +{% tab 'Scala 2 and 3' %} + +```scala +case class Student(name: String, year: Int) extends Person +case class Teacher(name: String, specialty: String) extends Person +``` + +{% endtab %} +{% endtabs %} + +由于它们被定义为样例类---并且它们具有内置的 `unapply` 方法---因此您可以编写如下匹配表达式： + +{% tabs case-classes_7 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def getPrintableString(p: Person): String = p match { + case Student(name, year) => + s"$name is a student in Year $year." + case Teacher(name, whatTheyTeach) => + s"$name teaches $whatTheyTeach." +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def getPrintableString(p: Person): String = p match + case Student(name, year) => + s"$name is a student in Year $year." + case Teacher(name, whatTheyTeach) => + s"$name teaches $whatTheyTeach." +``` + +{% endtab %} +{% endtabs %} + +请注意 `case` 语句中的以下两种模式： + +{% tabs case-classes_8 %} +{% tab 'Scala 2 and 3' %} + +```scala +case Student(name, year) => +case Teacher(name, whatTheyTeach) => +``` + +{% endtab %} +{% endtabs %} + +这些模式之所以有效，是因为 `Student` 和 `Teacher` 被定义为具有 `unapply` 方法的样例类，其类型签名符合特定标准。 +从技术上讲，这些示例中显示的特定类型的模式匹配称为_结构模式匹配_。 + +> Scala 标准是， `unapply` 方法在包装在 `Option` 中的元组中返回 样例类构造函数字段。 +> 解决方案的“元组”部分在上一课中进行了演示。 + +要显示该代码的工作原理，请创建一个 `Student` 和 `Teacher` 的实例： + +{% tabs case-classes_9 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val s = new Student("Al", 1) +val t = new Teacher("Bob Donnan", "Mathematics") +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val s = Student("Al", 1) +val t = Teacher("Bob Donnan", "Mathematics") +``` + +{% endtab %} +{% endtabs %} + +接下来，这是当您使用这两个实例来调用 `getPrintableString` 时，REPL 中的输出如下所示： + +{% tabs case-classes_10 %} +{% tab 'Scala 2 and 3' %} + +```scala +scala> getPrintableString(s) +res0: String = Al is a student in Year 1. + +scala> getPrintableString(t) +res1: String = Bob Donnan teaches Mathematics. +``` + +{% endtab %} +{% endtabs %} + +>所有这些关于 `unapply` 方法和提取器的内容对于这样的入门书来说都有些先进，但是因为样例类是一个重要的FP主题，所以似乎最好涵盖它们，而不是跳过它们。 + +#### 将模式匹配添加到任何具有 unapply 的类型 + +Scala 的一个很好的特性是，你可以通过编写自己的 `unapply` 方法来向任何类型添加模式匹配。 +例如，此类在其伴生对象中定义了一个 `unapply` 方法： + +{% tabs case-classes_11 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +class Person(var name: String, var age: Int) +object Person { + def unapply(p: Person): Tuple2[String, Int] = (p.name, p.age) +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +class Person(var name: String, var age: Int) +object Person: + def unapply(p: Person): Tuple2[String, Int] = (p.name, p.age) +``` + +{% endtab %} +{% endtabs %} + +因为它定义了一个 `unapply` 方法，并且因为该方法返回一个元组，所以您现在可以将 `Person` 与 `match` 表达式一起使用： + +{% tabs case-classes_12 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +val p = new Person("Astrid", 33) + +p match { + case Person(n,a) => println(s"name: $n, age: $a") + case null => println("No match") +} + +// that code prints: "name: Astrid, age: 33" +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +val p = Person("Astrid", 33) + +p match + case Person(n,a) => println(s"name: $n, age: $a") + case null => println("No match") + +// that code prints: "name: Astrid, age: 33" +``` + +{% endtab %} +{% endtabs %} + +{% endcomment %} + +## 样例对象 + +样例对象之于对象，就像 样例类之于类：它们提供了许多自动生成的方法，以使其更加强大。 +每当您需要需要少量额外功能的单例对象时，它们特别有用，例如在 `match` 表达式中与模式匹配一起使用。 + +当您需要传递不可变消息时，样例对象非常有用。 +例如，如果您正在处理音乐播放器项目，您将创建一组命令或消息，如下所示： + +{% tabs case-objects_1 %} +{% tab 'Scala 2 and 3' %} + +```scala +sealed trait Message +case class PlaySong(name: String) extends Message +case class IncreaseVolume(amount: Int) extends Message +case class DecreaseVolume(amount: Int) extends Message +case object StopPlaying extends Message +``` + +{% endtab %} +{% endtabs %} + +然后在代码的其他部分，你可以编写这样的方法，这些方法使用模式匹配来处理传入的消息（假设方法 `playSong` ， `changeVolume` 和 `stopPlayingSong` 在其他地方定义）： + +{% tabs case-objects_2 class=tabs-scala-version %} +{% tab 'Scala 2' %} + +```scala +def handleMessages(message: Message): Unit = message match { + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +} +``` + +{% endtab %} +{% tab 'Scala 3' %} + +```scala +def handleMessages(message: Message): Unit = message match + case PlaySong(name) => playSong(name) + case IncreaseVolume(amount) => changeVolume(amount) + case DecreaseVolume(amount) => changeVolume(-amount) + case StopPlaying => stopPlayingSong() +``` + +{% endtab %} +{% endtabs %} + +[ref-enums]: {{ site.scala3ref }}/enums/enums.html +[adts]: {% link _zh-cn/overviews/scala3-book/types-adts-gadts.md %} +[fp-modeling]: {% link _zh-cn/overviews/scala3-book/domain-modeling-fp.md %} +[creator]: {{ site.scala3ref }}/other-new-features/creator-applications.html +[unapply]: {{ site.scala3ref }}/changed-features/pattern-matching.html +[trait-params]: {{ site.scala3ref }}/other-new-features/trait-parameters.html diff --git a/_zh-cn/overviews/scala3-book/first-look-at-types.md b/_zh-cn/overviews/scala3-book/first-look-at-types.md new file mode 100644 index 0000000000..0c8fb09744 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/first-look-at-types.md @@ -0,0 +1,376 @@ +--- +title: 类型初探 +type: chapter +description: This page provides a brief introduction to Scala's built-in data types, including Int, Double, String, Long, Any, AnyRef, Nothing, and Null. +language: zh-cn +num: 17 +previous-page: taste-summary +next-page: string-interpolation + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +## 所有值都有一个类型 + +在 Scala 中，所有值都有一个类型，包括数值和函数。 +下图展示了类型层次结构的一个子集。 + +
+
+## Scala 类型层次结构
+
+`Any` 是所有类型的超类型，也称为 **首类型**。
+它定义了某些通用方法，例如 `equals` ， `hashCode` 和 `toString` 。
+
+首类型 `Any` 有一个子类型 [`Matchable`][matchable]，它用于标记可以执行模式匹配的所有类型。
+保证属性调用 _“参数化”_ 非常重要。
+我们不会在这里详细介绍，但总而言之，这意味着我们不能对类型为 `Any` 的值进行模式匹配，而只能对 `Matchable` 的子类型的值进行模式匹配。
+[参考文档][matchable]包含有关 `Matchable` 的更多信息。
+
+`Matchable` 有两个重要的子类型： `AnyVal` 和 `AnyRef` 。
+
+*`AnyVal`* 表示值类型。
+有几个预定义的值类型，它们是不可为空的： `Double`, `Float`, `Long`, `Int`, `Short`, `Byte`, `Char`, `Unit`, 和 `Boolean`。
+`Unit` 是一种值类型，它不携带有意义的信息。
+`Unit` 只有一个实例，我们可以将其称为：`()`。
+
+*`AnyRef`* 表示引用类型。
+所有非值类型都定义为引用类型。
+Scala中的每个用户定义类型都是 `AnyRef` 的子类型。
+如果在Java运行时环境的上下文中使用Scala，则 `AnyRef` 对应于 `java.lang.Object`。
+
+在基于语句的编程语言中， `void` 用于没有返回值的方法。
+如果您在Scala中编写没有返回值的方法，例如以下方法，则 `Unit` 用于相同的目的：
+
+{% tabs unit %}
+{% tab 'Scala 2 and 3' for=unit %}
+
+```scala
+def printIt(a: Any): Unit = println(a)
+```
+
+{% endtab %}
+{% endtabs %}
+
+下面是一个示例，它演示了字符串、整数、字符、布尔值和函数都是 `Any` 的实例，可以像对待其他所有对象一样处理：
+
+{% tabs any %}
+{% tab 'Scala 2 and 3' for=any %}
+
+```scala
+val list: List[Any] = List(
+ "a string",
+ 732, // an integer
+ 'c', // a character
+ true, // a boolean value
+ () => "an anonymous function returning a string"
+)
+
+list.foreach(element => println(element))
+```
+
+{% endtab %}
+{% endtabs %}
+
+该代码定义了一个类型为 `List[Any]` 的值 `list` 。
+该列表使用各种类型的元素进行初始化，但每个元素都是 `scala.Any` 的实例，因此我们可以将它们添加到列表中。
+
+下面是程序的输出：
+
+```
+a string
+732
+c
+true
+-128 至 127 | +| Short | 16 位有符号二进制补码整数（-2^15 至 2^15-1,含）
-32,768 至 32,767 | +| Int | 32 位二进制补码整数（-2^31 至 2^31-1,含）
-2,147,483,648 至 2,147,483,647 | +| Long | 64 位 2 的补码整数（-2^63 到 2^63-1,含）
（-2^63 到 2^63-1,包括） | +| Float | 32 位 IEEE 754 单精度浮点数
1.40129846432481707e-45 到 3.40282346638528860e+38 | +| Double | 64 位 IEEE 754 双精度浮点数
4.94065645841246544e-324 到 1.79769313486231570e+308 | +| Char | 16 位无符号 Unicode 字符（0 到 2^16-1,含）
0 到 65,535 | +| String | 一个 `Char` 序列 | + +## `BigInt` 和 `BigDecimal` + +当您需要非常大的数字时，请使用 `BigInt` 和 `BigDecimal` 类型： + +{% tabs type-bigint %} +{% tab 'Scala 2 and 3' for=type-bigint %} + +```scala +val a = BigInt(1_234_567_890_987_654_321L) +val b = BigDecimal(123_456.789) +``` + +{% endtab %} +{% endtabs %} + +其中 `Double` 和 `Float` 是近似的十进制数， `BigDecimal` 用于精确算术，例如在使用货币时。 + +`BigInt` 和 `BigDecimal` 的一个好处是，它们支持您习惯于用于数字类型的所有运算符： + +{% tabs type-bigint2 %} +{% tab 'Scala 2 and 3' for=type-bigint2 %} + +```scala +val b = BigInt(1234567890) // scala.math.BigInt = 1234567890 +val c = b + b // scala.math.BigInt = 2469135780 +val d = b * b // scala.math.BigInt = 1524157875019052100 +``` + +{% endtab %} +{% endtabs %} + +## 关于字符串的两个注释 + +Scala字符串类似于Java字符串，但它们有两个很棒的附加特性： + +- 它们支持字符串插值 +- 创建多行字符串很容易 + +### 字符串插值 + +字符串插值提供了一种非常可读的方式在字符串中使用变量。 +例如，给定以下三个变量： + +{% tabs string-inside1 %} +{% tab 'Scala 2 and 3' for=string-inside1 %} + +```scala +val firstName = "John" +val mi = 'C' +val lastName = "Doe" +``` + +{% endtab %} +{% endtabs %} + +你可以把那些变量组合成这样的字符串： + +{% tabs string-inside2 %} +{% tab 'Scala 2 and 3' for=string-inside2 %} + +```scala +println(s"Name: $firstName $mi $lastName") // "Name: John C Doe" +``` + +{% endtab %} +{% endtabs %} + +只需在字符串前面加上字母 `s` ，然后在字符串内的变量名称之前放置一个 `$` 符号。 + +如果要在字符串中使用可能较大的表达式时，请将它们放在大括号中： + +{% tabs string-inside3 %} +{% tab 'Scala 2 and 3' for=string-inside3 %} + +```scala +println(s"2 + 2 = ${2 + 2}") // prints "2 + 2 = 4" +val x = -1 +println(s"x.abs = ${x.abs}") // prints "x.abs = 1" +``` + +{% endtab %} +{% endtabs %} + +#### 其他插值器 + +放置在字符串前面的 `s` 只是一个可能的插值器。 +如果使用 `f` 而不是 `s` ，则可以在字符串中使用 `printf` 样式的格式语法。 +此外，字符串插值器只是一种特殊方法，可以定义自己的方法。 +例如，一些数据库库定义了非常强大的 `sql` 插值器。 + +### 多行字符串 + +多行字符串是通过将字符串包含在三个双引号内来创建的： + +{% tabs string-mlines1 %} +{% tab 'Scala 2 and 3' for=string-mlines1 %} + +```scala +val quote = """The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting.""" +``` + +{% endtab %} +{% endtabs %} + +这种基本方法的一个缺点是，第一行之后的行是缩进的，如下所示： + +{% tabs string-mlines2 %} +{% tab 'Scala 2 and 3' for=string-mlines2 %} + +```scala +"The essence of Scala: + Fusion of functional and object-oriented + programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +当间距很重要时，在第一行之后的所有行前面放一个 `|` 符号，并在字符串之后调用 `stripMargin` 方法： + +{% tabs string-mlines3 %} +{% tab 'Scala 2 and 3' for=string-mlines3 %} + +```scala +val quote = """The essence of Scala: + |Fusion of functional and object-oriented + |programming in a typed setting.""".stripMargin +``` + +{% endtab %} +{% endtabs %} + +现在字符串里所有行都是左对齐了： + +{% tabs string-mlines4 %} +{% tab 'Scala 2 and 3' for=string-mlines4 %} + +```scala +"The essence of Scala: +Fusion of functional and object-oriented +programming in a typed setting." +``` + +{% endtab %} +{% endtabs %} + +## 类型转换 + +可以通过以下方式强制转换值类型： + +
+
+例如：
+
+{% tabs cast1 %}
+{% tab 'Scala 2 and 3' for=cast1 %}
+
+```scala
+val b: Byte = 127
+val i: Int = b // 127
+
+val face: Char = '☺'
+val number: Int = face // 9786
+```
+
+{% endtab %}
+{% endtabs %}
+
+只有在没有丢失信息的情况下，才能强制转换为类型。否则，您需要明确说明强制转换：
+
+{% tabs cast2 %}
+{% tab 'Scala 2 and 3' for=cast2 %}
+
+```scala
+val x: Long = 987654321
+val y: Float = x.toFloat // 9.8765434E8 (注意 `.toFloat` 是必须的，因为强制类型转换后的精度会损)
+val z: Long = y // Error
+```
+
+{% endtab %}
+{% endtabs %}
+
+还可以将引用类型强制转换为子类型。
+这将在教程的后面部分介绍。
+
+## `Nothing` 和 `null`
+
+`Nothing` 是所有类型的子类型，也称为**底部类型**。
+`Nothing` 类型是没有值的。
+一个常见的用途是发出非终止信号，例如抛出异常，程序退出或无限循环---即，它是不计算为值的那种表达式，或者不正常返回的方法。
+
+`Null` 是所有引用类型的子类型（即 `AnyRef` 的任何子类型）。
+它具有由关键字面量 `null` 标识的单个值。
+目前，使用 `null` 被认为是不好的做法。它应该主要用于与其他JVM语言的互操作性。选择加入编译器选项会更改 `Null` 状态，以修复与其用法相关的警告。此选项可能会成为将来版本的 Scala 中的默认值。你可以在[这里][safe-null]了解更多关于它的信息。
+
+与此同时， `null` 几乎不应该在Scala代码中使用。
+本书的[函数式编程章节][fp]和 [API文档][option-api]中讨论了 `null` 的替代方法。
+
+[reference]: {{ site.scala3ref }}/overview.html
+[matchable]: {{ site.scala3ref }}/other-new-features/matchable.html
+[interpolation]: {% link _overviews/scala3-book/string-interpolation.md %}
+[fp]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %}
+[option-api]: https://scala-lang.org/api/3.x/scala/Option.html
+[safe-null]: {{ site.scala3ref }}/experimental/explicit-nulls.html
diff --git a/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md b/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md
new file mode 100644
index 0000000000..b1cce269af
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-functional-error-handling.md
@@ -0,0 +1,489 @@
+---
+title: 函数式错误处理
+type: section
+description: This section provides an introduction to functional error handling in Scala 3.
+language: zh-cn
+num: 46
+previous-page: fp-functions-are-values
+next-page: fp-summary
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+函数式编程就像写一系列代数方程，因为代数没有空值或抛出异常，所以你不用在 FP 中使用这些特性。
+这带来了一个有趣的问题：在 OOP 代码中通常可能使用空值或异常的情况下，您会怎么做？
+
+Scala 的解决方案是使用类似 `Option`/`Some`/`None` 类的结构。
+本课介绍如何使用这些技术。
+
+在我们开始之前有两个注意事项：
+
+- `Some` 和 `None` 类是 `Option` 的子类。
+- 下面的文字一般只指“`Option`”或“`Option`类”，而不是重复说“`Option`/`Some`/`None`”。
+
+## 第一个例子
+
+虽然第一个示例不处理空值，但它是引入 `Option` 类的好方法，所以我们将从它开始。
+
+想象一下，您想编写一个方法，可以轻松地将字符串转换为整数值，并且您想要一种优雅的方法来处理异常，这个是异常是该方法获取类似“Hello”而不是“1”的字符串时引发的。
+对这种方法的初步猜测可能如下所示：
+
+{% tabs fp-java-try class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def makeInt(s: String): Int =
+ try {
+ Integer.parseInt(s.trim)
+ } catch {
+ case e: Exception => 0
+ }
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def makeInt(s: String): Int =
+ try
+ Integer.parseInt(s.trim)
+ catch
+ case e: Exception => 0
+```
+{% endtab %}
+{% endtabs %}
+
+如果转换成功，则此方法返回正确的 `Int` 值，但如果失败，则该方法返回 `0`。
+出于某些目的，这可能是可以的，但它并不准确。
+例如，该方法可能收到了`"0"`，但它也可能收到了 `"foo"`、`"bar"` 或无数其他将引发异常的字符串。
+这是一个真正的问题：您如何知道该方法何时真正收到 `"0"`，或者何时收到其他内容？
+答案是，用这种方法，没有办法知道。
+
+## 使用 Option/Some/None
+
+Scala 中这个问题的一个常见解决方案是使用三个类，称为 `Option`、`Some` 和 `None` 。
+`Some` 和 `None` 类是 `Option` 的子类，因此解决方案的工作原理如下：
+
+- 你声明 `makeInt` 返回一个 `Option` 类型
+- 如果 `makeInt` 接收到一个字符串，它*可以* 转换为 `Int`，答案将包含在 `Some` 中
+- 如果 `makeInt` 接收到一个它*无法*转换的字符串，它返回一个 `None`
+
+这是 `makeInt` 的修订版：
+
+{% tabs fp--try-option class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def makeInt(s: String): Option[Int] =
+ try {
+ Some(Integer.parseInt(s.trim))
+ } catch {
+ case e: Exception => None
+ }
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def makeInt(s: String): Option[Int] =
+ try
+ Some(Integer.parseInt(s.trim))
+ catch
+ case e: Exception => None
+```
+{% endtab %}
+{% endtabs %}
+
+这段代码可以理解为，“当给定的字符串转换为整数时，返回包裹在 `Some` 中的 `Int`，例如 `Some(1)`。
+当字符串无法转换为整数时，会抛出并捕获异常，并且该方法返回一个 `None` 值。”
+
+这些示例展示了 `makeInt` 的工作原理：
+
+{% tabs fp-try-option-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = makeInt("1") // Some(1)
+val b = makeInt("one") // None
+```
+{% endtab %}
+{% endtabs %}
+
+如图所示，字符串`"1"`产生一个 `Some(1)`，而字符串 `"one"` 产生一个 `None`。
+这是错误处理的 `Option` 方法的本质。
+如图所示，使用了这种技术，因此方法可以返回 *值* 而不是 *异常*。
+在其他情况下，`Option` 值也用于替换 `null` 值。
+
+两个注意事项：
+
+- 你会发现这种方法在整个 Scala 库类和第三方 Scala 库中使用。
+- 这个例子的一个关键点是函数式方法不会抛出异常；相反，它们返回类似 `Option` 的值。
+
+## 成为 makeInt 的消费者
+
+现在假设您是 `makeInt` 方法的使用者。
+你知道它返回一个 `Option[Int]` 的子类，所以问题就变成了，你如何处理这些返回类型？
+
+根据您的需要，有两个常见的答案：
+
+- 使用 `match` 表达式
+- 使用 `for` 表达式
+
+## 使用 `match` 表达式
+
+一种可能的解决方案是使用 `match` 表达式：
+
+{% tabs fp-option-match class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+makeInt(x) match {
+ case Some(i) => println(i)
+ case None => println("That didn’t work.")
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+makeInt(x) match
+ case Some(i) => println(i)
+ case None => println("That didn’t work.")
+```
+{% endtab %}
+{% endtabs %}
+
+在本例中，如果 `x` 可以转换为 `Int`，则计算第一个 `case` 子句右侧的表达式；如果 `x` 不能转换为 `Int`，则计算第二个 `case` 子句右侧的表达式。
+
+## 使用 `for` 表达式
+
+另一种常见的解决方案是使用 `for` 表达式，即本书前面显示的 `for`/`yield` 组合。
+例如，假设您要将三个字符串转换为整数值，然后将它们相加。
+这就是你使用 `for` 表达式和 `makeInt` 的方法：
+
+{% tabs fp-for-comprehension class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+{% endtabs %}
+
+在该表达式运行后，`y` 将是以下两种情况之一：
+
+- 如果*所有*三个字符串都转换为 `Int` 值，`y` 将是 `Some[Int]`，即包裹在 `Some` 中的整数
+- 如果三个字符串中*任意一个*字符串不能转换为 `Int`，则 `y` 将是 `None`
+
+你可以自己测试一下：
+
+{% tabs fp-for-comprehension-evaluation class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val stringA = "1"
+val stringB = "2"
+val stringC = "3"
+
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val stringA = "1"
+val stringB = "2"
+val stringC = "3"
+
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+{% endtabs %}
+
+使用该样本数据，变量 `y` 的值将是 `Some(6)` 。
+
+要查看失败案例，请将这些字符串中的任何一个更改为不会转换为整数的字符串。
+当你这样做时，你会看到 `y` 是 `None`：
+
+{% tabs fp-for-comprehension-failure-result %}
+{% tab 'Scala 2 and 3' %}
+```scala
+y: Option[Int] = None
+```
+{% endtab %}
+{% endtabs %}
+
+## 将 Option 视为容器
+
+心智模型通常可以帮助我们理解新情况，因此，如果您不熟悉 `Option` 类，可以将它们视为*容器*：
+
+- `Some` 是一个容器，里面有一个项目
+- `None` 是一个容器，但里面什么都没有
+
+如果您更愿意将 `Option` 类想象成一个盒子，`None` 就像一个空盒子。
+它可能有一些东西，但它没有。
+
+{% comment %}
+NOTE: I commented-out this subsection because it continues to explain Some and None, and I thought it was probably too much for this book.
+
+## Using `foreach` with `Option`
+
+Because `Some` and `None` can be thought of containers, they’re also like collections classes.
+They have many of the methods you’d expect from a collection class, including `map`, `filter`, `foreach`, etc.
+
+This raises an interesting question: What will these two values print, if anything?
+
+{% tabs fp-option-methods-evaluation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+makeInt("1").foreach(println)
+makeInt("x").foreach(println)
+```
+{% endtab %}
+{% endtabs %}
+
+Answer: The first example prints the number `1`, and the second example doesn’t print anything.
+The first example prints `1` because:
+
+- `makeInt("1")` evaluates to `Some(1)`
+- The expression becomes `Some(1).foreach(println)`
+- The `foreach` method on the `Some` class knows how to reach inside the `Some` container and extract the value (`1`) that’s inside it, so it passes that value to `println`
+
+Similarly, the second example prints nothing because:
+
+- `makeInt("x")` evaluates to `None`
+- The `foreach` method on the `None` class knows that `None` doesn’t contain anything, so it does nothing
+
+In this regard, `None` is similar to an empty `List`.
+
+### The happy and unhappy paths
+
+Somewhere in Scala’s history, someone noted that the first example (the `Some`) represents the “Happy Path” of the `Option` approach, and the second example (the `None`) represents the “Unhappy Path.”
+*But* despite having two different possible outcomes, the great thing with `Option` is that there’s really just one path: The code you write to handle the `Some` and `None` possibilities is the same in both cases.
+The `foreach` examples look like this:
+
+{% tabs fp-another-option-method-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+makeInt(aString).foreach(println)
+```
+{% endtab %}
+{% endtabs %}
+
+And the `for` expression looks like this:
+
+{% tabs fp-another-for-comprehension-example class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val y = for {
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+} yield {
+ a + b + c
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val y = for
+ a <- makeInt(stringA)
+ b <- makeInt(stringB)
+ c <- makeInt(stringC)
+yield
+ a + b + c
+```
+{% endtab %}
+{% endtabs %}
+
+With exceptions you have to worry about handling branching logic, but because `makeInt` returns a value, you only have to write one piece of code to handle both the Happy and Unhappy Paths, and that simplifies your code.
+
+Indeed, the only time you have to think about whether the `Option` is a `Some` or a `None` is when you handle the result value, such as in a `match` expression:
+
+{% tabs fp-option-match-handle class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+makeInt(x) match {
+ case Some(i) => println(i)
+ case None => println("That didn't work.")
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+makeInt(x) match
+ case Some(i) => println(i)
+ case None => println("That didn't work.")
+```
+{% endtab %}
+{% endtabs %}
+
+> There are several other ways to handle `Option` values.
+> See the reference documentation for more details.
+{% endcomment %}
+
+## 使用 `Option` 替换 `null`
+
+回到 `null` 值，`null` 值可以悄悄地潜入你的代码的地方是这样的类：
+
+{% tabs fp=case-class-nulls %}
+{% tab 'Scala 2 and 3' %}
+```scala
+class Address(
+ var street1: String,
+ var street2: String,
+ var city: String,
+ var state: String,
+ var zip: String
+)
+```
+{% endtab %}
+{% endtabs %}
+
+虽然地球上的每个地址都有一个 `street1` 值，但 `street2` 值是可选的。
+因此，`street2` 字段可以被分配一个 `null` 值：
+
+{% tabs fp-case-class-nulls-example class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "1 Main Street",
+ null, // <-- D’oh! A null value!
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "1 Main Street",
+ null, // <-- D’oh! A null value!
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+{% endtabs %}
+
+从历史上看，开发人员在这种情况下使用了空白字符串和空值，这两种方法都是使用技巧来解决基础性的问题，这个问题是：`street2` 是一个*可选*字段。
+在 Scala 和其他现代语言中，正确的解决方案是预先声明 `street2` 是可选的：
+
+{% tabs fp-case-class-with-options %}
+{% tab 'Scala 2 and 3' %}
+```scala
+class Address(
+ var street1: String,
+ var street2: Option[String], // an optional value
+ var city: String,
+ var state: String,
+ var zip: String
+)
+```
+{% endtab %}
+{% endtabs %}
+
+现在开发人员可以编写更准确的代码，如下所示：
+
+{% tabs fp-case-class-with-options-example-none class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "1 Main Street",
+ None, // 'street2' has no value
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "1 Main Street",
+ None, // 'street2' has no value
+ "North Pole",
+ "Alaska",
+ "99705"
+)
+```
+{% endtab %}
+{% endtabs %}
+
+或这个：
+
+{% tabs fp-case-class-with-options-example-some class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+val santa = new Address(
+ "123 Main Street",
+ Some("Apt. 2B"),
+ "Talkeetna",
+ "Alaska",
+ "99676"
+)
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+val santa = Address(
+ "123 Main Street",
+ Some("Apt. 2B"),
+ "Talkeetna",
+ "Alaska",
+ "99676"
+)
+```
+{% endtab %}
+{% endtabs %}
+
+## `Option` 不是唯一的解决方案
+
+虽然本节关注的是 `Option` 类，但 Scala 还有一些其他选择。
+
+例如，称为 `Try`/`Success`/`Failure` 的三个类以相同的方式工作，但是 (a) 当您的代码可以抛出异常时，您主要使用这些类，并且 (b) 您想要使用`Failure` 类，因为它使您可以访问异常消息。
+例如，在编写与文件、数据库和 Internet 服务交互的方法时，通常会使用这些 `Try` 类，因为这些函数很容易引发异常。
+
+## 快速回顾
+
+这部分很长，让我们快速回顾一下：
+
+- 函数式程序员不使用 `null` 值
+- `null` 值的主要替代品是使用 `Option` 类
+- 函数式方法不会抛出异常； 相反，它们返回诸如 `Option` 、 `Try` 或 `Either` 之类的值
+- 使用 `Option` 值的常用方法是 `match` 和 `for` 表达式
+- Option 可以被认为是一个项目（`Some`）和没有项目（`None`）的容器
+- option 也可用于可选的构造函数或方法参数
+
diff --git a/_zh-cn/overviews/scala3-book/fp-functions-are-values.md b/_zh-cn/overviews/scala3-book/fp-functions-are-values.md
new file mode 100644
index 0000000000..ab802ed02a
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-functions-are-values.md
@@ -0,0 +1,133 @@
+---
+title: 函数是值
+type: section
+description: This section looks at the use of functions as values in functional programming.
+language: zh-cn
+num: 45
+previous-page: fp-pure-functions
+next-page: fp-functional-error-handling
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+虽然曾经创建的每种编程语言都可能允许您编写纯函数，但 Scala FP 的第二个重要特性是*您可以将函数创建为值*，就像您创建 `String` 和 `Int` 值一样。
+
+这个特性有很多好处，其中最常见的是（a）您可以定义方法来接受函数参数，以及（b）您可以将函数作为参数传递给方法。
+你已经在本书的多个地方看到了这一点，每当演示像 `map` 和 `filter` 这样的方法时：
+
+{% tabs fp-function-as-values-anonymous %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val nums = (1 to 10).toList
+
+val doubles = nums.map(_ * 2) // double each value
+val lessThanFive = nums.filter(_ < 5) // List(1,2,3,4)
+```
+{% endtab %}
+{% endtabs %}
+
+在这些示例中，匿名函数被传递到 `map` 和 `filter` 中。
+
+> 匿名函数也称为 *lambdas*。
+
+除了将匿名函数传递给 `filter` 和 `map` 之外，您还可以为它们提供 *方法*：
+
+{% tabs fp-function-as-values-defined %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// two methods
+def double(i: Int): Int = i * 2
+def underFive(i: Int): Boolean = i < 5
+
+// pass those methods into filter and map
+val doubles = nums.filter(underFive).map(double)
+```
+{% endtab %}
+{% endtabs %}
+
+这种将方法和函数视为值的能力是函数式编程语言提供的强大特性。
+
+> 从技术上讲，将另一个函数作为输入参数的函数称为 *高阶函数*。
+> （如果你喜欢幽默，就像有人曾经写过的那样，这就像说一个将另一个类的实例作为构造函数参数的类是一个高阶类。）
+
+## 函数、匿名函数和方法
+
+正如您在这些示例中看到的，这是一个匿名函数：
+
+{% tabs fp-anonymous-function-short %}
+{% tab 'Scala 2 and 3' %}
+```scala
+_ * 2
+```
+{% endtab %}
+{% endtabs %}
+
+如 [高阶函数][hofs] 讨论中所示，上面的写法是下面语法的简写版本：
+
+{% tabs fp-anonymous-function-full %}
+{% tab 'Scala 2 and 3' %}
+```scala
+(i: Int) => i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+像这样的函数被称为“匿名”，因为它们没有名字。
+如果你想给一个名字，只需将它分配给一个变量：
+
+{% tabs fp-function-assignement %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val double = (i: Int) => i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+现在你有了一个命名函数，一个分配给变量的函数。
+您可以像使用方法一样使用此函数：
+
+{% tabs fp-function-used-like-method %}
+{% tab 'Scala 2 and 3' %}
+```scala
+double(2) // 4
+```
+{% endtab %}
+{% endtabs %}
+
+在大多数情况下，`double` 是函数还是方法并不重要。 Scala 允许您以同样的方式对待它们。
+在幕后，让您像对待函数一样对待方法的 Scala 技术被称为 [Eta 表达式][eta]。
+
+这种将函数作为变量无缝传递的能力是 Scala 等函数式编程语言的一个显着特征。
+正如您在本书中的 `map` 和 `filter` 示例中所见，将函数传递给其他函数的能力有助于您创建简洁且仍然可读的代码---*富有表现力*。
+
+如果您对将函数作为参数传递给其他函数的过程不适应，可以尝试以下几个示例：
+
+{% tabs fp-function-as-values-example %}
+{% tab 'Scala 2 and 3' %}
+```scala
+List("bob", "joe").map(_.toUpperCase) // List(BOB, JOE)
+List("bob", "joe").map(_.capitalize) // List(Bob, Joe)
+List("plum", "banana").map(_.length) // List(4, 6)
+
+val fruits = List("apple", "pear")
+fruits.map(_.toUpperCase) // List(APPLE, PEAR)
+fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R)
+
+val nums = List(5, 1, 3, 11, 7)
+nums.map(_ * 2) // List(10, 2, 6, 22, 14)
+nums.filter(_ > 3) // List(5, 11, 7)
+nums.takeWhile(_ < 6) // List(5, 1, 3)
+nums.sortWith(_ < _) // List(1, 3, 5, 7, 11)
+nums.sortWith(_ > _) // List(11, 7, 5, 3, 1)
+
+nums.takeWhile(_ < 6).sortWith(_ < _) // List(1, 3, 5)
+```
+{% endtab %}
+{% endtabs %}
+
+[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %}
+[eta]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_zh-cn/overviews/scala3-book/fp-immutable-values.md b/_zh-cn/overviews/scala3-book/fp-immutable-values.md
new file mode 100644
index 0000000000..1d6b474daf
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-immutable-values.md
@@ -0,0 +1,95 @@
+---
+title: 不可变值
+type: section
+description: This section looks at the use of immutable values in functional programming.
+language: zh-cn
+num: 43
+previous-page: fp-what-is-fp
+next-page: fp-pure-functions
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+在纯函数式编程中，只使用不可变的值。
+在 Scala 中，这意味着：
+
+- 所有变量都创建为 `val` 字段
+- 仅使用不可变的集合类，例如 `List`、`Vector` 和不可变的 `Map` 和 `Set` 类
+
+只使用不可变变量会引发一个有趣的问题：如果一切都是不可变的，那么任何东西都如何改变？
+
+当谈到使用集合时，一个答案是你不会改变现有的集合。相反，您将函数应用于现有集合以创建新集合。
+这就是像 `map` 和 `filter` 这样的高阶函数的用武之地。
+
+例如，假设你有一个名字列表——一个 `List[String]`——都是小写的，你想找到所有以字母 `"j"` 开头的名字，并且把找出来的名字大写。
+在 FP 中，您编写以下代码：
+
+{% tabs fp-list %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val a = List("jane", "jon", "mary", "joe")
+val b = a.filter(_.startsWith("j"))
+ .map(_.capitalize)
+```
+{% endtab %}
+{% endtabs %}
+
+如图所示，您不会改变原始列表 `a`。
+相反，您将过滤和转换函数应用于 `a` 以创建一个新集合，并将该结果分配给新的不可变变量 `b` 。
+
+同样，在 FP 中，您不会创建具有可变 `var` 构造函数参数的类。
+也就是说，你不要这样写：
+
+{% tabs fp--class-variables %}
+{% tab 'Scala 2 and 3' %}
+```scala
+// don’t do this in FP
+class Person(var firstName: String, var lastName: String)
+ --- ---
+```
+{% endtab %}
+{% endtabs %}
+
+相反，您通常创建 `case` 类，其构造函数参数默认为 `val`：
+
+{% tabs fp-immutable-case-class %}
+{% tab 'Scala 2 and 3' %}
+```scala
+case class Person(firstName: String, lastName: String)
+```
+{% endtab %}
+{% endtabs %}
+
+现在你创建一个 `Person` 实例作为 `val` 字段：
+
+{% tabs fp-case-class-creation %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val reginald = Person("Reginald", "Dwight")
+```
+{% endtab %}
+{% endtabs %}
+
+然后，当您需要对数据进行更改时，您可以使用 `case` 类附带的 `copy` 方法来“在制作副本时更新数据”，如下所示：
+
+{% tabs fp-case-class-copy %}
+{% tab 'Scala 2 and 3' %}
+```scala
+val elton = reginald.copy(
+ firstName = "Elton", // update the first name
+ lastName = "John" // update the last name
+)
+```
+{% endtab %}
+{% endtabs %}
+
+还有其他处理不可变集合和变量的技术，但希望这些示例能让您尝试一下这些技术。
+
+> 根据您的需要，您可以创建枚举、traits 或类，而不是 `case` 类。
+> 有关详细信息，请参阅[数据建模][modeling]一章。
+
+[modeling]: {% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %}
diff --git a/_zh-cn/overviews/scala3-book/fp-intro.md b/_zh-cn/overviews/scala3-book/fp-intro.md
new file mode 100644
index 0000000000..4805401aec
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-intro.md
@@ -0,0 +1,30 @@
+---
+title: 函数式编程
+type: chapter
+description: This chapter provides an introduction to functional programming in Scala 3.
+language: zh-cn
+num: 41
+previous-page: collections-summary
+next-page: fp-what-is-fp
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 允许您以面向对象编程 (OOP) 风格、函数式编程 (FP) 风格以及混合风格编写代码——结合使用这两种方法。
+正如 Scala 的创建者 Martin Odersky 所说，Scala 的本质是在类型化设置中融合了函数式编程和面向对象编程：
+
+- 逻辑函数
+- 模块化的对象
+
+本章假设您熟悉 OOP 而不太熟悉 FP，因此它简要介绍了几个主要的函数式编程概念：
+
+- 什么是函数式编程？
+- 不可变值
+- 纯函数
+- 函数是值
+- 函数式错误处理
+
diff --git a/_zh-cn/overviews/scala3-book/fp-pure-functions.md b/_zh-cn/overviews/scala3-book/fp-pure-functions.md
new file mode 100644
index 0000000000..25fa4398ff
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-pure-functions.md
@@ -0,0 +1,129 @@
+---
+title: 纯函数
+type: section
+description: This section looks at the use of pure functions in functional programming.
+language: zh-cn
+num: 44
+previous-page: fp-immutable-values
+next-page: fp-functions-are-values
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+Scala 提供的另一个帮助您编写函数式代码的特性是编写纯函数的能力。
+一个_纯函数_可以这样定义：
+
+- 函数 `f` 是纯函数，如果给定相同的输入 `x`，它总是返回相同的输出 `f(x)`
+- 函数的输出_只_取决于它的输入变量和它的实现
+- 它只计算输出而不修改周围的世界
+
+这意味着：
+- 它不修改其输入参数
+- 它不会改变任何隐藏状态
+- 没有任何“后门”：不从外界读取数据（包括控制台、Web服务、数据库、文件等），也不向外界写入数据
+
+作为这个定义的结果，任何时候你调用一个具有相同输入值的纯函数，你总是会得到相同的结果。
+例如，您可以使用输入值 `2` 无限次调用 `double` 函数，并且始终得到结果 `4`。
+
+## 纯函数示例
+
+给定这个定义，你可以想象， *scala.math._* 包中的这些方法是纯函数：
+
+- `abs`
+- `ceil`
+- `max`
+
+这些 `String` 方法也是纯函数：
+
+- `isEmpty`
+- `length`
+- `substring`
+
+Scala 集合类上的大多数方法也可以作为纯函数工作，包括 `drop`、`filter`、`map` 等等。
+
+> 在 Scala 中，_函数_和_方法_几乎可以完全互换，因此即使我们使用行业通用术语“纯函数”，这个术语也可以用来描述函数和方法。
+> 如果您对如何像函数一样使用方法感兴趣，请参阅 [Eta 表达式][eta] 的讨论。
+
+## 不纯函数示例
+
+相反，以下函数是_不纯的_，因为它们违反了纯函数的定义。
+
+- `println` -- 与控制台、文件、数据库、Web 服务、传感器等交互的方法都是不纯的。
+- `currentTimeMillis ` -- 与日期和时间相关的方法都是不纯的，因为它们的输出取决于输入参数以外的其他东西
+- `sys.error` -- 异常抛出方法是不纯的，因为它们不简单地返回结果
+
+不纯函数通常会执行以下一项或多项操作：
+
+- 从隐藏状态读取，即它们访问的变量和数据不是作为输入参数明确地传递给函数
+- 写入隐藏状态
+- 改变他们给定的参数，或改变隐藏变量，例如类中包涵的字段
+- 与外界执行某种 I/O
+
+> 通常，您应该注意返回类型为 `Unit` 的函数。
+> 因为这些函数不返回任何东西，逻辑上你调用它的唯一原因是实现一些副作用。
+> 因此，这些功能的使用通常是不纯的。
+
+## 但是需要不纯的函数...
+
+当然，如果一个应用程序不能读取或写入外部世界，它就不是很有用，所以人们提出以下建议：
+
+> 使用纯函数编写应用程序的核心，然后围绕该核心编写一个不纯的“包装器”以与外部世界交互。
+> 正如有人曾经说过的，这就像在纯蛋糕上加了一层不纯的糖霜。
+
+重要的是要注意，有一些方法可以让与外界的不纯粹互动感觉更纯粹。
+例如，你会听说使用 `IO` Monad 来处理输入和输出。
+这些主题超出了本文档的范围，所以为了简单起见，这样认识 FP 会有所帮助：FP 应用程序有一个纯函数核心，还有其他一些函数把这些纯函数包装起来与外部世界交互。
+
+## 编写纯函数
+
+**注意**：在本节中，常见的行业术语“纯函数”通常用于指代 Scala 方法。
+
+要在 Scala 中编写纯函数，只需使用 Scala 的方法语法编写它们（尽管您也可以使用 Scala 的函数语法）。
+例如，这是一个将给定输入值加倍的纯函数：
+
+{% tabs fp-pure-function %}
+{% tab 'Scala 2 and 3' %}
+```scala
+def double(i: Int): Int = i * 2
+```
+{% endtab %}
+{% endtabs %}
+
+如果您对递归感到满意，这是一个计算整数列表之和的纯函数：
+
+{% tabs fp-pure-recursive-function class=tabs-scala-version %}
+{% tab 'Scala 2' %}
+```scala
+def sum(xs: List[Int]): Int = xs match {
+ case Nil => 0
+ case head :: tail => head + sum(tail)
+}
+```
+{% endtab %}
+
+{% tab 'Scala 3' %}
+```scala
+def sum(xs: List[Int]): Int = xs match
+ case Nil => 0
+ case head :: tail => head + sum(tail)
+```
+{% endtab %}
+{% endtabs %}
+
+如果您理解该代码，您会发现它符合纯函数定义。
+
+## 要点
+
+本节的第一个要点是纯函数的定义：
+
+> _纯函数_是仅依赖于其声明的输入及其实现来产生其输出的函数。
+> 它只计算其输出，不依赖或修改外部世界。
+
+第二个要点是每个现实世界的应用程序都与外部世界交互。
+因此，考虑函数式程序的一种简化方法是，它们由一个纯函数核心组成，其他一些函数把这些纯函数包装起来与外部世界交互。
+
+[eta]: {% link _zh-cn/overviews/scala3-book/fun-eta-expansion.md %}
diff --git a/_zh-cn/overviews/scala3-book/fp-summary.md b/_zh-cn/overviews/scala3-book/fp-summary.md
new file mode 100644
index 0000000000..459b2d6f82
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-summary.md
@@ -0,0 +1,30 @@
+---
+title: 总结
+type: section
+description: This section summarizes the previous functional programming sections.
+language: zh-cn
+num: 47
+previous-page: fp-functional-error-handling
+next-page: types-introduction
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本章在比较高的层次上，对 Scala 中的函数式编程进行了介绍。
+涵盖的主题是：
+
+- 什么是函数式编程？
+- 不可变值
+- 纯函数
+- 函数是值
+- 函数式错误处理
+
+如前所述，函数式编程是一个很大的话题，所以我们在本书中所能做的就是触及这些介绍性概念。
+有关详细信息，请参阅 [参考文档][reference]。
+
+[reference]: {{ site.scala3ref }}/overview.html
+
diff --git a/_zh-cn/overviews/scala3-book/fp-what-is-fp.md b/_zh-cn/overviews/scala3-book/fp-what-is-fp.md
new file mode 100644
index 0000000000..79370d450b
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/fp-what-is-fp.md
@@ -0,0 +1,33 @@
+---
+title: 什么是函数式编程？
+type: section
+description: This section provides an answer to the question, what is functional programming?
+language: zh-cn
+num: 42
+previous-page: fp-intro
+next-page: fp-immutable-values
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+[维基百科定义_函数式编程_](https://en.wikipedia.org/wiki/Functional_programming)如下：
+
+++ +知道这样的情况对你很有帮助：有经验的函数式程序员非常倾向于将他们的代码视为数学，将纯函数组合在一起就像组合一系列代数方程一样。 + +当你编写函数式代码时，你会感觉自己像个数学家，一旦你理解了范式，你就会想编写总是返回_值_---而不是异常或空值---的纯函数，这样你就可以将它们组合（结合）在一起以创建解决方案。 +编写类似数学的方程式（表达式）的感觉是驱使您_只_使用纯函数和不可变值的动力，因为这就是您在代数和其他形式的数学中使用的东西。 + +函数式编程是一个很大的主题，没有简单的方法可以将整个主题浓缩为一章，但希望以下部分能够概述主要主题，并展示 Scala 为编写函数式代码提供的一些工具。 + diff --git a/_zh-cn/overviews/scala3-book/fun-anonymous-functions.md b/_zh-cn/overviews/scala3-book/fun-anonymous-functions.md new file mode 100644 index 0000000000..ec08a19e02 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/fun-anonymous-functions.md @@ -0,0 +1,202 @@ +--- +title: 匿名函数 +type: section +description: This page shows how to use anonymous functions in Scala, including examples with the List class 'map' and 'filter' functions. +language: zh-cn +num: 29 +previous-page: fun-intro +next-page: fun-function-variables + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +匿名函数（也称为 *lambda*）是作为参数传递给高阶函数的代码块。 +维基百科将 [匿名函数](https://en.wikipedia.org/wiki/Anonymous_function) 定义为“未绑定到标识符的函数定义”。 + +例如，给定这样的列表： + +{% tabs fun-anonymous-1 %} +{% tab 'Scala 2 and 3' %} +```scala +val ints = List(1, 2, 3) +``` +{% endtab %} +{% endtabs %} + +您可以通过使用 `List` 类 `map` 方法和自定义匿名函数将 `ints` 中的每个元素加倍来创建一个新列表： + +{% tabs fun-anonymous-2 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map(_ * 2) // List(2, 4, 6) +``` +{% endtab %} +{% endtabs %} + +如注释所示，`doubledInts` 包含列表`List(2, 4, 6)`。 +在该示例中，这部分代码是一个匿名函数： + +{% tabs fun-anonymous-3 %} +{% tab 'Scala 2 and 3' %} +```scala +_ * 2 +``` +{% endtab %} +{% endtabs %} + +这是“将给定元素乘以 2”的简写方式。 + +## 更长的形式 + +一旦你熟悉了 Scala，你就会一直使用这种形式来编写匿名函数，这些函数在函数的一个位置使用一个变量。 +但如果你愿意，你也可以用更长的形式来写它们，所以除了写这段代码： + +{% tabs fun-anonymous-4 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map(_ * 2) +``` +{% endtab %} +{% endtabs %} + +您也可以使用以下形式编写它： + +{% tabs fun-anonymous-5 %} +{% tab 'Scala 2 and 3' %} +```scala +val doubledInts = ints.map((i: Int) => i * 2) +val doubledInts = ints.map((i) => i * 2) +val doubledInts = ints.map(i => i * 2) +``` +{% endtab %} +{% endtabs %} + +所有这些行的含义完全相同：将 `ints` 中的每个元素加倍以创建一个新列表 `doubledInts`。 +（稍后会解释每种形式的语法。） + +如果您熟悉 Java，了解这些 `map` 示例与以下 Java 代码等价可能会有所帮助： + +{% tabs fun-anonymous-5-b %} +{% tab 'Java' %} +```java +List函数式编程是一种编程范式，通过应用和组合函数来构建程序。 +它是一种声明式编程范例，其中函数定义是表达式树，每个表达式都返回一个值，而不是改变程序状态的命令式语句序列。
++
在函数式编程中，函数被视为一等公民，这意味着它们可以绑定到名称（包括本地标识符）、作为参数传递以及从其他函数返回，就像任何其他数据类型一样。 +这允许以声明式和可组合的方式编写程序，其中小函数以模块化方式组合。
+
+ 如果你有兴趣看本书的 Scala 2 版，你可以在这获得。 +我们目前在整合这两本书，你可以帮助我们。 ++ +在本书中，我们希望证明 Scala 是一种优美的、富有表现力的编程语言。它具有简洁、现代的语法，支持函数式编程（FP）和面向对象编程（OOP），并提供安全的静态类型系统。 +Scala 的语法和特性都经过了重新思考与公开辩论，并在2020年更新，比以往任何时候都更清晰、更容易理解。 + +本书首先在[“品味 Scala”部分][taste]对 Scala 的许多特性进行了一次“旋风之旅”。随后的章节会提供有关这些语言特性的更多详细信息。 + +{% comment %} +We should have a link structure on the whole tour here +{% endcomment %} + +[reference]: {{ site.scala3ref }}/overview.html +[taste]: {% link _zh-cn/overviews/scala3-book/taste-intro.md %} diff --git a/_zh-cn/overviews/scala3-book/methods-intro.md b/_zh-cn/overviews/scala3-book/methods-intro.md new file mode 100644 index 0000000000..ec383b437e --- /dev/null +++ b/_zh-cn/overviews/scala3-book/methods-intro.md @@ -0,0 +1,22 @@ +--- +title: 方法 +type: chapter +description: This section introduces methods in Scala 3. +language: zh-cn +num: 24 +previous-page: domain-modeling-fp +next-page: methods-most + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + + +在 Scala 2 中，_方法_可以在类、traits、对象、样例类和样例对象中定义。 +但它变得更好了：在Scala 3中，可以在这些结构的_外部_定义方法；我们说它们是“顶级”定义，因为它们没有嵌套在另一个定义中。 +简而言之，现在可以在任何地方定义方法。 + +方法的许多功能将在下一节中演示。 +由于 `main` 方法需要更多的解释，因此后面有单独部分对其进行描述。 diff --git a/_zh-cn/overviews/scala3-book/methods-main-methods.md b/_zh-cn/overviews/scala3-book/methods-main-methods.md new file mode 100644 index 0000000000..1b185854b1 --- /dev/null +++ b/_zh-cn/overviews/scala3-book/methods-main-methods.md @@ -0,0 +1,188 @@ +--- +title: main 方法 +type: section +description: This page describes how 'main' methods and the '@main' annotation work in Scala 3. +language: zh-cn +num: 26 +previous-page: methods-most +next-page: methods-summary + +partof: scala3-book +overview-name: "Scala 3 — Book" +layout: multipage-overview +permalink: "/zh-cn/scala3/book/:title.html" +--- + +
编写仅Scala 3 适用的一行程序
+ +Scala 3 提供了一种定义可以从命令行调用的程序的新方法：在方法中添加 `@main` 注释会将其变成可执行程序的入口点： + +{% tabs method_1 %} +{% tab 'Scala 3 Only' for=method_1 %} + +```scala +@main def hello() = println("Hello, world") +``` + +{% endtab %} +{% endtabs %} + +只需将该行代码保存在一个名为 *Hello.scala* 的文件中——文件名不必与方法名匹配——并使用 `scala` 运行它： + +```bash +$ scala Hello.scala +Hello, world +``` + +`@main` 注释方法可以写在顶层（如图所示），也可以写在静态可访问的对象中。 +在任何一种情况下，程序的名称都是方法的名称，没有任何对象前缀。 + +学习更多 `@main` 注解，可以阅读以下章节，或者看这个视频： + +
+
+
+
+### 命令行参数
+
+使用这种方法，您的`@main` 方法可以处理命令行参数，并且这些参数可以有不同的类型。
+例如，给定这个 `@main` 方法，它接受一个 `Int`、一个 `String` 和一个可变参数 `String*` 参数：
+
+{% tabs method_2 %}
+{% tab 'Scala 3 Only' for=method_2 %}
+
+```scala
+@main def happyBirthday(age: Int, name: String, others: String*) =
+ val suffix = (age % 100) match
+ case 11 | 12 | 13 => "th"
+ case _ => (age % 10) match
+ case 1 => "st"
+ case 2 => "nd"
+ case 3 => "rd"
+ case _ => "th"
+
+ val sb = StringBuilder(s"Happy $age$suffix birthday, $name")
+ for other <- others do sb.append(" and ").append(other)
+ sb.toString
+```
+
+{% endtab %}
+{% endtabs %}
+
+当你编译该代码时，它会创建一个名为 `happyBirthday` 的主程序，它的调用方式如下：
+
+```
+$ scala happyBirthday 23 Lisa Peter
+Happy 23rd Birthday, Lisa and Peter!
+```
+
+如上所示，`@main` 方法可以有任意数量的参数。
+对于每个参数类型，必须是 `scala.util.CommandLineParser.FromString` 类型类的一个 [given实例]({% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %})，它将参数 `String` 转换为所需的参数类型。
+同样如图所示，主方法的参数列表可以以重复参数结尾，例如 `String*`，它接受命令行中给出的所有剩余参数。
+
+从 `@main` 方法实现的程序检查命令行上是否有足够的参数来填充所有参数，以及参数字符串是否可以转换为所需的类型。
+如果检查失败，程序将终止并显示错误消息：
+
+```
+$ scala happyBirthday 22
+Illegal command line after first argument: more arguments expected
+
+$ scala happyBirthday sixty Fred
+Illegal command line: java.lang.NumberFormatException: For input string: "sixty"
+```
+
+## 用户自定义的类型作为参数
+
+正如上面指出的，编译器为参数类型寻找 `scala.util.CommandLineParser.FromString` 类型类 的given 实例。
+例如，我们自定义了一个 `Color`类型，并希望当以参数使用。你可以像以下代码这样使用：
+
+{% tabs method_3 %}
+{% tab 'Scala 3 Only' for=method_3 %}
+
+```scala
+enum Color:
+ case Red, Green, Blue
+
+given ComamndLineParser.FromString[Color] with
+ def fromString(value: String): Color = Color.valueOf(value)
+
+@main def run(color: Color): Unit =
+ println(s"The color is ${color.toString}")
+```
+
+{% endtab %}
+{% endtabs %}
+
+这对于您程序中的自定义类型以及可能使用的其他库中的类型，都是一样的。
+
+## 细节
+
+Scala 编译器从 `@main` 方法 `f` 生成程序，如下所示：
+
+- 它在有 `@main` 方法的包中创建一个名为 `f` 的类。
+- 该类有一个静态方法 `main`，具有 Java `main` 方法的通常签名：它以 `Array[String]` 作为参数并返回 `Unit`。
+- 生成的 `main` 方法调用方法 `f` 并使用 `scala.util.CommandLineParser` 对象中的方法转换参数。
+
+例如，上面的 `happyBirthday` 方法会生成与以下类等效的附加代码：
+
+{% tabs method_3 %}
+{% tab 'Scala 3 Only' for=method_3 %}
+
+```scala
+final class happyBirthday {
+ import scala.util.{CommandLineParser as CLP}
+
+
+此页面通过共享每种语言的并排示例，对 Java 和 Scala 编程语言进行了比较。
+它适用于了解 Java 并希望了解 Scala 的程序员，特别是通过 Scala 特性与 Java 特性的对比来了解。
+
+## 概述
+
+在进入示例之前，第一部分提供了以下部分的相对简短的介绍和总结。
+它从高层次上介绍了 Java 和 Scala 之间的异同，然后介绍了您在每天编写代码时会遇到的差异。
+
+### 高层次的相似性
+
+在高层次上，Scala 与 Java 有以下相似之处：
+
+- Scala代码编译成_.class_文件，打包成JAR文件，运行在JVM上
+- 这是一种[面向对象编程][modeling-oop] (OOP) 语言
+- 它是静态类型的
+- 两种语言都支持 lambdas 和 [高阶函数][hofs]
+- 它们都可以与 IntelliJ IDEA 和 Microsoft VS Code 等 IDE 一起使用
+- 可以使用 Gradle、Ant 和 Maven 等构建工具构建项目
+- 它具有用于构建服务器端、网络密集型应用程序的出色库和框架，包括 Web 服务器应用程序、微服务、机器学习等（参见 [“Awesome Scala” 列表](https://github.com/lauris/awesome-scala)）
+- Java 和 Scala 都可以使用 Scala 库：
+ - 他们可以使用 [Akka actor 库](https://akka.io) 来构建基于 actor 的并发系统，并使用 Apache Spark 来构建数据密集型应用程序
+ - 他们可以使用 [Play Framework](https://www.playframework.com) 开发服务器端应用程序
+- 您可以使用 [GraalVM](https://www.graalvm.org) 将您的项目编译为本机可执行文件
+- Scala 可以无缝使用为 Java 开发的大量库
+
+### 高层次的差异
+
+同样在高层次上，Java 和 Scala 之间的区别是：
+
+- Scala 语法简洁易读；我们称之为_表现力_
+- 虽然它是静态类型的，但 Scala 经常感觉像是一门动态语言
+- Scala 是一种纯 OOP 语言，因此每个对象都是类的一个实例，而像运算符一样的符号 `+` 和 `+=` 是真正的方法；这意味着您可以创建自己的运算符
+- 除了是纯OOP语言，Scala还是纯FP语言；实际上，它鼓励 OOP 和 FP 的融合，具有用于逻辑的函数和用于模块化的对象
+- Scala 拥有一整套不可变集合，包括 `List`、`Vector` 和不可变的 `Map` 和 `Set` 实现
+- Scala 中的一切都是一个_表达式_：像 `if` 语句、`for` 循环、`match` 表达式，甚至 `try`/`catch` 表达式都有返回值
+- Scala 习惯上倾向缺省使用不可变性：鼓励您使用不可变（`final`）变量和不可变集合
+- 惯用的 Scala 代码不使用 `null`，因此不会遭受 `NullPointerException`
+- Scala 生态系统在 sbt、Mill 等中还有其他 [构建工具][tools]
+- 除了在 JVM 上运行之外，[Scala.js](https://www.scala-js.org) 项目允许您使用 Scala 作为 JavaScript 替代品
+- [Scala Native](http://www.scala-native.org) 项目添加了低级结构，让您可以编写“系统”级代码，也可以编译为本机可执行文件
+
+{% comment %}
+These are several notes that came up early in the writing process, and I (Alvin) can’t really address them:
+TODO: Need a good, simple way to state that Scala has a sound type system
+TODO: Points to make about Scala’s consistency?
+TODO: Add a point about how the type system lets you express details as desired
+{% endcomment %}
+
+### 编程层次差异
+
+最后，这些是您在编写代码时每天都会看到的一些差异：
+
+- Scala 的语法极其一致
+- 变量和参数被定义为`val`（不可变，如Java中的`final`）或`var`（可变）
+- _类型推导_ 让您的代码感觉是动态类型的，并有助于保持您的代码简洁
+- 除了简单的 `for` 循环之外，Scala 还具有强大的 `for` comprehensions，可以根据您的算法产生结果
+- 模式匹配和 `match` 表达式将改变你编写代码的方式
+- 默认情况下编写不可变代码会导致编写_表达式_而不是_语句_；随着时间的推移，您会发现编写表达式可以简化您的代码（和您的测试）
+- [顶层定义][toplevel] 让您可以将方法、字段和其他定义放在任何地方，同时也带来简洁、富有表现力的代码
+- 您可以通过将多个 traits “混合”到类和对象中来创建_混搭_（特征类似于 Java 8 和更新版本中的接口）
+- 默认情况下类是封闭的，支持 Joshua Bloch 在 _Effective Java_ 的习惯用法，“Design and document for inheritance or else forbid it”
+- Scala 的 [上下文抽象][contextual] 和 _术语推导_ 提供了一系列特性：
+ - [扩展方法][extension-methods] 让您向封闭类添加新功能
+ - [_给_实例][givens] 让您定义编译器可以在 _using_ 点合成的术语，从而使您的代码不那么冗长，实质上让编译器为您编写代码
+ - [多元等式][multiversal] 允许您在编译时将相等比较限制为仅那些有意义的比较
+- Scala 拥有最先进的第三方开源函数式编程库
+- Scala 样例类就像 Java 14 中的记录；它们可以帮助您在编写 FP 代码时对数据进行建模，并内置对模式匹配和克隆等概念的支持
+- 由于名称参数、中缀符号、可选括号、扩展方法和 [高阶函数][hofs] 等功能，您可以创建自己的“控制结构”和 DSL
+- Scala 文件不必根据它们包含的类或 trait 来命名
+- 许多其他好东西：伴生类和对象、宏、[联合][union-types] 和 [交集][intersection-types]、数字字面量、多参数列表、参数的默认值、命名参数等
+
+### 用例子来进行特性对比
+
+鉴于该介绍，以下部分提供了 Java 和 Scala 编程语言功能的并排比较。
+
+## OOP 风格的类和方法
+
+本节提供了与 OOP 风格的类和方法相关的特性的比较。
+
+### 注释：
+
+
+
+
+
+### OOP 风格类，主构造函数：
+
+Scala不遵循JavaBeans标准，因此我们在这里展示的Java代码
+与它后面的Scala代码等效，而不是显示以JavaBeans风格编写
+的Java代码。
+
+
+
+
+
+### 辅助构造函数：
+
+
+
+
+
+### 类默认是封闭的：
+“Plan for inheritance or else forbid it.”
+
+
+
+
+
+### 为扩展开放的类：
+
+
+
+
+
+### 单行方法：
+
+
+
+
+
+### 多行方法：
+
+
+
+
+
+### 不可变字段：
+
+
+
+
+
+### 可变字段：
+
+
+
+
+
+## 接口、trait 和继承
+
+本节将Java接口与Scala trait 进行比较，包括类如何扩展接口和 trait。
+
+### 接口/trait：
+
+
+
+
+
+### 简单接口：
+
+
+
+
+
+### 有实体方法的接口：
+
+
+
+
+
+### 继承：
+
+
+
+
+
+### 扩展多个接口
+
+这些接口和特征具有具体的、已实现的方法（默认方法）：
+
+
+
+
+
+### 混搭：
+
+
+
+
+
+## 控制结构
+
+本节比较在 Java 和 Scala 中的[控制结构][control]。
+
+### `if` 语句，单行：
+
+
+
+
+
+### `if` 语句，多行：
+
+
+
+
+
+### if, else if, else:
+
+
+
+
+
+### `if` 作为方法体：
+
+
+
+
+
+### 从 `if` 返回值：
+
+在 Java 中调用_三元运算符_：
+
+
+
+
+
+### `while` 循环：
+
+
+
+
+
+### `for` 循环，单行：
+
+
+
+
+
+### `for` 循环，多行：
+
+
+
+
+
+### `for` 循环，多生成器：
+
+
+
+
+
+### 带守卫（`if`）表达式的生成器：
+
+
+
+
+
+### `for` comprehension:
+
+
+
+
+
+### switch/match:
+
+
+
+
+
+### switch/match, 每个情况下多个条件：
+
+
+
+
+
+### try/catch/finally:
+
+
+
+
+
+## 集合类
+
+本节比较 Java 和 Scala 里的[集合类][collections-classes]。
+
+### 不可变集合类
+
+如何创建不可变集合实例的例子。
+
+### Sequences:
+
+
+
+
+
+### Sets:
+
+
+
+
+
+### Maps:
+
+
+
+
+
+### 可变集合类
+
+Scala 在其 _scala.collection.mutable_ 包中有可变集合类，例如 `ArrayBuffer`、`Map` 和 `Set`。
+在 [导入它们][imports] 到当前作用域之后，创建它们就像刚刚显示的不可变 `List`、`Vector`、`Map` 和 `Set` 示例一样。
+
+Scala 还有一个 `Array` 类，您可以将其视为 Java `array` 原始类型的包装器。
+一个 Scala `Array[A]` 映射到一个 Java `A[]`，所以你可以认为这个是 Scala `Array[String]`：
+
+```scala
+val a = Array("a", "b")
+```
+
+这个追溯到 Java 的 `String[]`:
+
+```java
+String[] a = {"a", "b"};
+```
+
+但是，Scala `Array` 还具有您期望在 Scala 集合中使用的所有函数方法，包括 `map` 和 `filter`：
+
+```scala
+val nums = Array(1, 2, 3, 4, 5)
+val doubledNums = nums.map(_ * 2)
+val 过滤Nums = nums.filter(_ > 2)
+```
+
+因为 Scala `Array` 的表示方式与 Java `array` 相同，所以您可以轻松地在 Scala 代码中使用返回数组的 Java 方法。
+
+> 尽管讨论了 `Array`，但请记住，在 Scala 中通常有可能更适合的 `Array` 替代品。
+> 数组对于与其他语言（Java、JavaScript）的互操作很有用，并且在编写需要从底层平台获得最大性能的低级代码时也很有用。但总的来说，当你需要使用序列时，Scala 的习惯用法是更喜欢像 `Vector` 和 `List` 这样的不可变序列，然后在你真的需要可变序列时使用 `ArrayBuffer`。
+
+您还可以使用 Scala `CollectionConverters` 对象在 Java 和 Scala 集合类之间进行转换。
+在不同的包中有两个对象，一个用于从 Java 转换为 Scala，另一个用于从 Scala 转换为 Java。
+下表显示了可能的转换：
+
+
+
+
+
+## 集合类的方法
+
+由于能够将 Java 集合视为流，Java 和 Scala 现在可以使用许多相同的通用函数方法：
+
+- `map`
+- `filter`
+- `forEach`/`foreach`
+- `findFirst`/`find`
+- `reduce`
+
+如果您习惯在 Java 中将这些方法与 lambda 表达式一起使用，您会发现在 Scala 的 [集合类][collections-classes] 上使用相同的方法很容易。
+
+Scala 也有_数十个_其他 [集合方法][collections-methods]，包括 `head`、`tail`、`drop`、`take`、`distinct`、`flatten` 等等。
+起初你可能想知道为什么会有这么多方法，但是在使用 Scala 之后你会意识到_因为_有这些方法，你很少需要再编写自定义的 `for` 循环了。
+
+（这也意味着你也很少需要_读_自定义的 `for` 循环。
+因为开发人员倾向于在_读_代码上花费的时间是_编写_代码的十倍，这很重要。）
+
+## 元组
+
+Java 元组是这样创建的：
+
+```scala
+Pair pair =
+ new Pair("Eleven", 11);
+
+Triplet triplet =
+ Triplet.with("Eleven", 11, 11.0);
+Quartet triplet =
+ Quartet.with("Eleven", 11, 11.0, new Person("Eleven"));
+```
+
+其他 Java 元组名称是 Quintet、Sextet、Septet、Octet、Ennead、Decade。
+
+Scala 中任何大小的元组都是通过将值放在括号内来创建的，如下所示：
+
+```scala
+val a = ("eleven")
+val b = ("eleven", 11)
+val c = ("eleven", 11, 11.0)
+val d = ("eleven", 11, 11.0, Person("Eleven"))
+```
+
+## 枚举
+
+本节比较 Java 和 Scala 中的枚举。
+
+### 基本枚举：
+
+
+
+
+
+### 参数化的枚举：
+
+
+
+
+
+### 用户定义的枚举成员：
+
+
+
+
+
+## 异常和错误处理
+
+本节介绍 Java 和 Scala 中的异常处理之间的差异。
+
+### Java 使用检查异常
+
+Java 使用检查的异常，因此在 Java 代码中，您历来编写过 `try`/`catch`/`finally` 块，以及方法上的 `throws` 子句：
+
+```scala
+public int makeInt(String s)
+throws NumberFormatException {
+ // code here to convert a String to an int
+}
+```
+
+### Scala 不使用检查异常
+
+Scala 的习惯用法是_不_使用这样的检查异常。
+在处理可能抛出异常的代码时，您可以使用 `try`/`catch`/`finally` 块从抛出异常的代码中捕获异常，但是如何从那里开始的方式是不同的。
+
+解释这一点的最好方法是说 Scala 代码是由具有返回值的_表达式_组成的。
+其结果是，最终你写代就像写一系列代数表达式：
+
+```scala
+val a = f(x)
+val b = g(a,z)
+val c = h(b,y)
+```
+
+这很好，它只是代数。
+您创建方程来解决小问题，然后组合方程来解决更大的问题。
+
+非常重要的是——正如你在代数课程中所记得的那样——代数表达式不会短路——它们不会抛出会破坏一系列方程的异常。
+
+因此，在 Scala 中，我们的方法不会抛出异常。
+相反，它们返回像 `Option` 这样的类型。
+例如，这个 `makeInt` 方法捕获一个可能的异常并返回一个 `Option` 值：
+
+```scala
+def makeInt(s: String): Option[Int] =
+ try
+ Some(s.toInt)
+ catch
+ case e: NumberFormatException => None
+```
+
+Scala `Option` 类似于 Java `Optional` 类。
+如图所示，如果 string 到 int 的转换成功，则在 `Some` 值中返回 `Int`，如果失败，则返回 `None` 值。
+`Some` 和 `None` 是 `Option` 的子类型，因此该方法被声明为返回 `Option[Int]` 类型。
+
+当您有一个 `Option` 值时，例如 `makeInt` 返回的值，有很多方法可以使用它，具体取决于您的需要。
+此代码显示了一种可能的方法：
+
+```scala
+makeInt(aString) match
+ case Some(i) => println(s"Int i = $i")
+ case None => println(s"Could not convert $aString to an Int.")
+```
+
+`Option` 在 Scala 中很常用，它内置在标准库的许多类中。
+其他类似的类的集合，例如 Try/Success/Failure 和 Either/Left/Right，提供了更大的灵活性。
+
+有关在 Scala 中处理错误和异常的更多信息，请参阅 [函数式错误处理][error-handling] 部分。
+
+## Scala 独有的概念
+
+以上就是 Java 和 Scala 语言的比较。
+
+Scala 中还有其他一些概念目前在 Java 11 中是没有的。
+这包括：
+
+- 与 Scala 的 [上下文抽象][contextual] 相关的一切
+- 几个 Scala 方法特性：
+ - 多参数列表
+ - 默认参数值
+ - 调用方法时使用命名参数
+- 样例类（如 Java 14 中的“记录”）、样例对象以及伴生类和对象（参见 [领域建模][modeling-intro]）一章
+- 创建自己的控制结构和 DSL 的能力
+- [顶级定义][toplevel]
+- 模式匹配
+- `match` 表达式的高级特性
+- 类型 lambdas
+- trait参数
+- [不透明类型别名][opaque]
+- [多元相等性][equality]
+- [类型类][type-classes]
+- 中缀方法
+- 宏和元编程
+
+
+[collections-classes]: {% link _zh-cn/overviews/scala3-book/collections-classes.md %}
+[collections-methods]: {% link _zh-cn/overviews/scala3-book/collections-methods.md %}
+[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %}
+[equality]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %}
+[error-handling]: {% link _zh-cn/overviews/scala3-book/fp-functional-error-handling.md %}
+[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}
+[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %}
+[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %}
+[imports]: {% link _zh-cn/overviews/scala3-book/packaging-imports.md %}
+[modeling-intro]: {% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %}
+[modeling-oop]: {% link _zh-cn/overviews/scala3-book/domain-modeling-oop.md %}
+[opaque]: {% link _zh-cn/overviews/scala3-book/types-opaque-types.md %}
+[tools]: {% link _zh-cn/overviews/scala3-book/scala-tools.md %}
+[toplevel]: {% link _zh-cn/overviews/scala3-book/taste-toplevel-definitions.md %}
+[type-classes]: {% link _zh-cn/overviews/scala3-book/ca-type-classes.md %}
+
+[concurrency]: {% link _zh-cn/overviews/scala3-book/concurrency.md %}
+[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %}
+[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %}
+[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %}
+[intersection-types]: {% link _zh-cn/overviews/scala3-book/types-intersection.md %}
+[modeling-fp]: {% link _zh-cn/overviews/scala3-book/domain-modeling-fp.md %}
+[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %}
+[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %}
+
+
diff --git a/_zh-cn/overviews/scala3-book/scala-for-javascript-devs.md b/_zh-cn/overviews/scala3-book/scala-for-javascript-devs.md
new file mode 100644
index 0000000000..0ec0816eed
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/scala-for-javascript-devs.md
@@ -0,0 +1,1336 @@
+---
+title: Scala for JavaScript Developers
+type: chapter
+description: This chapter provides an introduction to Scala 3 for JavaScript developers
+language: zh-cn
+num: 74
+previous-page: scala-for-java-devs
+next-page: scala-for-python-devs
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+{% include_relative scala4x.css %}
+
+ //
+
+ |
+
+ //
+
+ |
+
+ class Person {
+
+ |
+
+ class Person (
+
+ |
+
+ public class Person {
+
+ |
+
+ class Person (
+
+ |
+
+ final class Person
+ |
+
+ class Person
+ |
+
+ class Person
+ |
+
+ open class Person
+ |
+
+ public int add(int a, int b) {
+
+ |
+
+ def add(a: Int, b: Int): Int = a + b
+ |
+
+ public void walkThenRun() {
+
+ |
+
+ def walkThenRun() =
+
+ |
+
+ final int i = 1;
+ |
+
+ val i = 1
+ |
+
+ int i = 1;
+
+ |
+
+ var i = 1
+ |
+
+ public interface Marker;
+ |
+
+ trait Marker
+ |
+
+ public interface Adder {
+
+ |
+
+ trait Adder:
+
+ |
+
+ public interface Adder {
+
+ |
+
+ trait Adder:
+
+ |
+
+ class Dog extends Animal implements HasLegs, HasTail
+ |
+
+ class Dog extends Animal, HasLegs, HasTail
+ |
+
+ interface Adder {
+
+ |
+
+ trait Adder:
+
+ |
+
| + N/A + | +
+ class DavidBanner
+
+ |
+
+ if (x == 1) { System.out.println(1); }
+ |
+
+ if x == 1 then println(x)
+ |
+
+ if (x == 1) {
+
+ |
+
+ if x == 1 then
+
+ |
+
+ if (x < 0) {
+
+ |
+
+ if x < 0 then
+
+ |
+
+ public int min(int a, int b) {
+
+ |
+
+ def min(a: Int, b: Int): Int =
+
+ |
+
+ int minVal = (a < b) ? a : b;
+ |
+
+ val minValue = if a < b then a else b
+ |
+
+ while (i < 3) {
+
+ |
+
+ while i < 3 do
+
+ |
+
+ for (int i: ints) {
+
+ |
+
+ //preferred
+
+ |
+
+ for (int i: ints) {
+
+ |
+
+ for
+
+ |
+
+ for (int i: ints1) {
+
+ |
+
+ for
+
+ |
+
+ List ints =
+
+ |
+
+ for
+
+ |
+
| + N/A + | +
+ val list =
+
+ |
+
+ String monthAsString = "";
+
+ |
+
+ val monthAsString = day match
+
+ |
+
+ String numAsString = "";
+
+ |
+
+ val numAsString = i match
+
+ |
+
+ try {
+
+ |
+
+ try
+
+ |
+
+ List strings = List.of("a", "b", "c");
+ |
+
+ val strings = List("a", "b", "c")
+
+ |
+
+ Set set = Set.of("a", "b", "c");
+ |
+
+ val set = Set("a", "b", "c")
+ |
+
+ Map map = Map.of(
+
+ |
+
+ val map = Map(
+
+ |
+
| Java | +Scala | +
|---|---|
| java.util.Collection | +scala.collection.Iterable | +
| java.util.List | +scala.collection.mutable.Buffer | +
| java.util.Set | +scala.collection.mutable.Set | +
| java.util.Map | +scala.collection.mutable.Map | +
| java.util.concurrent.ConcurrentMap | +scala.collection.mutable.ConcurrentMap | +
| java.util.Dictionary | +scala.collection.mutable.Map | +
+ enum Color {
+
+ |
+
+ enum Color:
+
+ |
+
+ enum Color {
+
+ |
+
+ enum Color(val rgb: Int):
+
+ |
+
+ enum Planet {
+
+ |
+
+ enum Planet(
+
+ |
+
+
+此页面提供了 JavaScript 和 Scala 编程语言之间的比较。
+它适用于了解 JavaScript 并希望了解 Scala 的程序员，特别是通过查看 JavaScript 语言功能与 Scala 比较的示例。
+
+## 概述
+
+本节对以下各节进行了相对简短的介绍和总结。
+它从高层次上介绍了 JavaScript 和 Scala 之间的异同，然后介绍了您在每天编写代码时会遇到的差异。
+
+### 高层次的相似性
+
+在高层次上，Scala 与 JavaScript 有以下相似之处：
+
+- 两者都被认为是高级编程语言，您不必关心指针和手动内存管理等低级概念
+- 两者都有一个相对简单、简洁的语法
+- 两者都支持 C/C++/Java 风格的花括号语法，用于编写方法和其他代码块
+- 两者都包括面向对象编程 (OOP) 的特性（如类）
+- 两者都包含用于 [函数式编程][fp-intro] (FP) 的（如 lambda）
+- JavaScript 在浏览器和 Node.js 等其他环境中运行。
+ Scala 的 [Scala.js](https://www.scala-js.org) 风格以 JavaScript 为目标，因此 Scala 程序可以在相同的环境中运行。
+- 开发人员使用 [Node.js](https://nodejs.org) 在 JavaScript 和 Scala 中编写服务器端应用程序； [Play Framework](https://www.playframework.com/) 之类的项目也可以让您在 Scala 中编写服务器端应用程序
+- 两种语言都有相似的 `if` 语句、`while` 循环和 `for` 循环
+- 从 [在这个 Scala.js 页面](https://www.scala-js.org/libraries/index.html) 开始，您会发现许多支持 React、Angular、jQuery 和许多其他 JavaScript 和Scala 库
+- JavaScript 对象是可变的；以命令式风格编写时，Scala 对象_可以_是可变的
+- JavaScript 和 Scala 都支持 _promises_ 作为处理异步计算结果的一种方式（[Scala concurrency][concurrency] 使用期货和承诺）
+
+### 高层次差异
+
+同样在高层次上，JavaScript 和 Scala 之间的一些区别是：
+
+- JavaScript 是动态类型的，Scala 是静态类型的
+ - 尽管 Scala 是静态类型的，但类型推断之类的特性让它感觉像是一种动态语言（正如您将在下面的示例中看到的那样）
+- Scala 惯用语默认支持不变性：鼓励您使用不可变变量和不可变集合
+- Scala 语法简洁易读；我们称之为_表现力_
+- Scala 是一种纯 OOP 语言，因此每个对象都是类的一个实例，而像运算符一样的符号 `+` 和 `+=` 是真正的方法；这意味着您可以创建自己的方法作为运算符
+- 作为一种纯 OOP 语言和纯 FP 语言，Scala 鼓励 OOP 和 FP 的融合，具有用于逻辑的函数和用于模块化的不可变对象
+- Scala 拥有最先进的第三方开源函数式编程库
+- Scala 中的一切都是一个_表达式_：像 `if` 语句、`for` 循环、`match` 表达式，甚至 `try`/`catch` 表达式都有返回值
+- [Scala Native](https://scala-native.org/) 项目让您可以编写“系统”级代码，也可以编译为本机可执行文件
+
+### 编程层次差异
+
+在较低的层次上，这些是您在编写代码时每天都会看到的一些差异：
+
+- Scala 变量和参数使用 `val`（不可变，如 JavaScript `const`）或 `var`（可变，如 JavaScript `var` 或 `let`）定义
+- Scala 不在行尾使用分号
+- Scala 是静态类型的，尽管在许多情况下您不需要声明类型
+- Scala 使用 trait 作为接口并创建_混搭_
+- 除了简单的 `for` 循环之外，Scala 还具有强大的 `for` comprehensions，可以根据您的算法产生结果
+- 模式匹配和 `match` 表达式将改变你编写代码的方式
+- Scala 的 Scala 的 [上下文抽象][contextual] 和 _术语推导_ 提供了一系列特性：
+ - [扩展方法][extension-methods] 允许您在不破坏模块化的情况下向封闭类添加新功能，方法是仅在特定范围内可用（与猴子补丁相反，它会污染代码的其他区域）
+ - [给实例][givens] 让您定义编译器可以用来为您合成代码的术语
+ - 类型安全和[多元等式][multiversal]让您将相等比较——在编译时——仅限于那些有意义的比较
+- 由于名称参数、中缀符号、可选括号、扩展方法和 [高阶函数][hofs] 等功能，您可以创建自己的“控制结构”和 DSL
+- 您可以在本书中阅读到许多其他好东西：样例类、伴生类和对象、宏、[联合][union-type]和[交集][intersection-types]类型、多参数列表、命名参数等
+
+## 变量和类型
+
+### 注释
+
+
+
+
+
+### 可变变量
+
+
+
+
+
+### 不可变变量
+
+
+
+
+
+Scala 的经验法则是使用 `val` 声明变量，除非有特定原因需要可变变量。
+
+## 命名标准
+
+JavaScript 和 Scala 通常使用相同的 _CamelCase_ 命名标准。
+变量命名为 `myVariableName`，方法命名为 `lastIndexOf`，类和对象命名为 `Animal` 和 `PrintedBook` 。
+
+## 字符串
+
+JavaScript 和 Scala 中字符串的许多用法相似，但 Scala 仅对简单字符串使用双引号，对多行字符串使用三引号。
+
+### 字符串基础
+
+
+
+
+
+### 插入
+
+
+
+
+
+### 带插入的多行字符串
+
+
+
+
+
+JavaScript 和 Scala 也有类似的处理字符串的方法，包括 `charAt`、`concat`、`indexOf` 等等。
+`\n`、`\f`、`\t` 等转义字符在两种语言中也是相同的。
+
+## 数字和算术
+
+JavaScript 和 Scala 之间的数字运算符很相似。
+最大的不同是 Scala 不提供 `++` 和 `--` 运算符。
+
+### 数字运算符：
+
+
+
+
+
+### 自增和自减：
+
+
+
+
+
+或许最大的区别在于像`+`和`-`这样的“操作符”在Scala中实际上是_方法_，而不是操作符。
+Scala 数字也有这些相关的方法：
+
+```scala
+var a = 2
+a *= 2 // 4
+a /= 2 // 2
+```
+
+Scala 的 `Double` 类型最接近于 JavaScript 的默认 `number` 类型，
+`Int` 表示有符号的 32 位整数值，而 `BigInt` 对应于 JavaScript 的 `bigint`。
+
+这些是 Scala `Int` 和 `Double` 值。
+请注意，类型不必显式声明：
+
+```scala
+val i = 1 // Int
+val d = 1.1 // Double
+```
+
+你可以按需要使用其它数字类型：
+
+```scala
+val a: Byte = 0 // Byte = 0
+val a: Double = 0 // Double = 0.0
+val a: Float = 0 // Float = 0.0
+val a: Int = 0 // Int = 0
+val a: Long = 0 // Long = 0
+val a: Short = 0 // Short = 0
+
+val x = BigInt(1_234_456_789)
+val y = BigDecimal(1_234_456.890)
+```
+
+### 布尔值
+
+两个语言都在布尔值中用 `true` 和 `false`。
+
+
+
+
+
+## 日期
+
+日期是两种语言中另一种常用的类型。
+
+### 获取当前日期：
+
+
+
+
+
+### 指定不同的日期：
+
+
+
+
+
+在这种情况下，Scala 使用 Java 附带的日期和时间类。
+JavaScript 和 Scala 之间的许多日期/时间方法是相似的。
+有关详细信息，请参阅 [_java.time_ 包](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/package-summary.html)。
+
+## 函数
+
+在 JavaScript 和 Scala 中，函数都是对象，因此它们的功能相似，但它们的语法和术语略有不同。
+
+### 命名函数，一行：
+
+
+
+
+
+### 命名函数，多行：
+
+
+
+
+
+在 Scala 中，显示 `Int` 返回类型是可选的。
+它_不_显示在 `add` 示例中，而_是_显示在 `addAndDouble` 示例中，因此您可以看到这两种方法。
+
+## 匿名函数
+
+JavaScript 和 Scala 都允许您定义匿名函数，您可以将其传递给其他函数和方法。
+
+### 箭头和匿名函数
+
+
+
+
+
+在 Scala 中，您很少使用所示的第一种语法来定义函数。
+相反，您经常在使用点定义匿名函数。
+许多集合方法是 [高阶函数][hofs]并接受函数参数，因此您编写如下代码：
+
+```scala
+// map method, long form
+List(1,2,3).map(i => i * 10) // List(10,20,30)
+
+// map, short form (which is more commonly used)
+List(1,2,3).map(_ * 10) // List(10,20,30)
+
+// filter, short form
+List(1,2,3).filter(_ < 3) // List(1,2)
+
+// filter and then map
+List(1,2,3,4,5).filter(_ < 3).map(_ * 10) // List(10, 20)
+```
+
+## 类
+
+Scala 既有类也有样例类。
+_类_ 与 JavaScript 类相似，通常用于 [OOP 风格应用程序][modeling-oop]（尽管它们也可以在 FP 代码中使用），并且 _样例类_有附加的特性，这让它在 [FP 风格应用][modeling-fp]中很有用。
+
+下面的例子展示了如何创建几个类型作为枚举，然后定义一个 OOP 风格的 `Pizza` 类。
+最后，创建并使用了一个 `Pizza` 实例：
+
+```scala
+// create some enumerations that the Pizza class will use
+enum CrustSize:
+ case Small, Medium, Large
+
+enum CrustType:
+ case Thin, Thick, Regular
+
+enum Topping:
+ case Cheese, Pepperoni, BlackOlives, GreenOlives, Onions
+
+// import those enumerations and the ArrayBuffer,
+// so the Pizza class can use them
+import CrustSize.*
+import CrustType.*
+import Topping.*
+import scala.collection.mutable.ArrayBuffer
+
+// define an OOP style Pizza class
+class Pizza(
+ var crustSize: CrustSize,
+ var crustType: CrustType
+):
+
+ private val toppings = ArrayBuffer[Topping]()
+
+ def addTopping(t: Topping): Unit =
+ toppings += t
+
+ def removeTopping(t: Topping): Unit =
+ toppings -= t
+
+ def removeAllToppings(): Unit =
+ toppings.clear()
+
+ override def toString(): String =
+ s"""
+ |Pizza:
+ | Crust Size: ${crustSize}
+ | Crust Type: ${crustType}
+ | Toppings: ${toppings}
+ """.stripMargin
+
+end Pizza
+
+// create a Pizza instance
+val p = Pizza(Small, Thin)
+
+// change the crust
+p.crustSize = Large
+p.crustType = Thick
+
+// add and remove toppings
+p.addTopping(Cheese)
+p.addTopping(Pepperoni)
+p.addTopping(BlackOlives)
+p.removeTopping(Pepperoni)
+
+// print the pizza, which uses its `toString` method
+println(p)
+```
+
+## 接口、trait 和继承
+
+Scala 使用 trait 作为接口，也可以创建混搭。
+trait 可以有抽象和具体的成员，包括方法和字段。
+
+这个例子展示了如何定义两个 traits，创建一个扩展和实现这些 traits 的类，然后创建和使用该类的一个实例：
+
+```scala
+trait HasLegs:
+ def numLegs: Int
+ def walk(): Unit
+ def stop() = println("Stopped walking")
+
+trait HasTail:
+ def wagTail(): Unit
+ def stopTail(): Unit
+
+class Dog(var name: String) extends HasLegs, HasTail:
+ val numLegs = 4
+ def walk() = println("I’m walking")
+ def wagTail() = println("⎞⎜⎛ ⎞⎜⎛")
+ def stopTail() = println("Tail is stopped")
+ override def toString = s"$name is a Dog"
+
+// create a Dog instance
+val d = Dog("Rover")
+
+// use the class’s attributes and behaviors
+println(d.numLegs) // 4
+d.wagTail() // "⎞⎜⎛ ⎞⎜⎛"
+d.walk() // "I’m walking"
+```
+
+## 控制结构
+
+除了在 JavaScript 中使用 `===` 和 `!==` 之外，比较和逻辑运算符在 JavaScript 和 Scala 中几乎相同。
+
+{% comment %}
+TODO: Sébastien mentioned that `===` is closest to `eql` in Scala. Update this area.
+{% endcomment %}
+
+### 比较运算符
+
+
+
+
+
+### 逻辑运算符
+
+
+
+
+
+## if/then/else 表达式
+
+JavaScript和 Scala if/then/else 语句相似。
+在 Scala 2 中它们几乎相同，但在 Scala 3 中，花括号不再是必需的（尽管它们仍然可以使用）。
+
+### `if` 语句，单行：
+
+
+
+
+
+### `if` 语句，多行：
+
+
+
+
+
+### if, else if, else:
+
+
+
+
+
+### 从 `if` 返回值：
+
+JavaScript 使用三元运算符，Scala 像往常一样使用它的 `if` 表达式：
+
+
+
+
+
+### `if` 作为方法体：
+
+Scala 方法往往很短，您可以轻松地使用 `if` 作为方法体：
+
+
+
+
+
+在 Scala 3 中，如果您愿意，您仍然可以使用“花括号”样式。
+例如，您可以像这样编写 if/else-if/else 表达式：
+
+```scala
+if (i == 0) {
+ println(0)
+} else if (i == 1) {
+ println(1)
+} else {
+ println("other")
+}
+```
+
+## 循环
+
+JavaScript 和 Scala 都有 `while` 循环和 `for` 循环。
+Scala 曾经有 do/while 循环，但它们已从语言中删除。
+
+### `while` 循环：
+
+
+
+
+
+如果你愿意，Scala 代码也可以写成这样：
+
+```scala
+var i = 0
+while (i < 3) {
+ println(i)
+ i += 1
+}
+```
+
+以下示例展示了 JavaScript 和 Scala 中的“for”循环。
+他们假设您可以使用这些集合：
+
+```scala
+// JavaScript
+let nums = [1, 2, 3];
+
+// Scala
+val nums = List(1, 2, 3)
+```
+
+### `for` 循环，单行：
+
+
+
+
+
+### `for` 循环，在循环体内多行
+
+
+
+
+
+### 在 `for` 循环中有多个生成器
+
+
+
+
+
+### 带守卫的生成器
+
+_守卫_是 `for` 表达式中的 `if` 表达式的名称。
+
+
+
+
+
+### `for` comprehension
+
+`for` comprehension 是一个 `for` 循环，它使用 `yield` 返回（产生）一个值。 它们经常在 Scala 中使用。
+
+
+
+
+
+## switch & match
+
+JavaScript 有 `switch` 语句，Scala 有 `match` 表达式。
+就像 Scala 中的所有其他东西一样，这些确实是_表达式_，这意味着它们返回一个结果：
+
+```scala
+val day = 1
+
+// later in the code ...
+val monthAsString = day match
+ case 1 => "January"
+ case 2 => "February"
+ case _ => "Other"
+```
+
+`match` 表达式可以在每个 `case` 语句中处理多个匹配项：
+
+```scala
+val numAsString = i match
+ case 1 | 3 | 5 | 7 | 9 => "odd"
+ case 2 | 4 | 6 | 8 | 10 => "even"
+ case _ => "too big"
+```
+
+它们也可以用于方法体：
+
+```scala
+def isTruthy(a: Matchable) = a match
+ case 0 | "" => false
+ case _ => true
+
+def isPerson(x: Matchable): Boolean = x match
+ case p: Person => true
+ case _ => false
+```
+
+`match` 表达式有许多其他模式匹配选项。
+
+## 集合类
+
+Scala 有不同的 [集合类][collections-classes] 来满足不同的需求。
+
+常见的_不可变_序列是：
+
+- `List`
+- `Vector`
+
+常见的_可变_序列是：
+
+- `Array`
+- `ArrayBuffer`
+
+Scala 还有可变和不可变的 Map 和 Set。
+
+这是创建常见 Scala 集合类型的方式：
+
+```scala
+val strings = List("a", "b", "c")
+val strings = Vector("a", "b", "c")
+val strings = ArrayBuffer("a", "b", "c")
+
+val set = Set("a", "b", "a") // result: Set("a", "b")
+val map = Map(
+ "a" -> 1,
+ "b" -> 2,
+ "c" -> 3
+)
+```
+
+### 集合上的方法
+
+以下示例展示了使用 Scala 集合的许多不同方法。
+
+### 填充列表：
+
+```scala
+// to, until
+(1 to 5).toList // List(1, 2, 3, 4, 5)
+(1 until 5).toList // List(1, 2, 3, 4)
+
+(1 to 10 by 2).toList // List(1, 3, 5, 7, 9)
+(1 until 10 by 2).toList // List(1, 3, 5, 7, 9)
+(1 to 10).by(2).toList // List(1, 3, 5, 7, 9)
+
+('d' to 'h').toList // List(d, e, f, g, h)
+('d' until 'h').toList // List(d, e, f, g)
+('a' to 'f').by(2).toList // List(a, c, e)
+
+// range method
+List.range(1, 3) // List(1, 2)
+List.range(1, 6, 2) // List(1, 3, 5)
+
+List.fill(3)("foo") // List(foo, foo, foo)
+List.tabulate(3)(n => n * n) // List(0, 1, 4)
+List.tabulate(4)(n => n * n) // List(0, 1, 4, 9)
+```
+
+### 序列上的函数式方法：
+
+```scala
+// these examples use a List, but they’re the same with Vector
+val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10)
+a.contains(20) // true
+a.distinct // List(10, 20, 30, 40)
+a.drop(2) // List(30, 40, 10)
+a.dropRight(2) // List(10, 20, 30)
+a.dropWhile(_ < 25) // List(30, 40, 10)
+a.filter(_ < 25) // List(10, 20, 10)
+a.filter(_ > 100) // List()
+a.find(_ > 20) // Some(30)
+a.head // 10
+a.headOption // Some(10)
+a.init // List(10, 20, 30, 40)
+a.last // 10
+a.lastOption // Some(10)
+a.slice(2,4) // List(30, 40)
+a.tail // List(20, 30, 40, 10)
+a.take(3) // List(10, 20, 30)
+a.takeRight(2) // List(40, 10)
+a.takeWhile(_ < 30) // List(10, 20)
+
+// map, flatMap
+val fruits = List("apple", "pear")
+fruits.map(_.toUpperCase) // List(APPLE, PEAR)
+fruits.flatMap(_.toUpperCase) // List(A, P, P, L, E, P, E, A, R)
+
+val nums = List(10, 5, 8, 1, 7)
+nums.sorted // List(1, 5, 7, 8, 10)
+nums.sortWith(_ < _) // List(1, 5, 7, 8, 10)
+nums.sortWith(_ > _) // List(10, 8, 7, 5, 1)
+
+List(1,2,3).updated(0,10) // List(10, 2, 3)
+List(2,4).union(List(1,3)) // List(2, 4, 1, 3)
+
+// zip
+val women = List("Wilma", "Betty") // List(Wilma, Betty)
+val men = List("Fred", "Barney") // List(Fred, Barney)
+val couples = women.zip(men) // List((Wilma,Fred), (Betty,Barney))
+```
+
+Scala 有_很多_更多可供您使用的方法。
+所有这些方法的好处是：
+
+- 您不必编写自定义的 `for` 循环来解决问题
+- 当你阅读别人的代码时，你不必阅读他们自定义的 `for` 循环； 你只会找到像这样的常用方法，因此更容易阅读来自不同项目的代码
+
+### 元组
+
+当您想将多个数据类型放在同一个列表中时，JavaScript 允许您这样做：
+
+```javascript
+stuff = ["Joe", 42, 1.0];
+```
+
+在 Scala 中你这样做：
+
+```scala
+val a = ("eleven")
+val b = ("eleven", 11)
+val c = ("eleven", 11, 11.0)
+val d = ("eleven", 11, 11.0, Person("Eleven"))
+```
+
+在 Scala 中，这些类型称为元组，如图所示，它们可以包含一个或多个元素，并且元素可以具有不同的类型。
+访问它们的元素就像访问 `List`、`Vector` 或 `Array` 的元素一样：
+
+```scala
+d(0) // "eleven"
+d(1) // 11
+```
+
+### 枚举
+
+JavaScript 没有枚举，但你可以这样做：
+
+```javascript
+let Color = {
+ RED: 1,
+ GREEN: 2,
+ BLUE: 3
+};
+Object.freeze(Color);
+```
+
+在 Scala 3 中，您可以使用枚举做很多事情。
+您可以创建该代码的等效代码：
+
+```scala
+enum Color:
+ case Red, Green, Blue
+```
+
+你可以创建带参数的枚举：
+
+```scala
+enum Color(val rgb: Int):
+ case Red extends Color(0xFF0000)
+ case Green extends Color(0x00FF00)
+ case Blue extends Color(0x0000FF)
+```
+
+你也可以创建用户自定义的枚举成员：
+
+```scala
+enum Planet(mass: Double, radius: Double):
+ case Mercury extends Planet(3.303e+23, 2.4397e6)
+ case Venus extends Planet(4.869e+24,6.0518e6)
+ case Earth extends Planet(5.976e+24,6.37814e6)
+ // more planets here ...
+
+ private final val G = 6.67300E-11
+ def surfaceGravity = G * mass / (radius * radius)
+ def surfaceWeight(otherMass: Double) = otherMass * surfaceGravity
+```
+
+## Scala.js DOM 代码
+
+Scala.js 允许您编写 Scala 代码，这些代码编译为 JavaScript 代码，然后可以在浏览器中使用。
+该方法类似于 TypeScript、ReScript 和其他编译为 JavaScript 的语言。
+
+包含必要的库并在项目中导入必要的包后，编写 Scala.js 代码看起来与编写 JavaScript 代码非常相似：
+
+```scala
+// show an alert dialog on a button click
+jQuery("#hello-button").click{() =>
+ dom.window.alert("Hello, world")
+}
+
+// define a button and what should happen when it’s clicked
+val btn = button(
+ "Click me",
+ onclick := { () =>
+ dom.window.alert("Hello, world")
+ })
+
+// create two divs with css classes, an h2 element, and the button
+val content =
+ div(cls := "foo",
+ div(cls := "bar",
+ h2("Hello"),
+ btn
+ )
+ )
+
+// add the content to the DOM
+val root = dom.document.getElementById("root")
+root.innerHTML = ""
+root.appendChild(content.render)
+```
+
+请注意，尽管 Scala 是一种类型安全的语言，但在上面的代码中没有声明任何类型。
+Scala 强大的类型推断能力通常使 Scala 代码看起来像是动态类型的。
+但它是类型安全的，因此您可以在开发周期的早期捕获许多类错误。
+
+## 其他 Scala.js 资源
+
+Scala.js 网站为对使用 Scala.js 感兴趣的 JavaScript 开发人员提供了极好的教程集。
+以下是他们的一些初始教程：
+
+- [基础教程（创建第一个 Scala.js 项目）](https://www.scala-js.org/doc/tutorial/basic/)
+- [适用于 JavaScript 开发人员的 Scala.js](https://www.scala-js.org/doc/sjs-for-js/)
+- [从 ES6 到 Scala：基础](https://www.scala-js.org/doc/sjs-for-js/es6-to-scala-part1.html)
+- [从 ES6 到 Scala：集合](https://www.scala-js.org/doc/sjs-for-js/es6-to-scala-part2.html)
+- [从 ES6 到 Scala：高级](https://www.scala-js.org/doc/sjs-for-js/es6-to-scala-part3.html)
+
+## Scala 独有的概念
+
+Scala 中还有其他一些概念目前在 JavaScript 中没有等效的概念：
+
+- 几乎所有与[上下文抽象][contextual]相关的东西
+- 方法特性：
+ - 多个参数列表
+ - 调用方法时使用命名参数
+- 使用 trait 作为接口
+- 样例类
+- 伴生类和对象
+- 创建自己的[控制结构][control]和 DSL 的能力
+- `match` 表达式和模式匹配的高级功能
+- `for` comprehension
+- 中缀方法
+- 宏和元编程
+- 更多的 ...
+
+
+[collections-classes]: {% link _zh-cn/overviews/scala3-book/collections-classes.md %}
+[concurrency]: {% link _zh-cn/overviews/scala3-book/concurrency.md %}
+[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %}
+[control]: {% link _zh-cn/overviews/scala3-book/control-structures.md %}
+[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}
+[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %}
+[givens]: {% link _zh-cn/overviews/scala3-book/ca-context-parameters.md %}
+[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %}
+[intersection-types]: {% link _zh-cn/overviews/scala3-book/types-intersection.md %}
+[modeling-fp]: {% link _zh-cn/overviews/scala3-book/domain-modeling-fp.md %}
+[modeling-oop]: {% link _zh-cn/overviews/scala3-book/domain-modeling-oop.md %}
+[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %}
+[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %}
+
+
diff --git a/_zh-cn/overviews/scala3-book/scala-for-python-devs.md b/_zh-cn/overviews/scala3-book/scala-for-python-devs.md
new file mode 100644
index 0000000000..618f8de44a
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/scala-for-python-devs.md
@@ -0,0 +1,1361 @@
+---
+title: Scala for Python Developers
+type: chapter
+description: This page is for Python developers who are interested in learning about Scala 3.
+language: zh-cn
+num: 75
+previous-page: scala-for-javascript-devs
+next-page: where-next
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+{% include_relative scala4x.css %}
+
+
+ //
+
+ |
+
+ //
+
+ |
+
+ let // now preferred for mutable
+
+ |
+
+ var // used for mutable variables
+ |
+
+ const
+ |
+
+ val
+ |
+
+ // use single- or double-quotes
+
+ |
+
+ // use only double-quotes
+
+ |
+
+ let name = 'Joe';
+
+ |
+
+ val name = "Joe"
+
+ |
+
+ let name = "joe";
+
+ |
+
+ val name = "Martin Odersky"
+
+ |
+
+ let x = 1;
+
+ |
+
+ val x = 1
+
+ |
+
+ i++;
+
+ |
+
+ i += 1;
+
+ |
+
+ let a = true;
+
+ |
+
+ val a = true
+
+ |
+
+ let d = new Date();
+ |
+
+ // different ways to get the current date and time
+
+ |
+
+ let d = Date(2020, 1, 21, 1, 0, 0, 0);
+
+ |
+
+ val d = LocalDate.of(2020, 1, 21)
+
+ |
+
+ function add(a, b) {
+
+ |
+
+ // technically this is a method, not a function
+
+ |
+
+ function addAndDouble(a, b) {
+
+ |
+
+ def addAndDouble(a: Int, b: Int): Int =
+
+ |
+
+ // arrow function
+
+ |
+
+ // a function (an anonymous function assigned to a variable)
+
+ |
+
| JavaScript | +Scala | +
|---|---|
+ == |
+
+ == |
+
+ === |
+
+ == |
+
+ != |
+
+ != |
+
+ !== |
+
+ != |
+
+ > |
+
+ > |
+
+ < |
+
+ < |
+
+ >= |
+
+ >= |
+
+ <= |
+
+ <= |
+
| JavaScript | +Scala | +
|---|---|
+ &&
+
+ |
+
+ &&
+
+ |
+
+ if (x == 1) { console.log(1); }
+ |
+
+ if x == 1 then println(x)
+ |
+
+ if (x == 1) {
+
+ |
+
+ if x == 1 then
+
+ |
+
+ if (x < 0) {
+
+ |
+
+ if x < 0 then
+
+ |
+
+ let minVal = a < b ? a : b;
+ |
+
+ val minValue = if a < b then a else b
+ |
+
+ function min(a, b) {
+
+ |
+
+ def min(a: Int, b: Int): Int =
+
+ |
+
+ let i = 0;
+
+ |
+
+ var i = 0;
+
+ |
+
+ // newer syntax
+
+ |
+
+ // preferred
+
+ |
+
+ // preferred
+
+ |
+
+ // preferred
+
+ |
+
+ let str = "ab";
+
+ |
+
+ for
+
+ |
+
+ for (let i = 0; i < 10; i++) {
+
+ |
+
+ for
+
+ |
+
| + N/A + | +
+ val list =
+
+ |
+
+
+{% comment %}
+
+NOTE: Hopefully someone with more Python experience can give this a thorough review.
+
+NOTE: On this page (https://contributors.scala-lang.org/t/feedback-sought-optional-braces/4702/10), Li Haoyi comments: “Python’s success also speaks for itself; beginners certainly don’t pick Python because of performance, ease of installation, packaging, IDE support, or simplicity of the language’s runtime semantics!” I’m not a Python expert, so these points are good to know, though I don’t want to go negative in any comparisons.
+It’s more like thinking, “Python developers will appreciate Scala’s performance, ease of installation, packaging, IDE support, etc.”
+{% endcomment %}
+
+{% comment %}
+TODO: We should probably go through this document and add links to our other detail pages, when time permits.
+{% endcomment %}
+
+本节提供了 Python 和 Scala 编程语言之间的比较。
+它适用于懂得 Python 并希望了解 Scala 的程序员，特别是通过查看 Python 语言特性与 Scala 比较的示例。
+
+## 介绍
+
+在进入示例之前，第一部分提供了以下部分的相对简短的介绍和总结。
+这两种语言首先在高层次上进行比较，然后在日常编程层次上进行比较。
+
+### 高层次相似性
+
+在高层次上，Scala 与 Python 有这些*相似之处*：
+
+- 两者都是高级编程语言，您不必关心指针和手动内存管理等低级概念
+- 两者都有一个相对简单、简洁的语法
+- 两者都支持[函数式编程][fp-intro]
+- 两者都是面向对象的编程 (OOP) 语言
+- 两者都有推导：Python 有列表推导，Scala 有 `for` 推导
+- 两种语言都支持 lambdas 和 [高阶函数][hofs]
+- 两者都可以与 [Apache Spark](https://spark.apache.org) 一起用于大数据处理
+- 两者都有很多很棒的库
+
+### 高层次差异
+
+同样在高层次上，Python 和 Scala 之间的_差异_是：
+
+- Python 是动态类型的，Scala 是静态类型的
+ - 虽然它是静态类型的，但 Scala 的类型推断等特性让它感觉像是一门动态语言
+- Python 被解释，Scala 代码被编译成 _.class_ 文件，并在 Java 虚拟机 (JVM) 上运行
+- 除了在 JVM 上运行之外，[Scala.js](https://www.scala-js.org) 项目允许您使用 Scala 作为 JavaScript 替代品
+- [Scala Native](https://scala-native.org/) 项目可让您编写“系统”级代码，并编译为本机可执行文件
+- Scala 中的一切都是一个_表达式_：像 `if` 语句、`for` 循环、`match` 表达式，甚至 `try`/`catch` 表达式都有返回值
+- Scala 习惯默认不变性：鼓励您使用不可变变量和不可变集合
+- Scala 对[并发和并行编程][concurrency]有很好的支持
+
+### 编程层次相似性
+
+本节介绍您在日常编写代码时会看到 Python 和 Scala 之间的相似之处：
+
+- Scala 的类型推断常常让人感觉像是一种动态类型语言
+- 两种语言都不使用分号来结束表达式
+- 两种语言都支持使用重要的缩进而不是大括号和圆括号
+- 定义方法的语法类似
+- 两者都有列表、字典（映射）、集合和元组
+- 两者都有映射和过滤的推导
+- 使用 Scala 3 的[顶级定义][toplevel]，您可以将方法、字段和其他定义放在任何地方
+ - 一个区别是 Python 甚至可以在不声明单个方法的情况下运行，而 Scala 3 不能在顶层做_所有事_；例如，启动 Scala 应用程序需要一个 [main 方法][main-method] (`@main def`)
+
+### 编程层次差异
+
+同样在编程级别，这些是您在编写代码时每天都会看到的一些差异：
+
+- 在 Scala 中编程感觉非常一致：
+ - `val` 和 `var` 字段用于定义字段和参数
+ - 列表、映射、集合和元组都以类似方式创建和访问；例如，括号用于创建所有类型---`List(1,2,3)`, `Set(1,2,3)`, `Map(1->"one")`---就像创建任何其他 Scala 类
+ - [集合类][collections-classes] 通常具有大部分相同的高阶函数
+ - 模式匹配在整个语言中一致使用
+ - 用于定义传递给方法的函数的语法与用于定义匿名函数的语法相同
+- Scala 变量和参数使用 `val`（不可变）或 `var`（可变）关键字定义
+- Scala 习惯用法更喜欢不可变的数据结构
+- Scala 通过 IntelliJ IDEA 和 Microsoft VS Code 提供了极好的 IDE 支持
+- 注释：Python 使用 `#` 表示注释； Scala 使用 C、C++ 和 Java 样式：`//`、`/*...*/` 和 `/**...*/`
+- 命名约定：Python 标准是使用下划线，例如 `my_list`； Scala 使用 `myList`
+- Scala 是静态类型的，因此您可以声明方法参数、方法返回值和其他地方的类型
+- 模式匹配和 `match` 表达式在 Scala 中被广泛使用（并且会改变你编写代码的方式）
+- Scala 中大量使用 trait；接口和抽象类在 Python 中使用较少
+- Scala 的 [上下文抽象][contextual] 和 _术语推导_提供了一系列不同的特性：
+ - [扩展方法][extension-method]让您使用清晰的语法轻松地向类添加新功能
+ - [多元等式][multiversal] 让您限制相等比较---在编译时——只有那些有意义的比较
+- Scala 拥有最先进的开源函数式编程库（参见 [“Awesome Scala” 列表](https://github.com/lauris/awesome-scala)）
+- 借助对象、按名称参数、中缀表示法、可选括号、扩展方法、高阶函数等功能，您可以创建自己的“控制结构”和 DSL
+- Scala 代码可以在 JVM 中运行，甚至可以编译为原生代码（使用 [Scala Native](https://github.com/scala-native/scala-native) 和 [GraalVM](https://www.graalvm) .org)) 实现高性能
+- 许多其他好东西：样例类、伴生类和对象、宏、[联合][union-types] 和 [交集][intersection-types] 类型、[顶级定义][toplevel]、数字字面量、多参数列表和更多的
+
+### 特性比较示例
+
+鉴于该介绍，以下部分提供了 Python 和 Scala 编程语言功能的并排比较。
+
+{% comment %}
+TODO: Update the Python examples to use four spaces. I started to do this, but then thought it would be better to do that in a separate PR.
+{% endcomment %}
+
+## 注释
+
+Python 使用 `#` 表示注释，而 Scala 的注释语法与 C、C++ 和 Java 等语言相同：
+
+
+
+
+
+## 变量赋值
+
+这些例子演示了如何在 Python 和 Scala 中创建变量。
+
+### 创建整数和字符串变量：
+
+
+
+
+
+### 列表：
+
+
+
+
+
+### 字典/映射：
+
+
+
+
+
+### 集合：
+
+
+
+
+
+### 元组：
+
+
+
+
+
+如果 Scala 字段是可变的，请使用 `var` 而不是 `val` 来定义变量：
+
+```scala
+var x = 1
+x += 1
+```
+
+然而，Scala 中的经验法则是始终使用 `val`，除非变量确实需要被改变。
+
+## OOP 风格的类和方法
+
+本节比较了与 OOP 风格的类和方法相关的特性。
+
+### OOP 风格类，主构造函数：
+
+
+
+
+
+### 创建和使用实例：
+
+
+
+
+
+### 单行方法：
+
+
+
+
+
+### 多行方法：
+
+
+
+
+
+## 接口，traits，和继承
+
+如果您熟悉 Java 8 和更新版本，Scala trait 类似于那些 Java 接口。
+Traits 在 Scala 中一直使用，而 Python 接口和抽象类的使用频率要低得多。
+因此，与其试图比较两者，不如用这个例子来展示如何使用 Scala trait来构建一个模拟数学问题的小解决方案：
+
+```scala
+trait Adder:
+ def add(a: Int, b: Int) = a + b
+
+trait Multiplier:
+ def multiply(a: Int, b: Int) = a * b
+
+// create a class from the traits
+class SimpleMath extends Adder, Multiplier
+val sm = new SimpleMath
+sm.add(1,1) // 2
+sm.multiply(2,2) // 4
+```
+
+还有[许多其他方法可以将 trait 与类和对象一起使用][modeling-intro]，但这让您了解如何使用它们将概念组织成行为的逻辑组，然后根据需要将它们合并以创建一个完整的解决方案。
+
+## 控制结构
+
+本节比较 Python 和 Scala 中的[控制结构][control-structures]。
+两种语言都有类似 `if`/`else`、`while`、`for` 循环和 `try` 的结构。
+Scala 也有 `match` 表达式。
+
+### `if` 语句，单行：
+
+
+
+
+
+### `if` 语句，多行：
+
+
+
+
+
+### if, else if, else:
+
+
+
+
+
+### 从 `if` 返回值：
+
+
+
+
+
+### `if` 作为方法体：
+
+
+
+
+
+### `while` 循环：
+
+
+
+
+
+### 有范围的 `for` 循环：
+
+
+
+
+
+### 列表的 `for` 循环：
+
+
+
+
+
+### `for` 循环，多行：
+
+
+
+
+
+### 多“范围”生成器：
+
+
+
+
+
+### 带守卫（`if` 表达式）的生成器：
+
+
+
+
+
+### 每行有多个 `if` 条件：
+
+
+
+
+
+### 推导：
+
+
+
+
+
+### `match` 表达式：
+
+
+
+
+
+### switch/match:
+
+
+
+
+
+### try, catch, finally:
+
+
+
+
+
+匹配表达式和模式匹配是 Scala 编程体验的重要组成部分，但这里只展示了几个 `match` 表达式功能。 有关更多示例，请参见 [控制结构][control-structures] 页面。
+
+## 集合类
+
+本节比较 Python 和 Scala 中可用的 [集合类][collections-classes]，包括列表、字典/映射、集合和元组。
+
+### 列表
+
+Python 有它的列表，Scala 有几个不同的专门的可变和不可变序列类，具体取决于您的需要。
+因为 Python 列表是可变的，所以它最直接地与 Scala 的 `ArrayBuffer` 进行比较。
+
+### Python 列表 & Scala序列：
+Match expressions and pattern matching are a big part of the Scala programming experience, but only a few `match` expression features are shown here. See the [Control Structures][control-structures] page for many more examples.
+
+## Collections classes
+
+This section compares the [collections classes][collections-classes] that are available in Python and Scala, including lists, dictionaries/maps, sets, and tuples.
+
+### Lists
+
+Where Python has its list, Scala has several different specialized mutable and immutable sequence classes, depending on your needs.
+Because the Python list is mutable, it most directly compares to Scala’s `ArrayBuffer`.
+
+### Python list & Scala sequences:
+
+
+
+
+
+### 获取列表元素：
+
+
+
+
+### 更新列表元素：
+
+
+
+
+
+### 合并两个列表：
+
+
+
+
+
+### 遍历列表：
+
+
+
+
+
+Scala 的主要序列类是 `List`、`Vector` 和 `ArrayBuffer`。
+`List` 和 `Vector` 是当你想要一个不可变序列时使用的主要类，而 `ArrayBuffer` 是当你想要一个可变序列时使用的主要类。
+（Scala 中的“缓冲区”是一个可以增长和缩小的序列。）
+
+### 字典/映射
+
+Python 字典就像_可变的_ Scala `Map` 类。
+但是，默认的 Scala 映射是_不可变的_，并且有许多转换方法可以让您轻松创建新映射。
+
+#### 字典/映射 创建：
+
+
+
+
+
+#### 获取字典/映射元素：
+
+
+
+
+
+#### 带 `for` 循环的字典/映射：
+
+
+
+
+
+Scala 有其他专门的 `Map` 类来满足不同的需求。
+
+### 集合
+
+Python 集合类似于_可变的_ Scala `Set` 类。
+
+#### 集合创建：
+
+
+
+
+
+#### 重复元素：
+
+
+
+
+
+Scala 有其他专门的 `Set` 类来满足不同的需求。
+
+### 元组
+
+Python 和 Scala 元组也很相似。
+
+#### 元组创建：
+
+
+
+
+
+#### 获取元组元素：
+
+
+
+
+
+## 集合类上的方法
+
+Python 和 Scala 有几个相同的常用函数方法可供它们使用：
+
+- `map`
+- `filter`
+- `reduce`
+
+如果您习惯于在 Python 中将这些方法与 lambda 表达式一起使用，您会发现 Scala 在其集合类中使用了类似的方法。
+为了演示此功能，这里有两个示例列表：
+
+```scala
+numbers = (1,2,3) // python
+val numbers = List(1,2,3) // scala
+```
+
+下表中使用了这些列表，显示了如何对其应用映射和过滤算法。
+
+### 映射与推导：
+
+
+
+
+
+### 有推导的过滤：
+
+
+
+
+
+### 映射 & 有推导的过滤：
+
+
+
+
+
+### 映射：
+
+
+
+
+
+### 过滤：
+
+
+
+
+
+
+### Scala 集合方法：
+
+Scala 集合类有超过 100 种功能方法来简化您的代码。
+除了 `map`、`filter` 和 `reduce`，下面列出了其他常用的方法。
+在这些方法示例中：
+
+- `c` 指的是一个集合
+- `p` 是谓词
+- `f` 是一个函数、匿名函数或方法
+- `n` 指的是一个整数值
+
+以下是一些可用的过滤方法：
+
+| 方法 | 说明 |
+| -------------- | ------------- |
+| `c1.diff(c2) ` | 返回 `c1` 和 `c2` 中元素的差异。 |
+| `c.distinct` | 返回 `c` 中的唯一元素。 |
+| `c.drop(n)` | 返回集合中除前 `n` 个元素之外的所有元素。 |
+| `c.filter(p) ` | 返回集合中谓词为 `true` 的所有元素。 |
+| `c.head` | 返回集合的第一个元素。 （如果集合为空，则抛出 `NoSuchElementException`。） |
+| `c.tail` | 返回集合中除第一个元素之外的所有元素。 （如果集合为空，则抛出 `UnsupportedOperationException`。） |
+| `c.take(n)` | 返回集合 `c` 的前 `n` 个元素。 |
+
+以下是一些转换方法：
+
+| 方法 | 说明 |
+| --------------- | ------------- |
+| `c.flatten` | 将集合的集合（例如列表列表）转换为单个集合（单个列表）。 |
+| `c.flatMap(f)` | 通过将 `f` 应用于集合 `c` 的所有元素（如 `map`）返回一个新集合，然后将结果集合的元素展平。 |
+| `c.map(f)` | 通过将 `f` 应用于集合 `c` 的所有元素来创建一个新集合。 |
+| `c.reduce(f)` | 将 `reduction` 函数 `f` 应用于 `c` 中的连续元素以产生单个值。 |
+| `c.sortWith(f)` | 返回由比较函数 `f` 排序的 `c` 版本。 |
+
+一些常见的分组方法：
+
+| 方法 | 说明 |
+| ---------------- | ------------- |
+| `c.groupBy(f)` | 根据 `f` 将集合划分为集合的 `Map`。 |
+| `c.partition(p)` | 根据谓词 `p` 返回两个集合。 |
+| `c.span(p)` | 返回两个集合的集合，第一个由 `c.takeWhile(p)` 创建，第二个由 `c.dropWhile(p)` 创建。 |
+| `c.splitAt(n)` | 通过在元素 `n` 处拆分集合 `c` 来返回两个集合的集合。 |
+
+一些信息和数学方法：
+
+| 方法 | 说明 |
+| -------------- | ------------- |
+| `c1.containsSlice(c2)` | 如果 `c1` 包含序列 `c2`，则返回 `true`。 |
+| `c.count(p)` | 计算 `c` 中元素的数量，其中 `p` 为 `true`。 |
+| `c.distinct` | 返回 `c` 中的不重复的元素。 |
+| `c.exists(p)` | 如果集合中任何元素的 `p` 为 `true` ，则返回 `true` 。 |
+| `c.find(p)` | 返回匹配 `p` 的第一个元素。该元素以 `Option[A]` 的形式返回。 |
+| `c.min` | 返回集合中的最小元素。 （可以抛出_java.lang.UnsupportedOperationException_。）|
+| `c.max` | 返回集合中的最大元素。 （可以抛出_java.lang.UnsupportedOperationException_。）|
+| `c slice(from, to)` | 返回从元素 `from` 开始到元素 `to` 结束的元素间隔。 |
+| `c.sum` | 返回集合中所有元素的总和。 （需要为集合中的元素定义 `Ordering`。） |
+
+以下是一些示例，展示了这些方法如何在列表上工作：
+
+```scala
+val a = List(10, 20, 30, 40, 10) // List(10, 20, 30, 40, 10)
+a.distinct // List(10, 20, 30, 40)
+a.drop(2) // List(30, 40, 10)
+a.dropRight(2) // List(10, 20, 30)
+a.dropWhile(_ < 25) // List(30, 40, 10)
+a.filter(_ < 25) // List(10, 20, 10)
+a.filter(_ > 100) // List()
+a.find(_ > 20) // Some(30)
+a.head // 10
+a.headOption // Some(10)
+a.init // List(10, 20, 30, 40)
+a.intersect(List(19,20,21)) // List(20)
+a.last // 10
+a.lastOption // Some(10)
+a.slice(2,4) // List(30, 40)
+a.tail // List(20, 30, 40, 10)
+a.take(3) // List(10, 20, 30)
+a.takeRight(2) // List(40, 10)
+a.takeWhile(_ < 30) // List(10, 20)
+```
+
+这些方法展示了 Scala 中的一个常见模式：对象上可用的函数式方法。
+这些方法都不会改变初始列表“a”； 相反，它们都返回的数据在注释后显示。
+
+还有更多可用的方法，但希望这些描述和示例能让您体验到预建集合方法的强大功能。
+
+## 枚举
+
+本节比较 Python 和 Scala 3 中的枚举。
+
+### 创建枚举：
+
+
+
+
+
+### 值和比较：
+
+
+
+
+
+### 参数化枚举：
+
+
+
+
+
+### 用户定义枚举成员：
+
+
+
+
+
+## Scala 独有的概念
+
+Scala 中的有些概念目前在 Python 中没有等效的功能。
+请点击以下链接了解更多详情：
+
+
+
+- 大多数与[上下文抽象][contextual]相关的概念，如[扩展方法][extension-methods]、类型类、隐式值
+- Scala 允许多参数列表，从而实现部分应用函数等特性，以及创建自己的 DSL 的能力
+- 样例类，对于函数式编程和模式匹配非常有用
+- 创建自己的控制结构和 DSL 的能力
+- 模式匹配和 `match` 表达式
+- [多重等式][multiversal]：在编译时控制哪些等式比较有意义的能力
+- 中缀方法
+- 宏和元编程
+
+## Scala 和虚拟环境
+
+在 Scala 中，无需显式设置 Python 虚拟环境的等价物。默认情况下，Scala 构建工具管理项目依赖项，因此用户不必考虑手动安装包。例如，使用 `sbt` 构建工具，我们在 `libraryDependencies` 设置下的 `build.sbt` 文件中指定依赖关系，然后执行
+
+```
+cd myapp
+sbt compile
+```
+
+自动解析该特定项目的所有依赖项。 下载依赖的位置很大程度上是构建工具的一个实现细节，用户不必直接与这些下载的依赖交互。 例如，如果我们删除整个 sbt 依赖项缓存，则在项目的下一次编译时，sbt 会自动重新解析并再次下载所有必需的依赖项。
+
+这与 Python 不同，默认情况下，依赖项安装在系统范围或用户范围的目录中，因此要在每个项目的基础上获得隔离环境，必须创建相应的虚拟环境。 例如，使用 `venv` 模块，我们可以像这样为特定项目创建一个
+
+```
+cd myapp
+python3 -m venv myapp-env
+source myapp-env/bin/activate
+pip install -r requirements.txt
+```
+
+这会在项目的 `myapp/myapp-env` 目录下安装所有依赖项，并更改 shell 环境变量 `PATH` 以从 `myapp-env` 查找依赖项。
+在 Scala 中，这些手动过程都不是必需的。
+
+
+[collections-classes]: {% link _zh-cn/overviews/scala3-book/collections-classes.md %}
+[concurrency]: {% link _zh-cn/overviews/scala3-book/concurrency.md %}
+[contextual]: {% link _zh-cn/overviews/scala3-book/ca-contextual-abstractions-intro.md %}
+[control-structures]: {% link _zh-cn/overviews/scala3-book/control-structures.md %}
+[extension-methods]: {% link _zh-cn/overviews/scala3-book/ca-extension-methods.md %}
+[fp-intro]: {% link _zh-cn/overviews/scala3-book/fp-intro.md %}
+[hofs]: {% link _zh-cn/overviews/scala3-book/fun-hofs.md %}
+[intersection-types]: {% link _zh-cn/overviews/scala3-book/types-intersection.md %}
+[main-method]: {% link _zh-cn/overviews/scala3-book/methods-main-methods.md %}
+[modeling-intro]: {% link _zh-cn/overviews/scala3-book/domain-modeling-intro.md %}
+[multiversal]: {% link _zh-cn/overviews/scala3-book/ca-multiversal-equality.md %}
+[toplevel]: {% link _zh-cn/overviews/scala3-book/taste-toplevel-definitions.md %}
+[union-types]: {% link _zh-cn/overviews/scala3-book/types-union.md %}
+
diff --git a/_zh-cn/overviews/scala3-book/scala-tools.md b/_zh-cn/overviews/scala3-book/scala-tools.md
new file mode 100644
index 0000000000..822c3d428a
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/scala-tools.md
@@ -0,0 +1,20 @@
+---
+title: Scala 工具
+type: chapter
+description: This chapter looks at two commonly-used Scala tools, sbt and ScalaTest.
+language: zh-cn
+num: 69
+previous-page: concurrency
+next-page: tools-sbt
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+
+本章介绍编写和运行 Scala 程序的两种方法：
+
+- 通过创建Scala项目，可能包含多个文件，并定义一个程序入口点，
+- 通过与练习册交互，练习册是在单个文件中定义的程序，逐行执行。
diff --git a/_zh-cn/overviews/scala3-book/scala4x.css b/_zh-cn/overviews/scala3-book/scala4x.css
new file mode 100644
index 0000000000..c7d34705bb
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/scala4x.css
@@ -0,0 +1,59 @@
+
+
+
diff --git a/_zh-cn/overviews/scala3-book/string-interpolation.md b/_zh-cn/overviews/scala3-book/string-interpolation.md
new file mode 100644
index 0000000000..372eccc5e0
--- /dev/null
+++ b/_zh-cn/overviews/scala3-book/string-interpolation.md
@@ -0,0 +1,356 @@
+---
+title: 字符串插值
+type: chapter
+description: This page provides more information about creating strings and using 字符串插值.
+language: zh-cn
+num: 18
+previous-page: first-look-at-types
+next-page: control-structures
+redirect_from:
+ - /zh-cn/overviews/core/string-interpolation.html
+
+partof: scala3-book
+overview-name: "Scala 3 — Book"
+layout: multipage-overview
+permalink: "/zh-cn/scala3/book/:title.html"
+---
+
+## 介绍
+
+字符串插值提供了一种在字符串中使用变量的方法。
+比如：
+
+{% tabs example-1 %}
+{% tab 'Scala 2 and 3' for=example-1 %}
+```scala
+val name = "James"
+val age = 30
+println(s"$name is $age years old") // "James is 30 years old"
+```
+{% endtab %}
+{% endtabs %}
+
+字符串插值由在字符串引号前面的 `s` 和任何有前缀 `$` 的变量组成。
+
+### 其它插值
+
+把 `s` 放在字符串前，只是 Scala 提供的插值的一种可能。
+
+Scala 内置三种字符串插值方法： `s`, `f` 和 `raw`.
+进一步，字符串插值器只是一种特殊的方法，所以你也可以定义自己的插值器。例如，
+有些数据库的函数库定义了 `sql` 插值器，这个插值器可以返回数据库查询。
+
+## `s` 插值器 (`s`-字符串)
+
+在任何字符串字面量加上 `s` 前缀，就可以让你在字符串中直接使用变量。你已经在这里见过这个例子：
+
+{% tabs example-2 %}
+{% tab 'Scala 2 and 3' for=example-2 %}
+```scala
+val name = "James"
+val age = 30
+println(s"$name is $age years old") // "James is 30 years old"
+```
+{% endtab %}
+{% endtabs %}
+
+这里字符串中的 `$name` 和 `$age` 占位符相应地被调用 `name.toString` 和 `age.toString` 的结果所替换。
+`s`-字符串可以获取当前作用域的所有变量。
+
+虽然这看着很明显，但它很重要，需要在这指出来，字符串插值在普通字符串字面量中_不_起作用：
+
+{% tabs example-3 %}
+{% tab 'Scala 2 and 3' for=example-3 %}
+```scala
+val name = "James"
+val age = 30
+println("$name is $age years old") // "$name is $age years old"
+```
+{% endtab %}
+{% endtabs %}
+
+字符串插值器可以使用任何表达式。例如：
+
+{% tabs example-4 %}
+{% tab 'Scala 2 and 3' for=example-4 %}
+```scala
+println(s"2 + 2 = ${2 + 2}") // "2 + 2 = 4"
+val x = -1
+println(s"x.abs = ${x.abs}") // "x.abs = 1"
+```
+{% endtab %}
+{% endtabs %}
+
+任何表达式可以嵌入 `${}` 中.
+
+有些特殊字符在嵌入到字符串内时需要转义。
+当需要显示真实的美元符号时，你可以把美元符号双写 `$$`, 像这样：
+
+{% tabs example-5 %}
+{% tab 'Scala 2 and 3' for=example-5 %}
+```scala
+println(s"New offers starting at $$14.99") // "New offers starting at $14.99"
+```
+{% endtab %}
+{% endtabs %}
+
+双引号一样需要转义。这个可以使用三引号来达到，如下：
+
+{% tabs example-6 %}
+{% tab 'Scala 2 and 3' for=example-6 %}
+```scala
+println(s"""{"name":"James"}""") // `{"name":"James"}`
+```
+{% endtab %}
+{% endtabs %}
+
+最后，可以在所有多行字符串内插值
+
+{% tabs example-7 %}
+{% tab 'Scala 2 and 3' for=example-7 %}
+```scala
+println(s"""name: "$name",
+ |age: $age""".stripMargin)
+```
+
+This will print as follows:
+
+```
+name: "James"
+age: 30
+```
+{% endtab %}
+{% endtabs %}
+
+## `f` 插值器 (`f`-字符串)
+
+在任何字符串字面量加上 `f` 前缀，允许你创建简单的格式化字符串，像其它语言中的 `printf`。当使用 `f` 插值器时，
+所有变量的引用应该遵循 `printf` 风格的格式化字符串，像 `%d`。让我们看以下例子：
+
+{% tabs example-8 %}
+{% tab 'Scala 2 and 3' for=example-8 %}
+```scala
+val height = 1.9d
+val name = "James"
+println(f"$name%s is $height%2.2f meters tall") // "James is 1.90 meters tall"
+```
+{% endtab %}
+{% endtabs %}
+
+`f` 插值器是类型安全的。如果你尝试把一个双精度数传递给一个只能处理整数的格式化字符串，编译器会发出一个错误信息。
+例如：
+
+{% tabs f-interpolator-error class=tabs-scala-version %}
+
+{% tab 'Scala 2' for=f-interpolator-error %}
+```scala
+val height: Double = 1.9d
+
+scala> f"$height%4d"
+
+ # a comment
+ |
+
+ // a comment
+
+ |
+
+ x = 1
+
+ |
+
+ val x = 1
+
+ |
+
+ x = [1,2,3]
+ |
+
+ val x = List(1,2,3)
+ |
+
+ x = {
+
+ |
+
+ val x = Map(
+
+ |
+
+ x = {1,2,3}
+ |
+
+ val x = Set(1,2,3)
+ |
+
+ x = (11, "Eleven")
+ |
+
+ val x = (11, "Eleven")
+ |
+
+ class Person(object):
+
+ |
+
+ class Person (var name: String):
+
+ |
+
+ p = Person("John")
+
+ |
+
+ val p = Person("John")
+
+ |
+
+ def add(a, b): return a + b
+ |
+
+ def add(a: Int, b: Int): Int = a + b
+ |
+
+ def walkThenRun():
+
+ |
+
+ def walkThenRun() =
+
+ |
+
+ if x == 1: print(x)
+ |
+
+ if x == 1 then println(x)
+ |
+
+ if x == 1:
+
+ |
+
+ if x == 1 then
+
+ |
+
+ if x < 0:
+
+ |
+
+ if x < 0 then
+
+ |
+
+ min_val = a if a < b else b
+ |
+
+ val minValue = if a < b then a else b
+ |
+
+ def min(a, b):
+
+ |
+
+ def min(a: Int, b: Int): Int =
+
+ |
+
+ i = 1
+
+ |
+
+ var i = 1
+
+ |
+
+ for i in range(0,3):
+
+ |
+
+ // preferred
+
+ |
+
+ for i in ints: print(i)
+
+ |
+
+ for i <- ints do println(i)
+ |
+
+ for i in ints:
+
+ |
+
+ for
+
+ |
+
+ for i in range(1,3):
+
+ |
+
+ for
+
+ |
+
+ for i in range(1,11):
+
+ |
+
+ for
+
+ |
+
+ for i in range(1,11):
+
+ |
+
+ for
+
+ |
+
+ xs = [i * 10 for i in range(1, 4)]
+
+ |
+
+ val xs = for i <- 1 to 3 yield i * 10
+
+ |
+
+ # From 3.10, Python supports structural pattern matching
+
+ |
+
+ val monthAsString = month match
+
+ |
+
+ # Only from Python 3.10
+
+ |
+
+ val numAsString = i match
+
+ |
+
+ try:
+
+ |
+
+ try
+
+ |
+
+ a = [1,2,3]
+ |
+
+ // use different sequence classes
+
+ |
+
+ a[0]
+ |
+
+ a(0) // just like all other method calls
+ |
+
+ a[0] = 10
+
+ |
+
+ // ArrayBuffer is mutable
+
+ |
+
+ c = a + b
+ |
+
+ val c = a ++ b
+ |
+
+ for i in ints: print(i)
+
+ |
+
+ // preferred
+
+ |
+
+ my_dict = {
+
+ |
+
+ val myMap = Map(
+
+ |
+
+ my_dict['a'] # 1
+ |
+
+ myMap("a") // 1
+ |
+
+ for key, value in my_dict.items():
+
+ |
+
+ for (key,value) <- myMap do
+
+ |
+
+ set = {"a", "b", "c"}
+ |
+
+ val set = Set(1,2,3)
+ |
+
+ set = {1,2,1}
+
+ |
+
+ val set = Set(1,2,1)
+
+ |
+
+ t = (11, 11.0, "Eleven")
+ |
+
+ val t = (11, 11.0, "Eleven")
+ |
+
+ t[0] # 11
+
+ |
+
+ t(0) // 11
+
+ |
+
+ x = [i * 10 for i in numbers]
+ |
+
+ val x = for i <- numbers yield i * 10
+ |
+
+ evens = [i for i in numbers if i % 2 == 0]
+ |
+
+ val evens = numbers.filter(_ % 2 == 0)
+
+ |
+
+ x = [i * 10 for i in numbers if i % 2 == 0]
+ |
+
+ val x = numbers.filter(_ % 2 == 0).map(_ * 10)
+
+ |
+
+ x = map(lambda x: x * 10, numbers)
+ |
+
+ val x = numbers.map(_ * 10)
+ |
+
+ f = lambda x: x > 1
+
+ |
+
+ val x = numbers.filter(_ > 1)
+ |
+
+ from enum import Enum, auto
+
+ |
+
+ enum Color:
+
+ |
+
+ Color.RED == Color.BLUE # False
+ |
+
+ Color.Red == Color.Blue // false
+ |
+
| + N/A + | +
+ enum Color(val rgb: Int):
+
+ |
+
| + N/A + | +
+ enum Planet(
+
+ |
+
| 变量类型 | +说明 | +
|---|---|
val |
+ 创建一个不可变变量——类似于 Java 中的 final。 您应该始终使用 val 创建一个变量，除非有理由使用可变变量。 |
+
var |
+ 创建一个可变变量，并且只应在变量的内容随时间变化时使用。 | +
diff --git a/contribute.md b/contribute.md index 471ab85a3c..3ac938c17b 100644 --- a/contribute.md +++ b/contribute.md @@ -1,9 +1,9 @@ --- -layout: contribute -title: Contribute +layout: singlepage-overview +title: Why Contribute to docs.scala-lang.org? --- -###### Heather Miller +###### A note from Heather Miller ## A Place to Build Documentation Together @@ -21,175 +21,6 @@ If we want Scala to be accessible to more programmers, clear, easy-to-find docum If you're interested in contributing to the Scala project in general, I argue that one of the most meaningful ways that you can, is to help us improve this transfer of information- let's make it easier and faster for people to _get_ core concepts, and to answer their own questions so they can progress to _Scala-proficient_ quickly. Each line that you contribute has the potential to affect the entire Scala community as a whole-- current, and future. -## About docs.scala-lang.org +## How Can I Contribute? -### Content - -Currently, the _types_ of documentation supported in this repository are: - -- **Guides/Overviews**: Definitive guides/overviews of specific language features. Often long, detailed documents, often produced by members of the Scala team. An example is the excellent [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview. -- **Tutorials**: Bite-size, example-rich, and concise articles meant to get a developer up to speed quickly. -- **Cheatsheets**: Quick reference of Scala syntax and behaviors. - -### Implementation - -This documentation repository is open-source, it lives in [github repository](https://github.com/scala/docs.scala-lang), and is always contribution-ready. - -It's statically generated from [Markdown](https://en.wikipedia.org/wiki/Markdown) source using [Jekyll](https://github.com/mojombo/jekyll), and hosted on [GitHub Pages](https://pages.github.com/). This workflow was chosen so as to make it as easy as possible for core committers and the community alike to produce HTML documentation, and as easy as possible to publish it in a central location. - -The markdown syntax being used supports [Maruku](https://github.com/bhollis/maruku) extensions, and has automatic syntax highlighting, without the need for any tags. - -Additionally [mdoc](https://github.com/scalameta/mdoc) is used during pull requests to validate Scala code blocks. To use this feature you must use the backtick notation as documented by mdoc. Note that only validation is done. The output files from mdoc are not used in the building of the tutorial. Use `mdoc` or `mdoc:fail` for your code blocks. - -## Submitting Docs - -For one to contribute a document, one must simply -[fork](https://help.github.com/articles/fork-a-repo/) the -[repo](https://github.com/scala/docs.scala-lang), write their article in -[Markdown](https://daringfireball.net/projects/markdown/syntax) (example below), and submit a pull request. That's it. Likely after some edits and discussion, your document will be made live on [docs.scala-lang.org](https://docs.scala-lang.org). - - --- - layout: overview - title: My Awesome Title - --- - - ## An h2 Header in Markdown - - And a paragraph, with a [link](https://www.scala-lang.org). - - One can contribute code by indenting it 4 spaces, or in-line by putting backticks around it like so, `def foo` - -Everything else is automatically generated for you; tables of contents, and most index pages. And of course, the styling is already taken care of for you. - -### Criteria for Docs to be Accepted - -The goal of this documentation repository is to be tighter and more organized than other community-driven documentation platforms, like wikis. As such, any document pulled in for inclusion on [https://docs.scala-lang.org](https://docs.scala-lang.org) must: - -- **"fit in"** to the repository ( _i.e.,_ it should not be a complete duplicate of another article), -- **be polished** it must be thorough, complete, correct, organized, and "article-like" (personal programming notes don't quite fit.) -- **be maintained** if the document might require revisions from time to time, it should come with an owner - -If you have something you're thinking about contributing, or that you're thinking about writing in order to contribute-- we'd love to consider it! Please don't hesitate to use GitHub issues and pull requests and the [scala/contributors room](https://gitter.im/scala/contributors) on Gitter for any questions, concerns, clarifications, etc. - -## Document Templates - - - -### Guides/Overviews - -A guide or an overview that can be logically placed on **one** page must be placed in the directory `overviews/RELEVANT-CATEGORY/_posts` with the file name in the format `YYYY-MM-dd-title-separated-by-dashes.md`, and header: - - --- - layout: overview - title: YOUR TITLE - --- - -The rest of the document should, of course, be written in [Markdown](https://en.wikipedia.org/wiki/Markdown). - -At the moment, `RELEVANT-CATEGORY` corresponds to only a single category, "core," because we are currently focusing on building up documentation of core libraries. However, expect more categories here in the future. - -If your document consists of **multiple** pages, like the [Collections]({{ site.baseurl }}/overviews/collections-2.13/introduction.html) overview, an ordering must be specified, by numbering documents in their logical order with `num`, and a name must be assigned to the collection of pages using `partof`. For example, the following header might be used for a document in the collections overview: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 10 - --- - -A **single** document in the collection must contain a tag in the header, `outof`, that indicates the total number of documents in the large overview. Putting it on the last page in the overview is often best: - - --- - layout: overview - title: YOUR TITLE - - partof: collections - num: 15 - outof: 15 - --- - -Index pages, such as [https://docs.scala-lang.org/overviews/index.html](https://docs.scala-lang.org/overviews/index.html) are automatically generated, assuming documents are properly placed under the correct `RELEVANT-CATEGORY`. So, simply drop your document into the correct folder, and you're done. - -### Tutorials - -At the moment, a tutorial that can be logically placed on **one** page must be placed in the directory `tutorials/` with the file name in the format `title-separated-by-dashes.md`. For the moment, single-page tutorials use the same layout as single-page overviews: - - --- - layout: overview - title: YOUR TITLE - --- - -If you have a **multiple-page** tutorial, like in the case of multiple-page overviews, you must both specify an ordering for your document, and a name must be assigned to the collection of tutorial pages. For example, the following header is used for the [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html) series of tutorial articles: - - --- - layout: inner-page-no-masthead - title: YOUR TITLE - - tutorial: scala-tour - num: 4 - --- - -At the moment, only indexes for multiple-page tutorials are automatically generated. - -### Cheatsheets - -For now, cheatsheets are assumed to be in the form of tables. To contribute a cheatsheet, one must simply produce their cheatsheet as a Markdown table, with the following header: - - --- - layout: cheatsheet - title: YOUR TITLE - by: YOUR NAME - about: SOME TEXT ABOUT THE CHEAT SHEET. - --- - -### Code blocks - -The site build process uses [mdoc](https://scalameta.org/mdoc/) to typecheck -code snippets in markdown. This is a great way to ensure the code snippets that -you're including typecheck and are valid. Here are a few quick types to get -started. - -To get started, you can simply add `mdoc` behind `scala` when you are creating a -code block. The `mdoc` modifier here will make sure that `mdoc` runs the code -snippet and ensures that it's valid. - - ```scala mdoc - val a = 1 - ``` -If you have a snippet that you expect to fail, you can also account for this by -using `mdoc:fail` for a compile error `mdoc:crash` for a runtime-error. - - ```scala mdoc:fail - val b: String = 3 // won't compile - ``` -Keep in mind that a single file is all compiled as a single unit, so you can't -redefine a variable that was defined above in another code snippet. _However_ -there are a couple ways to get around this. Firstly, you can use the `mdoc:nest` -modifier with will wrap the snippet in a `scala.Predef.locally{...}`. This will -essentially "hide" the snippet from the others. Another way around this is to -use the `mdoc:reset` modifier, which _resets_ and forgets about everything up -above. Here is an example using the various modifiers. - - ```scala mdoc - import java.time.Instant - - def now() = Instant.now() - object Foo {} - ``` - - ```scala mdoc:nest - case class Foo(a: Int) // conflicts with Foo above, but it's nested so it's fine - ``` - - ```scala mdoc - val a = s"The time is ${now()}" // still have access to the now method from above - ``` - ```scala mdoc:reset - case class Foo(a: String) // forget the previous Foo's and start fresh - ``` - ```scala mdoc - val myFoo = Foo("hi") // now we only have access to the last Foo - ``` +Please read: [Add New Guides/Tutorials](https://docs.scala-lang.org/contribute/add-guides.html) diff --git a/docker-compose.yml b/docker-compose.yml index 26f6d5b398..75b1876399 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,9 +1,9 @@ -version: '2' - services: jekyll: - image: bretfisher/jekyll-serve - volumes: - - .:/site + user: "${UID}:${GID}" + build: . + command: sh -c "chown $UID / && bundle exec jekyll serve --incremental --host=0.0.0.0 " ports: - - '8080:4000' + - '4000:4000' + volumes: + - .:/srv/jekyll diff --git a/docker-compose_build-only.yml b/docker-compose_build-only.yml new file mode 100644 index 0000000000..615d0425a7 --- /dev/null +++ b/docker-compose_build-only.yml @@ -0,0 +1,9 @@ +version: '2' + +services: + jekyll: + user: "${UID}:${GID}" + build: . + command: sh -c "chown $UID / && bundle exec jekyll build" + volumes: + - .:/srv/jekyll diff --git a/guides.md b/guides.md deleted file mode 100644 index 98700b64b3..0000000000 --- a/guides.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout: inner-page-no-masthead -title: Guides and Overviews -languages: [ja, zh-cn, es, ru] - ---- diff --git a/index.md b/index.md index d244e435e7..22cbc790cc 100644 --- a/index.md +++ b/index.md @@ -1,74 +1,55 @@ --- -layout: documentation -languages: [ja, zh-cn, ru] -title: Documentation +layout: landing-page +languages: [ja, zh-cn, ru, uk] + +title: Learn Scala namespace: root discourse: true partof: documentation more-resources-label: More Resources +redirect_from: + - /scala3/ + - /scala3/index.html -scala3-sections: - - title: "First steps" - links: - - title: "New in Scala 3" - description: "An overview of the exciting new features in Scala 3." - icon: "fa fa-star" - link: /scala3/new-in-scala3.html - - title: "Getting Started" - description: "Install Scala 3 on your computer and start writing some Scala code!" - icon: "fa fa-rocket" - link: /scala3/getting-started.html - - title: "Scala 3 Book" - description: "An online book introducing the main language features." - icon: "fa fa-book" - link: /scala3/book/introduction.html - - title: "More detailed information" - links: - - title: "Migration Guide" - description: "A guide to help you migrate from Scala 2 to Scala 3." - icon: "fa fa-suitcase" - link: https://scalacenter.github.io/scala-3-migration-guide/ - - title: "Guides" - description: "Detailed guides about particular aspects of the language." - icon: "fa fa-map" - link: /scala3/guides.html - - title: "API" - description: "API documentation for every version of Scala 3." - icon: "fa fa-file-text" - link: https://dotty.epfl.ch/api/index.html - - title: "Language Reference" - description: "The Scala 3 language reference." - icon: "fa fa-book" - link: https://dotty.epfl.ch/docs/reference/overview.html - -scala2-sections: +sections: - title: "First Steps..." links: - title: "Getting Started" description: "Install Scala on your computer and start writing some Scala code!" icon: "fa fa-rocket" - link: /getting-started.html + link: /getting-started/install-scala.html - title: "Tour of Scala" description: "Bite-sized introductions to core language features." icon: "fa fa-flag" link: /tour/tour-of-scala.html - - title: "Scala Book" - description: "An online book introducing the main language features." - icon: "fa fa-book" - link: /overviews/scala-book/introduction.html - more-resources: - - title: Online Courses, Exercises, & Blogs - url: /learn.html + - title: "Scala 3 Book" + description: "Learn Scala by reading a series of short lessons." + icon: "fa fa-book-open" + link: /scala3/book/introduction.html + - title: "Scala Toolkit" + description: "Sending HTTP requests, writing files, running processes, parsing JSON..." + icon: "fa fa-toolbox" + link: /toolkit/introduction.html + - title: Online Courses + description: "MOOCs to learn Scala, for beginners and experienced programmers." + icon: "fa fa-cloud" + link: /online-courses.html - title: Books - url: /books.html + description: "Printed and digital books about Scala." + icon: "fa fa-book" + link: /books.html + - title: Tutorials + description: "Take you by the hand through a series of steps to create Scala applications." + icon: "fa fa-tasks" + link: /tutorials.html - title: "Returning Users" links: - title: "API" description: "API documentation for every version of Scala." - icon: "fa fa-file-text" + icon: "fa fa-file-alt" link: /api/all.html - - title: "Overviews" + - title: "Guides & Overviews" description: "In-depth documentation covering many of Scala's features." icon: "fa fa-database" link: /overviews/index.html @@ -84,19 +65,46 @@ scala2-sections: description: "Answers to frequently-asked questions about Scala." icon: "fa fa-question-circle" link: /tutorials/FAQ/index.html - - title: "Language Spec" - description: "Scala's formal language specification." + - title: "Language Spec v2.x" + description: "Scala 2's formal language specification." icon: "fa fa-book" link: https://scala-lang.org/files/archive/spec/2.13/ + - title: "Language Spec v3.x" + description: "Scala 3's formal language specification." + icon: "fa fa-book" + link: https://scala-lang.org/files/archive/spec/3.4/ + - title: "Scala 3 Language Reference" + description: "The Scala 3 language reference." + icon: "fa fa-book" + link: https://docs.scala-lang.org/scala3/reference + + - title: "Explore Scala 3" + links: + - title: "Migration Guide" + description: "A guide to help you move from Scala 2 to Scala 3." + icon: "fa fa-suitcase" + link: /scala3/guides/migration/compatibility-intro.html + - title: "New in Scala 3" + description: "An overview of the exciting new features in Scala 3." + icon: "fa fa-star" + link: /scala3/new-in-scala3.html + - title: "All new Scaladoc for Scala 3" + description: "Highlights of new features for Scaladoc" + icon: "fa fa-star" + link: /scala3/scaladoc.html + - title: "Talks" + description: "Talks about Scala 3 that can be watched online" + icon: "fa fa-play-circle" + link: /scala3/talks.html - title: "Scala Evolution" links: - - title: "SIPs" - description: "The Scala Improvement Process. Language & compiler evolution." + - title: "Scala Improvement Process" + description: "Description of the process for evolving the language, and list of all the Scala Improvement Proposals (SIPs)." icon: "fa fa-cogs" link: /sips/index.html - - title: "SPP" - description: "The Scala Platform Process. Community-driven library evolution." - icon: "fa fa-users" - link: https://platform.scala-lang.org + - title: "Become a Scala OSS Contributor" + description: "From start to finish: discover how you can help Scala's open-source ecosystem" + icon: "fa fa-code-branch" + link: /contribute/ --- diff --git a/learn.md b/learn.md deleted file mode 100644 index 62ff6b5fbb..0000000000 --- a/learn.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Online Resources -layout: inner-page-no-masthead -redirect_from: - - /documentation/books.html ---- - -## Try Scala in your browser! - -There are a handful of websites where you can interactively run Scala code in your browser! Have a look at [ScalaFiddle](https://scalafiddle.io/) and [Scastie](https://scastie.org/). - -## Online courses from the Scala Center - -The following courses are available for free. They teach you the main features of the Scala language and introduce you -to functional programming. They are published either on [Coursera](https://www.coursera.org) or [edX](https://www.edx.org). - - * [Functional Programming in Scala Specialization](https://www.coursera.org/specializations/scala). - The Specialization provides a hands-on introduction to functional programming using Scala. You can access the courses - material and exercises by either signing up for the specialization or auditing the courses individually. The - specialization has the following courses. - * [Functional Programming Principles in Scala](https://www.coursera.org/learn/progfun1), - * [Functional Program Design in Scala](https://www.coursera.org/learn/progfun2), - * [Parallel programming](https://www.coursera.org/learn/parprog1), - * [Big Data Analysis with Scala and Spark](https://www.coursera.org/learn/scala-spark-big-data), - * [Functional Programming in Scala Capstone](https://www.coursera.org/learn/scala-capstone), - * [Programming Reactive Systems](https://www.coursera.org/learn/scala-reactive) (also available on [edX](https://www.edx.org/course/programming-reactive-systems)). - -Note : On Coursera and edX, there is a paid version available. The only difference with the free version is that -the paid version delivers a certificate of completion. Learn more about -[Coursera certificates](https://learner.coursera.help/hc/en-us/articles/209819053-Get-a-Course-Certificate) or -[edX certificates](https://support.edx.org/hc/en-us/categories/115002269627-Certificates). - -## Scala Exercises - -[Scala Exercises](https://www.scala-exercises.org/) is a series of lessons and exercises created by [47 Degrees](https://www.47deg.com/). It's a great way to get a brief introduction to Scala while testing your knowledge along the way. - -[Tour of Scala](https://tourofscala.com) gives you an introduction to Scala, step by step, from begineer to expert. - -## Dr. Mark C Lewis's lectures from Trinity University - -[Dr. Mark C Lewis](https://www.cs.trinity.edu/~mlewis/) from Trinity University, San Antonio, TX, teaches programming courses using the Scala language. Course videos are available in YouTube for free. Some of the courses below. - - * [Introduction to Programming and Problem Solving Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt9MIJ9DV4ps-_trOzWtphYO) - * [Object-Orientation, Abstraction, and Data Structures Using Scala](https://www.youtube.com/playlist?list=PLLMXbkbDbVt8JLumqKj-3BlHmEXPIfR42) - -You can visit his [YouTube channel](https://www.youtube.com/user/DrMarkCLewis/featured) for more videos. - -## Scala Learning Community -[Scala Learning Community on Discord](http://sca.la/learning-community), a growing online community connecting learners with online resources to learn Scala together. - -## allaboutscala -[allaboutscala](https://allaboutscala.com/) provides detailed tutorials for beginners. - -## ScalaCourses -[Independent Courseware](https://getscala.com), online self-study or instructor-led Scala and Play courses for a fee. - -## DevInsideYou -[DevInsideYou](https://youtube.com/devinsideyou) is a YouTube channel with hundreds of hours of free Scala content. - -## Visual Scala Reference -[Visual Scala Reference](https://superruzafa.github.com/visual-scala-reference/), a guide to visually learn about Scala concepts and functions. diff --git a/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md b/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md index 38a941ac28..c4722a5bb3 100644 --- a/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md +++ b/news/_posts/2012-12-12-functional-programming-principles-in-scala-impressions-and-statistics.md @@ -1,5 +1,5 @@ --- -layout: inner-page-no-masthead +layout: singlepage-overview title: "Functional Programming Principles in Scala: Impressions and Statistics" --- ###### By Heather Miller and Martin Odersky @@ -33,7 +33,7 @@ Those of you reading this who were enrolled in the course might recall that, sev For example, as mentioned above, a success rate of 20% is quite high for an online course. One might suspect that it was because the course was very easy, but in our previous experience that's not the case. In fact, the online course is a direct adaptation of a 2nd year course that was given at EPFL for a number of years and that has a reputation of being rather tough. If anything, the material in the online course was a bit more compressed than in the previous on-campus class. -In particular, 57% of all respondents to the survey rated the overall course as being 3, "Just Right", on a scale from 1 to 5, with 1 being "Too Easy" and 5 being "Too Difficult. With regard to programming assignments specifically, 40% rated the assignments as being 3, "Just Right", while 46% rated assignments as being 4 "Challenging". +In particular, 57% of all respondents to the survey rated the overall course as being 3, "Just Right", on a scale from 1 to 5, with 1 being "Too Easy" and 5 being "Too Difficult". With regard to programming assignments specifically, 40% rated the assignments as being 3, "Just Right", while 46% rated assignments as being 4 "Challenging". Another point which might be particularly interesting is the fact that the difficulty rating appears to be independent of whether people have a background in Computer Science/Software Engineering or not. One might guess that this could mean that learning Scala is not much more difficult without a formal educational background in Computer Science. @@ -43,7 +43,7 @@ While a majority of the students in the course have degrees in Computer Science/
Participants' Fields of Study
Perceived Difficulty Relative to Level of Education
Which editor do you normally use, and which editor did you use for the course?
-
-
-Along with managing JVMs, `cs setup` also installs useful command line tools:
-
-- A JDK
-- The [sbt](https://www.scala-sbt.org) and [mill](https://com-lihaoyi.github.io/mill/) build tools
-- [Ammonite](https://ammonite.io), an enhanced REPL
-- [scalafmt](https://scalameta.org/scalafmt), the Scala formatter
-- The [Coursier CLI](https://get-coursier.io/docs/cli-overview), to install further Scala-based applications
-- (the `scala` and `scalac` command-line tools for Scala 2.13 -- not Scala 3).
-
-For more information, read the [coursier-cli documentation](https://get-coursier.io/docs/cli-overview).
-
-
-### ... or manually
-
-You only need two tools to compile, run, test, and package a Scala project: Java 8 or 11, and sbt.
-To install these manually:
-
-1. Download Java from [Oracle Java 8](https://www.oracle.com/java/technologies/javase-jdk8-downloads.html), [Oracle Java 11](https://www.oracle.com/java/technologies/javase-jdk11-downloads.html), or [AdoptOpenJDK 8/11](https://adoptopenjdk.net/). Refer to [JDK Compatibility](/overviews/jdk-compatibility/overview.html) for Scala/Java compatibility detail.
-2. Install [sbt](https://www.scala-sbt.org/download.html)
-
-
-
-## Create a “Hello, world” project with sbt
-
-To create a project, you can either use a command-line tool or an IDE.
-If you are familiar with the command line, we recommend that approach.
-
-
-### Using the command line
-
-sbt is a build tool for Scala.
-sbt compiles, runs, and tests your Scala code.
-(It can also publish libraries and do many other tasks.)
-
-To create a new Scala project with sbt:
-
-1. `cd` to an empty folder.
-1. Run this command `sbt new scala/scala3.g8`.
-This pulls the ['hello-world' template][template-url] from GitHub.
-It also creates a _target_ folder, which you can ignore.
-1. When prompted, name the application `hello world`.
- This will create a project called "hello-world".
-1. Let’s take a look at what just got generated:
-
-```
-hello-world/
- project/ (sbt uses this for its own files)
- build.properties
- src/main/scala/ (all of your Scala code goes here)
- Main.scala (entry point of program)
- build.sbt (sbt’s build definition file)
-```
-The scala file `Main.scala` in `src/main/scala` is all we need for now.
-
-More documentation about sbt can be found in the [Scala Book](/scala3/book/scala-tools.html) and in the official sbt [documentation](https://www.scala-sbt.org/1.x/docs/index.html)
-
-
-{% comment %}
-### With IntelliJ IDEA
-
-You can skip the rest of this page and go directly to [Building a Scala Project with IntelliJ and sbt](/getting-started/intellij-track/building-a-scala-project-with-intellij-and-sbt.html)
-{% endcomment %}
-
-
-## Open the “Hello, world” project
-
-Let’s use an IDE to open the project.
-The most popular ones are IntelliJ IDEA and VS Code.
-They both offer rich IDE features, but you can still use [many other editors.](https://scalameta.org/metals/docs/editors/overview.html)
-
-### Using IntelliJ IDEA
-
-1. Download and install [IntelliJ Community Edition](https://www.jetbrains.com/idea/download/)
-1. Install the Scala plugin by following [the instructions on how to install IntelliJ plugins](https://www.jetbrains.com/help/idea/managing-plugins.html)
-1. Open the _build.sbt_ file, then choose _Open as a project_
-
-### Using VS Code with Metals
-
-1. Download [VS Code](https://code.visualstudio.com/Download)
-1. Install the Metals extension from [the Marketplace](https://marketplace.visualstudio.com/items?itemName=scalameta.metals)
-1. Next, open the directory containing your _build.sbt_ file.
- When prompted to do so, select _Import build_.
-
->[Metals](https://scalameta.org/metals) is a “Scala language server” that provides support for writing Scala code in VS Code and other editors like [Atom, Sublime Text, and more](https://scalameta.org/metals/docs/editors/overview.html), using the Language Server Protocol.
-(For details on how Metals works, see, [“Write Scala in VS Code, Vim, Emacs, Atom and Sublime Text with Metals”](https://www.scala-lang.org/2019/04/16/metals.html).)
-
-
-
-### View the source code
-
-View these two files in your IDE:
-
-- _build.sbt_
-- _src/main/scala/Main.scala_
-
-When you run your project in the next step, the configuration in _build.sbt_ will be used to run the code in _src/main/scala/Main.scala_.
-
-
-
-## Run the “Hello, world” project
-
-If you’re comfortable using your IDE, you can run the code in _Main.scala_ from your IDE.
-
-Otherwise, you can run the application from a terminal with these steps:
-
-1. `cd` into _hello-world_.
-1. Run `sbt`.
- This opens up the sbt console.
-1. Type `~run`.
- The `~` is optional and causes sbt to re-run on every file save, allowing for a fast edit/run/debug cycle.
- sbt also generates a `target` directory for its own use, which you can ignore.
-
-When you’re finished experimenting with this project, press `[Enter]` to interrupt the `run` command.
-Then type `exit` or press `[Ctrl][d]` to exit sbt and return to your command line prompt.
-
-
-
-## Next steps
-
-Now that you’ve created a first “Hello, world” example with Scala 3, you’re ready for some next steps.
-Consider checking out:
-
-- [The Scala 3 Book](/scala3/book/introduction.html), which provides a set of short lessons introducing Scala’s main features
-- [The migration guide](https://scalacenter.github.io/scala-3-migration-guide/) helps you to migrate your existing Scala 2 code base to Scala 3.
-
-When you want to connect with other Scala users, there are several mailing lists and real-time chat rooms available.
-Check out our [Scala community page](https://scala-lang.org/community/) for a list of these resources, and for where to reach out for help.
-
-
-
-
-
-
-
-
-
-
-
-[template-url]: https://github.com/scala/scala3.g8
diff --git a/scala3/guides.md b/scala3/guides.md
deleted file mode 100644
index 36d631131f..0000000000
--- a/scala3/guides.md
+++ /dev/null
@@ -1,66 +0,0 @@
----
-layout: inner-page-parent
-title: Guides on Scala 3
-
-guides:
- - title: "Migration from Scala 2 to Scala 3"
- icon: suitcase
- url: "https://scalacenter.github.io/scala-3-migration-guide"
- description: "Everything you need to know about compatibility and migration to Scala 3."
- - title: Macros
- by: Nicolas Stucki
- icon: magic
- url: "/scala3/guides/macros"
- description: "A detailed tutorial to cover all the features involved in writing macros in Scala 3."
- label-text: feature
- - title: An Overview of TASTy
- by: Alvin Alexander
- icon: birthday-cake
- url: "/scala3/guides/tasty-overview.html"
- description: "An overview over the TASTy format aimed at end-users of the Scala language."
----
-
-
-
-Follow the instructions to install the cs launcher then run:
$ cs install scala3-repl
$ cs install scala3-compiler
-
-
-
-
-
- Overviews and Guides
-- Detailed guides about the Scala 3 language and its features. -
-
- {% for overview in page.guides %}
-
-
-
- {% endfor %}
-
-
-
-
- {% if overview.icon %}
-
-
-
- {% endif %}
-
-
{{ overview.title }}
-
- {% if overview.label-text %}
- {{ overview.label-text }}
{% endif %}
- {% if overview.by %}By {{ overview.by }}
{% endif %}
- {% if overview.description %}{{ overview.description }}
{% endif %} - {% if overview.subdocs %} - Contents --
- {% for doc in overview.subdocs %}
-
- {{ doc.title }} - {% endfor %} -
+
+
+
+## Scala Learning Path
+
+The diagram below summarizes the possible learning paths with our courses:
+
+
+
+The “foundational” courses target programmers with no prior experience in Scala, whereas the “deepening”
+courses aim at strengthening Scala programmers skills in a specific domain (such as parallel programming).
+
+We recommend starting with either Effective Programming in Scala, or Functional Programming Principles in
+Scala followed by Functional Program Design. Then, you can complement your Scala skills by taking any
+of the courses Programming Reactive Systems, Parallel Programming, or Big Data Analysis with Scala and Spark.
+In case you take the Scala Specialization, you will end with the Scala Capstone Project.
+
+## Learning Platforms
+
+Currently, all our MOOCs are available on the platform [Coursera](https://coursera.org),
+and some of them are available on [edX](https://edx.org) or the [Extension School](https://extensionschool.ch).
+This section explains the differences between these learning platforms.
+
+On all the platforms the full material is always available online. It includes
+video lectures, text articles, quizzes, and auto-graded homeworks. All the
+platforms also provide discussion forums where you can exchange with the
+other learners.
+
+The difference between the Extension School and the other platforms is that it
+provides live meetings with instructors, and code reviews by Scala experts.
+
+On the other hand, on Coursera or edX it is possible to take
+our courses for free (a.k.a. “audit” mode). Optionally, a subscription gives
+you access to a certificate of completion that attests your accomplishments.
+
+Learn more about
+[Coursera certificates](https://learners.coursera.help/hc/en-us/articles/209819053-Get-a-Course-Certificate),
+[edX certificates](https://support.edx.org/hc/en-us/categories/115002269627-Certificates),
+or [Extension School certificates](https://www.extensionschool.ch/faqs#certifying-coursework).
+Note that your subscriptions also supports the work of the [Scala Center],
+whose mission is to create high-quality educational material.
+
+If you prefer learning in autonomy, we recommend
+you to choose the Coursera or edX platform, but if you are looking for more
+support, we recommend you to choose the Extension School. Here is a table
+below that compares the learning platforms:
+
+| | Coursera / edX (audit) | Coursera / edX (subscription) | Extension School |
+|--------------------------------------------------|------------------------|-------------------------------|------------------|
+| Video lectures, quizzes | Yes | Yes | Yes |
+| Auto-graded homeworks | Yes | Yes | Yes |
+| Discussion forums | Yes | Yes | Yes |
+| Self-paced | Yes | Yes | Yes |
+| Price | $0 | $50 to $100 per course | $420 per month |
+| Certificate of completion | No | Yes | Yes |
+| Supports the Scala Center | No | Yes | Yes |
+| 30 min of live session with instructors per week | No | No | Yes |
+| Code reviews by Scala experts | No | No | Yes |
+
+## Effective Programming in Scala
+
+This course is available on [Coursera](https://coursera.org/learn/effective-scala)
+and the [Extension School](https://extensionschool.ch/learn/effective-programming-in-scala).
+Please refer to [this section](#learning-platforms) to know the differences
+between both learning platforms.
+
+[Effective Programming in Scala] teaches non-Scala programmers everything
+they need to be ready to work in Scala. At the end of this hands-on course,
+you will know how to achieve common programming tasks in Scala (e.g.,
+modeling business domains, implementing business logic, designing large
+systems made of components, handling errors, manipulating data, running
+concurrent tasks in parallel, testing your code). You can learn more about
+this course in the following video:
+
+
+
+
+
+This course is also a good way to upgrade your Scala 2 knowledge to Scala 3.
+
+After taking this course, you might be interested in improving your
+skills in specific areas by taking the courses [Parallel Programming],
+[Big Data Analysis with Scala and Spark], or [Programming Reactive Systems].
+
+## Scala Specialization
+
+The [Scala Specialization] provides a hands-on introduction to functional programming using Scala. You can access the courses
+material and exercises by either signing up for the specialization or auditing the courses individually. The
+specialization has the following courses.
+* [Functional Programming Principles in Scala],
+* [Functional Program Design in Scala],
+* [Parallel programming],
+* [Big Data Analysis with Scala and Spark],
+* [Functional Programming in Scala Capstone].
+
+These courses provide a deep understanding of the Scala language itself,
+and they also dive into more specific topics such as parallel programming,
+and Spark.
+
+## Programming Reactive Systems
+
+[Programming Reactive Systems] (also available on [edX](https://www.edx.org/course/scala-akka-reactive))
+teaches how to write responsive, scalable, and resilient systems with the
+library Akka.
+
+## Scala 2 Courses
+
+The above courses all use Scala 3. If needed, you can find
+the (legacy) Scala 2 version of our courses here:
+
+- [Functional Programming Principles in Scala (Scala 2 version)](https://www.coursera.org/learn/scala2-functional-programming)
+- [Functional Program Design (Scala 2 version)](https://www.coursera.org/learn/scala2-functional-program-design)
+- [Parallel Programming (Scala 2 version)](https://www.coursera.org/learn/scala2-parallel-programming)
+- [Big Data Analysis with Scala and Spark (Scala 2 version)](https://www.coursera.org/learn/scala2-spark-big-data)
+- [Programming Reactive Systems (Scala 2 version)](https://www.coursera.org/learn/scala2-akka-reactive)
+
+## Testimonials
+
+{% include carousel.html images=page.testimonials number=0 height="50" unit="%" duration="10" %}
+
+## Other Online Resources
+
+You can find other online resources contributed by the community on
+[this page]({% link online-courses.md %}).
+
+[Scala Center]: https://scala.epfl.ch
+[Scala Specialization]: https://www.coursera.org/specializations/scala
+[Effective Programming in Scala]: https://www.coursera.org/learn/effective-scala
+[Functional Programming Principles in Scala]: https://www.coursera.org/learn/scala-functional-programming
+[Functional Program Design in Scala]: https://www.coursera.org/learn/scala-functional-program-design
+[Parallel programming]: https://www.coursera.org/learn/scala-parallel-programming
+[Big Data Analysis with Scala and Spark]: https://www.coursera.org/learn/scala-spark-big-data
+[Functional Programming in Scala Capstone]: https://www.coursera.org/learn/scala-capstone
+[Programming Reactive Systems]: https://www.coursera.org/learn/scala-akka-reactive
diff --git a/scripts/run-mdoc.sh b/scripts/run-mdoc.sh
index 97593abd20..fc478f83d5 100755
--- a/scripts/run-mdoc.sh
+++ b/scripts/run-mdoc.sh
@@ -1,10 +1,15 @@
#!/bin/bash
set -eux
-cs launch org.scalameta:mdoc_2.12:2.2.13 -- \
+cs launch --scala-version 2.13.16 org.scalameta::mdoc:2.3.3 -- \
--in . \
--out /tmp/mdoc-out/ \
- --classpath $(cs fetch -p com.chuusai:shapeless_2.12:2.3.3) \
+ --classpath \
+ $(cs fetch --scala-version 2.13.16 -p \
+ com.chuusai::shapeless:2.3.10 \
+ org.scala-lang::toolkit:0.1.7 \
+ org.scala-lang::toolkit-test:0.1.7 \
+ ) \
--scalac-options "-Xfatal-warnings -feature" \
--no-link-hygiene \
--include '**.md'
diff --git a/tutorials.md b/tutorials.md
new file mode 100644
index 0000000000..17ade963ba
--- /dev/null
+++ b/tutorials.md
@@ -0,0 +1,62 @@
+---
+layout: root-index-layout
+title: Tutorials
+
+tutorials:
+- title: "Getting Started with Scala in IntelliJ"
+ url: "/getting-started/intellij-track/getting-started-with-scala-in-intellij.html"
+ description: "Create a Scala project using IntelliJ IDE."
+ icon: rocket
+- title: "Getting Started with Scala and sbt"
+ url: "/getting-started/sbt-track/getting-started-with-scala-and-sbt-on-the-command-line.html"
+ description: "Create a Scala project using sbt and the command-line."
+ icon: rocket
+- title: "Scala for Java Programmers"
+ url: "/tutorials/scala-for-java-programmers.html"
+ description: "Quick introduction to the Scala language and compiler for people who already have some experience in Java."
+ icon: coffee
+- title: "Scala on Android"
+ url: "/tutorials/scala-on-android.html"
+ description: "Create an Android app in Scala."
+ icon: robot
+- title: "Scala with Maven"
+ url: "/tutorials/scala-with-maven.html"
+ description: "Create a Scala project with Maven."
+ icon: code
+---
+
+
+
+
+
+
+
+ Tutorials
++ Tutorials take you by the hand through a series of steps to create Scala applications. +
+
+ {% for tutorial in page.tutorials %}
+
+
+
+ {% endfor %}
+
+
+
+
+ {% if tutorial.icon %}
+
+
+
+ {% endif %}
+
+
{{ tutorial.title }}
+
+ {% if tutorial.by %}
+ By {{ tutorial.by }}
{% endif %}
+ {% if tutorial.description %}{{ tutorial.description }}
{% endif %} +