[转]Scala: How do I find what some symbol means or does?

原文：http://docs.scala-lang.org/tutorials/FAQ/finding-symbols.html

 

Let’s divide the operators, for the purpose of teaching, into four categories:

• Keywords/reserved symbols
• Automatically imported methods
• Common methods
• Syntactic sugars/composition

And let’s see some arbitrary examples:

1. -> // Automatically imported method
2. <- // Keyword
3. ||= // Syntactic sugar
4. ++= // Syntactic sugar/composition or common method
5. <= // Common method
6. _+_ // Keyword/composition
7. :: // Common method or object
8. :+= // Common method

The exact meaning of most of these methods depend on the class that is defining them. For example, <= on Int means “less than or equal to”, but it might mean something else in another class. :: is probably the method defined on List but it could also be the object of the same name.

So, let’s see them.

Keywords/reserved symbols

There are a few symbols in Scala that are special and cannot be defined or used used as method names. Two of them are considered proper keywords, while others are just “reserved”. They are:

1. // Keywords
2. <- // Used on for-comprehensions, to separate pattern from generator
3. => // Used for function types, function literals and import renaming
5. // Reserved
6. ( ) // Delimit expressions and parameters
7. [ ] // Delimit type parameters
8. { } // Delimit blocks
9. . // Method call and path separator
10. // /* */ // Comments
11. # // Used in type notations
12. : // Type ascription or context bounds
13. <: >: <% // Upper, lower and view bounds
14. " """ // Strings
15. ' // Indicate symbols and characters
16. @ // Annotations and variable binding on pattern matching
17. ` // Denote constant or enable arbitrary identifiers
18. , // Parameter separator
19. ; // Statement separator
20. _* // vararg expansion
21. _ // Many different meanings

These are all part of the language, and, as such, can be found in any text that properly describe the language, such as Scala Specification(PDF) itself.

The last one, the underscore, deserve a special description, because it is widely used, and has different meanings depending on the context. Here’s a sample:

1. import scala._ // Wild card -- all of Scala is imported
2. import scala.{ Predef => _, _ } // Exclusion, everything except Predef
3. def f[M[_]] // Higher kinded type parameter
4. def f(m: M[_]) // Existential type
5. _ + _ // Anonymous function placeholder parameter
6. m _ // Eta expansion of method into method value
7. m(_) // Partial function application
8. _ => 5 // Discarded parameter
9. case _ => // Wild card pattern -- matches anything
10. f(xs: _*) // Sequence xs is passed as multiple parameters to f(ys: T*)
11. case Seq(xs @ _*) // Identifier xs is bound to the whole matched sequence

Automatically imported methods

If you did not find the symbol you are looking for in the list above, then it must be a method, or part of one. But, often, you’ll see some symbol and the documentation for the class will not have that method. When this happens, either you are looking at a composition of one or more methods with something else, or the method has been imported into scope, or is available through an imported implicit conversion.

These can also be found in ScalaDoc’s index.

Every Scala code has three automatic imports:

1. // Not necessarily in this order
2. import java.lang._
3. import scala._
4. import scala.Predef._

The first two only make classes and singleton objects available. The third one contains all implicit conversions and imported methods, since Predef is an object itself.

Looking inside Predef quickly shows some symbols:

1. class <:<
2. class =:=
3. object <%<
4. object =:=

Any other symbol will be made available through an implicit conversion. Just look at the methods tagged with implicit that receive, as parameter, an object of type that is receiving the method. For example:

1. "a" -> 1 // Look for an implicit from String, AnyRef, Any or type parameter

In the above case, -> is defined in the class ArrowAssoc through the method any2ArrowAssocthat takes an object of type A, where A is an unbounded type parameter to the same method.

Common methods

Many symbols are simply methods on a class. For instance, if you do

1. List(1, 2) ++ List(3, 4)

You’ll find the method ++ right on the ScalaDoc for List. However, there’s one convention that you must be aware when searching for methods. Methods ending in colon (:) bind to the right instead of the left. In other words, while the above method call is equivalent to:

1. List(1, 2).++(List(3, 4))

If I had, instead 1 :: List(2, 3), that would be equivalent to:

1. List(2, 3).::(1)

So you need to look at the type found on the right when looking for methods ending in colon. Consider, for instance:

1. 1 +: List(2, 3) :+ 4

The first method (+:) binds to the right, and is found on List. The second method (:+) is just a normal method, and binds to the left – again, on List.

Syntactic sugars/composition

So, here’s a few syntactic sugars that may hide a method:

1. class Example(arr: Array[Int] = Array.fill(5)(0)) {
2. def apply(n: Int) = arr(n)
3. def update(n: Int, v: Int) = arr(n) = v
4. def a = arr(0); def a_=(v: Int) = arr(0) = v
5. def b = arr(1); def b_=(v: Int) = arr(1) = v
6. def c = arr(2); def c_=(v: Int) = arr(2) = v
7. def d = arr(3); def d_=(v: Int) = arr(3) = v
8. def e = arr(4); def e_=(v: Int) = arr(4) = v
9. def +(v: Int) = new Example(arr map (_ + v))
10. def unapply(n: Int) = if (arr.indices contains n) Some(arr(n)) else None
11. }
13. var ex = new Example
14. println(ex(0)) // calls apply(0)
15. ex(0) = 2 // calls update(0, 2)
16. ex.b = 3 // calls b_=(3)
17. val ex(c) = 2 // calls unapply(2) and assigns result to c
18. ex += 1 // substituted for ex = ex + 1

The last one is interesting, because any symbolic method can be combined to form an assignment-like method that way.

And, of course, there’s various combinations that can appear in code:

1. (_+_) // An expression, or parameter, that is an anonymous function with
2. // two parameters, used exactly where the underscores appear, and
3. // which calls the "+" method on the first parameter passing the
4. // second parameter as argument.

This answer was originally submitted in response to this question on Stack Overflow.