scala3-library-bootstrappedJS/scala/scala.annotation

scala.annotation

Members list

Packages

Type members

Classlikes

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.

Attributes

Source: RefiningAnnotation.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

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. Note: the annotation is copied from constructor parameters to corresponding class fields. But it is checked that the field is eliminated before code is generated.

Attributes

Source: constructorOnly.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

An annotation that can be used to mark a definition as experimental.

Attributes

See also: https://dotty.epfl.ch/docs/reference/other-new-features/experimental-defs
Source: experimental.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

https://github.com/scala/scala.github.com/pull/491

Attributes

Source: static.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

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.

Attributes

Source: targetName.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

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.

Attributes

Source: threadUnsafe.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

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.

Attributes

Source: transparentTrait.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

Deprecated classlikes

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.

Attributes

Deprecated: true
Source: alpha.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

Experimental classlikes

Base trait for macro annotation implementation. Macro annotations can transform definitions and add new definitions.

See: MacroAnnotation.transform

Attributes

Experimental: true
Source: MacroAnnotation.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

MainAnnotation provides the functionality for a compiler-generated main class. It links a compiler-generated main method (call it compiler-main) to a user written main method (user-main). The protocol of calls from compiler-main is as follows:

create a command with the command line arguments,
for each parameter of user-main, a call to command.argGetter, or command.varargGetter if is a final varargs parameter,
a call to command.run with the closure of user-main applied to all arguments.

Example:

/** Sum all the numbers
 *
 *  @param first Fist number to sum
 *  @param rest The rest of the numbers to sum
 */
@myMain def sum(first: Int, second: Int = 0, rest: Int*): Int = first + second + rest.sum

generates

object foo {
  def main(args: Array[String]): Unit = {
    val mainAnnot = new myMain()
    val info = new Info(
      name = "foo.main",
      documentation = "Sum all the numbers",
      parameters = Seq(
        new Parameter("first", "scala.Int", hasDefault=false, isVarargs=false, "Fist number to sum"),
        new Parameter("rest", "scala.Int" , hasDefault=false, isVarargs=true, "The rest of the numbers to sum")
      )
    )
    val mainArgsOpt = mainAnnot.command(info, args)
    if mainArgsOpt.isDefined then
      val mainArgs = mainArgsOpt.get
      val args0 = mainAnnot.argGetter[Int](info.parameters(0), mainArgs(0), None) // using parser Int
      val args1 = mainAnnot.argGetter[Int](info.parameters(1), mainArgs(1), Some(() => sum$default$1())) // using parser Int
      val args2 = mainAnnot.varargGetter[Int](info.parameters(2), mainArgs.drop(2)) // using parser Int
      mainAnnot.run(() => sum(args0(), args1(), args2()*))
  }
}

Value parameters

Parser: The class used for argument string parsing and arguments into a T
Result: The required result type of the main method. If this type is Any or Unit, any type will be accepted.

Attributes

Companion: object
Experimental: true
Source: MainAnnotation.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any
Known subtypes: class newMain

Attributes

Companion: trait
Experimental: true
Source: MainAnnotation.scala
Supertypes: class Object

trait Matchable

class Any
Self type: MainAnnotation.type

An annotation on a parameter type that allows implicit conversions for its arguments. Intended for use by Scala 2, to annotate Scala 2 libraries. Scala 3 uses the into modifier on the parameter type instead.

Attributes

Experimental: true
Source: allowConversions.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

Marks an annotated class as a capability. If the annotation is present and -Ycc is set, any (possibly aliased or refined) instance of the class type is implicitly augmented with the universal capture set. Example

Attributes

Experimental: true
Source: capability.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

Annotations to control the behavior of the compiler check for safe initialization of static obects.

Programmers usually do not need to use any annotations. They are intended for complex initialization code in static objects.

Attributes

Experimental: true
Source: init.scala
Supertypes: class Object

trait Matchable

class Any
Self type: init.type

The annotation that designates a main function. Main functions are entry points for Scala programs. They can be called through a command line interface by using the scala command, followed by their name and, optionally, their parameters.

The parameters of a main function may have any type T, as long as there exists a given util.CommandLineParser.FromString[T] in the scope. It will be used for parsing the string given as input into the correct argument type. These types already have parsers defined:

String,
Boolean,
Byte, Short, Int, Long, Float, Double.

The parameters of a main function may be passed either by position, or by name. Passing an argument positionally means that you give the arguments in the same order as the function's signature. Passing an argument by name means that you give the argument right after giving its name. Considering the function @newMain def foo(i: Int, str: String), we may have arguments passed:

by position: scala foo 1 abc,
by name: scala foo -i 1 --str abc or scala foo --str abc -i 1.

A mixture of both is also possible: scala foo --str abc 1 is equivalent to all previous examples.

Note that main function overloading is not currently supported, i.e. you cannot define two main methods that have the same name in the same project.

Special arguments are used to display help regarding a main function: --help and -h. If used as argument, the program will display some useful information about the main function. This help directly uses the ScalaDoc comment associated with the function, more precisely its description and the description of the parameters documented with @param. Note that if a parameter is named help or h, or if one of the parameters has as alias one of those names, the help displaying will be disabled for that argument. For example, for @newMain def foo(help: Boolean), scala foo -h will display the help, but scala foo --help will fail, as it will expect a Boolean value after --help.

Parameters may be given annotations to add functionalities to the main function:

main.alias adds other names to a parameter. For example, if a parameter node has as aliases otherNode and n, it may be addressed using --node, --otherNode or -n.

Here is an example of a main function with annotated parameters: @newMain def foo(@newMain.alias("x") number: Int, @newMain.alias("explanation") s: String). The following commands are equivalent:

scala foo --number 1 -s abc
scala foo -x 1 -s abc
scala foo --number 1 --explanation abc
scala foo -x 1 --explanation abc

Boolean parameters are considered flags that do not require the "true" or "false" value to be passed. For example, @newMain def foo(i: Boolean) can be called as foo (where i=false) or foo -i (where i=true).

The special -- marker can be used to indicate that all following arguments are passed verbatim as positional parameters. For example, @newMain def foo(args: String*) can be called as scala foo a b -- -c -d which implies that args=Seq("a", "b", "-c", "-d").

Attributes

Companion: object
Experimental: true
Source: newMain.scala
Supertypes: trait MainAnnotation[FromString, Any]

trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Experimental: true
Source: newMain.scala
Supertypes: class Object

trait Matchable

class Any
Self type: newMain.type

A binary API is a definition that is annotated with @publicInBinary. This annotation can be placed on def, val, lazy val, var, class constructors, object, and given definitions. A binary API will be publicly available in the bytecode. Tools like TASTy MiMa will take this into account to check compatibility.

This annotation cannot be used on private/private[this] definitions.

@publicInBinary can be used to guarantee access to private[T]/protected definitions:

within inline definitions,
against previous binary where this definitions was public or less private,
or through JVM reflection.

Removing this annotation from a non-public definition is a binary incompatible change. Adding this annotation to a non-public definition can also cause binary incompatibilities if the definition is accessed in an inline definition (these can be checked using -WunstableInlineAccessors).

Attributes

Experimental: true
Source: publicInBinary.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

An annotation that indicates capture of a set of references under -Ycc.

T @retains(x, y, z)

is the internal representation used for the capturing type

{x, y, z}  T

The annotation can also be written explicitly if one wants to avoid the non-standard capturing type syntax.

Attributes

Experimental: true
Source: retains.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

An annotation that indicates capture of an enclosing by-name type

Attributes

Experimental: true
Source: retainsByName.scala
Supertypes: trait StaticAnnotation

class Annotation

class Object

trait Matchable

class Any

In this article

Generated with