scala.annotation
package scala.annotation
Type members
Classlikes
abstract class Annotation
A base class for annotations.
Annotations extending this class directly are not preserved in the classfile. To enable storing
annotations in the classfile's Scala signature and make it available to Scala reflection and
other tools, the annotation needs to inherit from scala.annotation.StaticAnnotation.
Annotation classes defined in Scala are not stored in classfiles in a Java-compatible manner
and therefore not visible in Java reflection. In order to achieve this, the annotation has to
be written in Java.
- Source
- (source)
@deprecated("Annotation classes need to be written in Java in order to be stored in classfiles in a Java-compatible manner", "2.13.0")
A base class for classfile annotations. These are stored as
Java annotations]
in classfiles.
- Source
- (source)
Annotation classes extending this trait only accept constant values as arguments.
Note that this trait extends StaticAnnotation, so constant annotations are persisted in the
classfile.
The implementation requires arguments of constant annotations to be passed as named arguments,
except if there is a single argument, which then defines the annotation's parameter named
value
.Constant annotations may use default arguments. Note that the internal representation of an
annotation usage (which is visible for compiler plugins, for example) only contains arguments
that are explicitly provided.
Constant annotations are not allowed to define auxiliary constructors, and the primary
constructor is required to have a single parameter list.
Example:
class Ann(value: Int, x: Int = 0) extends scala.annotation.ConstantAnnotation
class Test {
def someInt = 0
@Ann(value = 0, x = 1) def g = 0
@Ann(0) def f = 0 // Internal representation contains `@Ann(value = 0)`
@Ann(someInt) // error: argument needs to be a compile-time constant
}
- Source
- (source)
A base trait for annotations that yield proper subtypes of the types they annotate.
Refining annotations are more "sticky" than normal ones. They are conceptually kept
around when normal refinements would also not be stripped away.
- Source
- (source)
A base class for static annotations. These are available to the Scala type checker or Scala
reflection, even across different compilation units.
Annotation classes defined in Scala are not stored in classfiles in a Java-compatible manner
and therefore not visible in Java reflection. In order to achieve this, the annotation has to
be written in Java.
- Source
- (source)
A marker for annotations that, when applied to a type, should be treated
as a constraint on the annotated type.
A proper constraint should restrict the type based only on information
mentioned within the type. A Scala compiler can use this assumption to
rewrite the contents of the constraint as necessary. To contrast, a type
annotation whose meaning depends on the context where it is written
down is not a proper constrained type, and this marker should not be
applied. A Scala compiler will drop such annotations in cases where it
would rewrite a type constraint.
- Source
- (source)
@deprecated("use @targetName instead")
An annotation that defines an external name for a definition.
If an
alpha(extname)
annotation is given for a method or some other
definition, its implementation will use the name extname
instead of
the regular name. An alpha
annotation is mandatory for definitions
with symbolic names.
- Source
- (source)
An annotation that designates that an annottee should not be referred to after
type checking (which includes macro expansion).
Examples of potential use:
1) The annottee can only appear in the arguments of some other macro
that will eliminate it from the AST during expansion.
2) The annottee is a macro and should have been expanded away,
so if hasn't, something wrong has happened.
(Comes in handy to provide better support for new macro flavors,
e.g. macro annotations, that can't be expanded by the vanilla compiler).
- Value Params
- message
-
the error message to print during compilation if a reference remains after type checking
- Source
- (source)
An annotation that goes on parameters of classes or traits. It asserts
that the parameter is used only for initialization and is not kept in
the class as a field. Violations of this assertion are flagged as
compile errors. The annotation is particularly useful for implicit
parameters since for these a textual scan is not sufficient to know
where they are used.
- Source
- (source)
An annotation for methods whose bodies may be excluded
from compiler-generated bytecode.
Behavior is influenced by passing
-Xelide-below <arg>
to scalac
.
Calls to methods marked elidable (as well as the method body) will
be omitted from generated code if the priority given the annotation
is lower than that given on the command line.@elidable(123) // annotation priority
scalac -Xelide-below 456 // command line priority
The method call will be replaced with an expression which depends on
the type of the elided expression. In decreasing order of precedence:
Unit ()
Boolean false
T <: AnyVal 0
T >: Null null
T >: Nothing Predef.???
Complete example:
import scala.annotation._, elidable._
object Test extends App {
def expensiveComputation(): Int = { Thread.sleep(1000) ; 172 }
@elidable(WARNING) def warning(msg: String) = println(msg)
@elidable(FINE) def debug(msg: String) = println(msg)
@elidable(FINE) def computedValue = expensiveComputation()
warning("Warning! Danger! Warning!")
debug("Debug! Danger! Debug!")
println("I computed a value: " + computedValue)
}
% scalac example.scala && scala Test
Warning! Danger! Warning!
Debug! Danger! Debug!
I computed a value: 172
// INFO lies between WARNING and FINE
% scalac -Xelide-below INFO example.scala && scala Test
Warning! Danger! Warning!
I computed a value: 0
Note that only concrete methods can be marked
@elidable
. A non-annotated method
is not elided, even if it overrides / implements a method that has the annotation.Also note that the static type determines which annotations are considered:
import scala.annotation._, elidable._
class C { @elidable(0) def f(): Unit = ??? }
object O extends C { override def f(): Unit = println("O.f") }
object Test extends App {
O.f() // not elided
(O: C).f() // elided if compiled with `-Xelide-below 1`
}
object elidable
This useless appearing code was necessary to allow people to use
named constants for the elidable annotation. This is what it takes
to convince the compiler to fold the constants: otherwise when it's
time to check an elision level it's staring at a tree like
To customize the error message that's emitted when an implicit search finds
multiple ambiguous values, annotate at least one of the implicit values
@implicitAmbiguous
. Assuming the implicit value is a method with type
parameters X1,..., XN
, the error message will be the result of replacing
all occurrences of ${Xi}
in the string msg
with the string representation
of the corresponding type argument Ti
.If more than one
@implicitAmbiguous
annotation is collected, the compiler is
free to pick any of them to display.Nice errors can direct users to fix imports or even tell them why code
intentionally doesn't compile.
trait =!=[C, D]
implicit def neq[E, F] : E =!= F = null
@annotation.implicitAmbiguous("Could not prove ${J} =!= ${J}")
implicit def neqAmbig1[G, H, J] : J =!= J = null
implicit def neqAmbig2[I] : I =!= I = null
implicitly[Int =!= Int]
- Source
- (source)
To customize the error message that's emitted when an implicit of type
C[T1,..., TN]
cannot be found, annotate the class C
with @implicitNotFound
.
Assuming C
has type parameters X1, ..., XN
, the error message will be the
result of replacing all occurrences of ${Xi}
in the string msg
with the
string representation of the corresponding type argument Ti
.
The annotation is effectively inherited by subtypes if they are not annotated.The annotation can also be attached to implicit parameters. In this case,
${Xi}
can refer to type parameters in the current scope. The @implicitNotFound
message
on the parameter takes precedence over the one on the parameter's type.import scala.annotation.implicitNotFound
@implicitNotFound("Could not find an implicit C[${T}, ${U}]")
class C[T, U]
class K[A] {
def m[B](implicit c: C[List[A], B]) = 0
def n[B](implicit @implicitNotFound("Specific message for C of list of ${A} and ${B}") c: C[List[A], B]) = 1
}
object Test {
val k = new K[Int]
k.m[String]
k.n[String]
}
The compiler issues the following error messages:
Test.scala:13: error: Could not find an implicit C[List[Int], String] k.m[String] ^ Test.scala:14: error: Specific message for C of list of Int and String k.n[String] ^
- Source
- (source)
An annotation for local warning suppression.
The optional
value
parameter allows selectively silencing messages, see scalac -Wconf:help
for help. Examples:def f = {
1: @nowarn // don't warn "a pure expression does nothing in statement position"
2
}
@nowarn def f = { 1; deprecated() } // don't warn
@nowarn("msg=pure expression does nothing")
def f = { 1; deprecated() } // show deprecation warning
To ensure that a
@nowarn
annotation actually suppresses a warning, enable -Xlint:unused
or -Wunused:nowarn
.
- Source
- (source)
@deprecatedInheritance("Scheduled for being final in the future", "2.13.0")
This annotation configures how Scala prints two-parameter generic types.
By default, types with symbolic names are printed infix; while types without
them are printed using the regular generic type syntax.
Example of usage:
scala> class Map[T, U]
defined class Map
scala> def foo: Int Map Int = ???
foo: Map[Int,Int]
scala> @showAsInfix class Map[T, U]
defined class Map
scala> def foo: Int Map Int = ???
foo: Int Map Int
- Value Params
- enabled
-
whether to show this type as an infix type operator.
- Source
- (source)
@field @getter @beanGetter @beanSetter @param @setter
https://github.com/scala/scala.github.com/pull/491
- Source
- (source)
@deprecatedInheritance("Scheduled for being final in the future", "2.13.0")
If this annotation is present on a method or its enclosing class,
the strictfp flag will be emitted.
- Source
- (source)
An annotation to be applied to a match expression. If present,
the compiler will verify that the match has been compiled to a
tableswitch or lookupswitch
and issue a warning if it instead compiles into a series of conditional expressions.
Example usage:
val Constant = 'Q'
def tokenMe(ch: Char) = (ch: @switch) match {
case ' ' | '\t' | '\n' => 1
case 'A' | 'Z' | '$' => 2
case '5' | Constant => 3 // a non-literal may prevent switch generation: this would not compile
case _ => 4
}
Note: for pattern matches with one or two cases, the compiler generates jump instructions.
Annotating such a match with
@switch
does not issue any warning.
- Source
- (source)
A method annotation which verifies that the method will be compiled
with tail call optimization.
If it is present, the compiler will issue an error if the method cannot
be optimized into a loop.
- Source
- (source)
An annotation that defines an external name for a definition.
If an
targetName(extname)
annotation is given for a method or some other
definition, its implementation will use the name extname
instead of
the regular name.
- Source
- (source)
This annotation can only be used on a field which defines a lazy val.
When this annotation is used, the initialization of the lazy val will use a
faster mechanism which is not thread-safe.
- Source
- (source)
An annotation that can be used from Scala 2 to mark a trait as transparent.
Scala 3 code would use the modifier
transparent
instead. Transparent traits
are not inferred when combined with other types in an intersection.
See reference/other-new-features/transparent-traits.html for details.
- Source
- (source)
@deprecatedInheritance("Scheduled for being final in the future", "2.13.0")
A method annotation which suppresses the creation of
additional specialized forms based on enclosing specialized
type parameters.
- Source
- (source)
Mark an element unused for a given context.
Unused warnings are suppressed for elements known to be unused.
For example, a method parameter may be marked
@unused
because the method is designed to be overridden by
an implementation that does use the parameter.
- Source
- (source)
A method annotation which instructs the compiler to generate a
Java varargs-style forwarder method for interop. This annotation can
only be applied to methods with repeated parameters.
- Source
- (source)