scala.annotation

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()*))
  }
}

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.

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.

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

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.

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

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").

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.

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

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

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.

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.

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.

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.