Merge pull request #14558 from dotty-staging/add-scala.annotation.MainAnnotation

Add `scala.annotation.MainAnnotation`

Author: nicolasstucki

compiler/src/dotty/tools/dotc/ast/MainProxies.scala

@@ -528,6 +528,8 @@ class Definitions {
     @tu lazy val Seq_lengthCompare: Symbol = SeqClass.requiredMethod(nme.lengthCompare, List(IntType))
     @tu lazy val Seq_length       : Symbol = SeqClass.requiredMethod(nme.length)
     @tu lazy val Seq_toSeq        : Symbol = SeqClass.requiredMethod(nme.toSeq)
+  @tu lazy val SeqModule: Symbol = requiredModule("scala.collection.immutable.Seq")
+
 
   @tu lazy val StringOps: Symbol = requiredClass("scala.collection.StringOps")
     @tu lazy val StringOps_format: Symbol  = StringOps.requiredMethod(nme.format)
@@ -853,6 +855,12 @@ class Definitions {
 
   @tu lazy val XMLTopScopeModule: Symbol = requiredModule("scala.xml.TopScope")
 
+  @tu lazy val MainAnnotationClass: ClassSymbol = requiredClass("scala.annotation.MainAnnotation")
+  @tu lazy val MainAnnotationInfo: ClassSymbol = requiredClass("scala.annotation.MainAnnotation.Info")
+  @tu lazy val MainAnnotationParameter: ClassSymbol = requiredClass("scala.annotation.MainAnnotation.Parameter")
+  @tu lazy val MainAnnotationParameterAnnotation: ClassSymbol = requiredClass("scala.annotation.MainAnnotation.ParameterAnnotation")
+  @tu lazy val MainAnnotationCommand: ClassSymbol = requiredClass("scala.annotation.MainAnnotation.Command")
+
   @tu lazy val CommandLineParserModule: Symbol = requiredModule("scala.util.CommandLineParser")
     @tu lazy val CLP_ParseError: ClassSymbol = CommandLineParserModule.requiredClass("ParseError").typeRef.symbol.asClass
     @tu lazy val CLP_parseArgument: Symbol = CommandLineParserModule.requiredMethod("parseArgument")

compiler/src/dotty/tools/dotc/core/Definitions.scala

@@ -397,6 +397,7 @@ object StdNames {
     val applyOrElse: N          = "applyOrElse"
     val args : N                = "args"
     val argv : N                = "argv"
+    val argGetter : N           = "argGetter"
     val arrayClass: N           = "arrayClass"
     val arrayElementClass: N    = "arrayElementClass"
     val arrayType: N            = "arrayType"
@@ -427,6 +428,8 @@ object StdNames {
     val classOf: N              = "classOf"
     val classType: N            = "classType"
     val clone_ : N              = "clone"
+    val cmd: N                  = "cmd"
+    val command: N              = "command"
     val common: N               = "common"
     val compiletime : N         = "compiletime"
     val conforms_ : N           = "$conforms"
@@ -540,6 +543,7 @@ object StdNames {
     val ordinalDollar: N        = "$ordinal"
     val ordinalDollar_ : N      = "_$ordinal"
     val origin: N               = "origin"
+    val parameters: N           = "parameters"
     val parts: N                = "parts"
     val postfixOps: N           = "postfixOps"
     val prefix : N              = "prefix"
@@ -613,6 +617,7 @@ object StdNames {
     val fromOrdinal: N          = "fromOrdinal"
     val values: N               = "values"
     val view_ : N               = "view"
+    val varargGetter : N        = "varargGetter"
     val wait_ : N               = "wait"
     val wildcardType: N         = "wildcardType"
     val withFilter: N           = "withFilter"

compiler/src/dotty/tools/dotc/core/StdNames.scala

@@ -1351,12 +1351,13 @@ trait Checking {
   def checkAnnotApplicable(annot: Tree, sym: Symbol)(using Context): Boolean =
     !ctx.reporter.reportsErrorsFor {
       val annotCls = Annotations.annotClass(annot)
+      val concreteAnnot = Annotations.ConcreteAnnotation(annot)
       val pos = annot.srcPos
-      if (annotCls == defn.MainAnnot) {
+      if (annotCls == defn.MainAnnot || concreteAnnot.matches(defn.MainAnnotationClass)) {
         if (!sym.isRealMethod)
-          report.error(em"@main annotation cannot be applied to $sym", pos)
+          report.error(em"main annotation cannot be applied to $sym", pos)
         if (!sym.owner.is(Module) || !sym.owner.isStatic)
-          report.error(em"$sym cannot be a @main method since it cannot be accessed statically", pos)
+          report.error(em"$sym cannot be a main method since it cannot be accessed statically", pos)
       }
       // TODO: Add more checks here
     }

compiler/src/dotty/tools/dotc/typer/Checking.scala

@@ -2602,7 +2602,7 @@ class Typer(@constructorOnly nestingLevel: Int = 0) extends Namer
           pkg.moduleClass.info.decls.lookup(topLevelClassName).ensureCompleted()
           var stats1 = typedStats(tree.stats, pkg.moduleClass)._1
           if (!ctx.isAfterTyper)
-            stats1 = stats1 ++ typedBlockStats(MainProxies.mainProxies(stats1))._1
+            stats1 = stats1 ++ typedBlockStats(MainProxies.proxies(stats1))._1
           cpy.PackageDef(tree)(pid1, stats1).withType(pkg.termRef)
         }
       case _ =>

compiler/src/dotty/tools/dotc/typer/Typer.scala

@@ -0,0 +1,97 @@
+---
+layout: doc-page
+title: "MainAnnotation"
+---
+
+`MainAnnotation` provides a generic way to define main annotations such as `@main`.
+
+When a users annotates a method with an annotation that extends `MainAnnotation` a class with a `main` method will be generated. The main method will contain the code needed to parse the command line arguments and run the application.
+
+```scala
+/** 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
+```
+
+```scala
+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", Seq()),
+        new Parameter("second", "scala.Int", hasDefault=true, isVarargs=false, "", Seq()),
+        new Parameter("rest", "scala.Int" , hasDefault=false, isVarargs=true, "The rest of the numbers to sum", Seq())
+      )
+    )
+    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 a parser of Int
+      val args1 = mainAnnot.argGetter[Int](info.parameters(1), mainArgs(1), Some(() => sum$default$1())) // using a parser of Int
+      val args2 = mainAnnot.varargGetter[Int](info.parameters(2), mainArgs.drop(2)) // using a parser of Int
+      mainAnnot.run(() => sum(args0(), args1(), args2()*))
+  }
+}
+```
+
+The implementation of the `main` method first instantiates the annotation and then call `command`.
+When calling the `command`, the arguments can be checked and preprocessed.
+Then it defines a series of argument getters calling `argGetter` for each parameter and `varargGetter` for the last one if it is a varargs. `argGetter` gets an optional lambda that computes the default argument.
+Finally, the `run` method is called to run the application. It receives a by-name argument that contains the call the annotated method with the instantiations arguments (using the lambdas from `argGetter`/`varargGetter`).
+
+
+Example of implementation of `myMain` that takes all arguments positionally. It used `util.CommandLineParser.FromString` and expects no default arguments. For simplicity, any errors in preprocessing or parsing results in crash.
+
+```scala
+// Parser used to parse command line arguments
+import scala.util.CommandLineParser.FromString[T]
+
+// Result type of the annotated method is Int and arguments are parsed using FromString
+@experimental class myMain extends MainAnnotation[FromString, Int]:
+  import MainAnnotation.{ Info, Parameter }
+
+  def command(info: Info, args: Seq[String]): Option[Seq[String]] =
+    if args.contains("--help") then
+      println(info.documentation)
+      None // do not parse or run the program
+    else if info.parameters.exists(_.hasDefault) then
+      println("Default arguments are not supported")
+      None
+    else if info.hasVarargs then
+      val numPlainArgs = info.parameters.length - 1
+      if numPlainArgs <= args.length then
+        println("Not enough arguments")
+        None
+      else
+        Some(args)
+    else
+      if info.parameters.length <= args.length then
+        println("Not enough arguments")
+        None
+      else if info.parameters.length >= args.length then
+        println("Too many arguments")
+        None
+      else
+        Some(args)
+
+  def argGetter[T](param: Parameter, arg: String, defaultArgument: Option[() => T])(using parser: FromString[T]): () => T =
+    () => parser.fromString(arg)
+
+  def varargGetter[T](param: Parameter, args: Seq[String])(using parser: FromString[T]): () => Seq[T] =
+    () => args.map(arg => parser.fromString(arg))
+
+  def run(program: () => Int): Unit =
+    println("executing program")
+
+    try {
+      val result = program()
+      println("result: " + result)
+      println("executed program")
+end myMain
+```

docs/_docs/reference/experimental/main-annotation.md

@@ -147,6 +147,7 @@ subsection:
           - page: reference/experimental/named-typeargs-spec.md
           - page: reference/experimental/numeric-literals.md
           - page: reference/experimental/explicit-nulls.md
+          - page: reference/experimental/main-annotation.md
           - page: reference/experimental/cc.md
           - page: reference/experimental/tupled-function.md
       - page: reference/syntax.md

docs/sidebar.yml

@@ -0,0 +1,126 @@
+package 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:
+ *  ```scala
+ *  /** 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
+ *  ```scala
+ *  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()*))
+ *    }
+ *  }
+ *  ```
+ *
+ *  @param Parser The class used for argument string parsing and arguments into a `T`
+ *  @param Result The required result type of the main method.
+ *                If this type is Any or Unit, any type will be accepted.
+ */
+@experimental
+trait MainAnnotation[Parser[_], Result] extends StaticAnnotation:
+  import MainAnnotation.{Info, Parameter}
+
+  /** Process the command arguments before parsing them.
+   *
+   *  Return `Some` of the sequence of arguments that will be parsed to be passed to the main method.
+   *  This sequence needs to have the same length as the number of parameters of the main method (i.e. `info.parameters.size`).
+   *  If there is a varags parameter, then the sequence must be at least of length `info.parameters.size - 1`.
+   *
+   *  Returns `None` if the arguments are invalid and parsing and run should be stopped.
+   *
+   *  @param info The information about the command (name, documentation and info about parameters)
+   *  @param args The command line arguments
+   */
+  def command(info: Info, args: Seq[String]): Option[Seq[String]]
+
+  /** The getter for the `idx`th argument of type `T`
+   *
+   *   @param idx The index of the argument
+   *   @param defaultArgument Optional lambda to instantiate the default argument
+   */
+  def argGetter[T](param: Parameter, arg: String, defaultArgument: Option[() => T])(using Parser[T]): () => T
+
+  /** The getter for a final varargs argument of type `T*` */
+  def varargGetter[T](param: Parameter, args: Seq[String])(using Parser[T]): () => Seq[T]
+
+  /** Run `program` if all arguments are valid if all arguments are valid
+   *
+   *  @param program A function containing the call to the main method and instantiation of its arguments
+   */
+  def run(program: () => Result): Unit
+
+end MainAnnotation
+
+@experimental
+object MainAnnotation:
+
+  /** Information about the main method
+   *
+   *  @param name The name of the main method
+   *  @param documentation The documentation of the main method without the `@param` documentation (see Parameter.documentaion)
+   *  @param parameters Information about the parameters of the main method
+   */
+  final class Info(
+    val name: String,
+    val documentation: String,
+    val parameters: Seq[Parameter],
+  ):
+
+    /** If the method ends with a varargs parameter */
+    def hasVarargs: Boolean = parameters.nonEmpty && parameters.last.isVarargs
+
+  end Info
+
+  /** Information about a parameter of a main method
+   *
+   *  @param name The name of the parameter
+   *  @param typeName The name of the parameter's type
+   *  @param hasDefault If the parameter has a default argument
+   *  @param isVarargs If the parameter is a varargs parameter (can only be true for the last parameter)
+   *  @param documentation The documentation of the parameter (from `@param` documentation in the main method)
+   *  @param annotations The annotations of the parameter that extend `ParameterAnnotation`
+   */
+  final class Parameter(
+    val name: String,
+    val typeName: String,
+    val hasDefault: Boolean,
+    val isVarargs: Boolean,
+    val documentation: String,
+    val annotations: Seq[ParameterAnnotation],
+  )
+
+  /** Marker trait for annotations that will be included in the Parameter annotations. */
+  trait ParameterAnnotation extends StaticAnnotation
+
+end MainAnnotation

library/src/scala/annotation/MainAnnotation.scala

@@ -3,13 +3,21 @@ import com.typesafe.tools.mima.core._
 
 object MiMaFilters {
   val Library: Seq[ProblemFilter] = Seq(
-
-    // Those are OK because user code is not allowed to inherit from Quotes:
+    // Experimental APIs that can be added in 3.2.0 or later
+    ProblemFilters.exclude[DirectMissingMethodProblem]("scala.runtime.Tuples.append"),
     ProblemFilters.exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#SymbolMethods.asQuotes"),
     ProblemFilters.exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#ClassDefModule.apply"),
     ProblemFilters.exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#SymbolModule.newClass"),
     ProblemFilters.exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#SymbolMethods.typeRef"),
     ProblemFilters.exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#SymbolMethods.termRef"),
     ProblemFilters.exclude[ReversedMissingMethodProblem]("scala.quoted.Quotes#reflectModule#TypeTreeModule.ref"),
+
+    // Experimental `MainAnnotation` APIs. Can be added in 3.3.0 or later.
+    ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation"),
+    ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation$"),
+    ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation$Command"),
+    ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation$CommandInfo"),
+    ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation$ParameterInfo"),
+    ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation$ParameterAnnotation"),
   )
 }

project/MiMaFilters.scala

@@ -127,6 +127,7 @@ subsection:
       - page: reference/experimental/named-typeargs-spec.md
       - page: reference/experimental/numeric-literals.md
       - page: reference/experimental/explicit-nulls.md
+      - page: reference/experimental/main-annotation.md
       - page: reference/experimental/cc.md
   - page: reference/syntax.md
   - title: Language Versions

project/resources/referenceReplacements/sidebar.yml

@@ -68,6 +68,7 @@
 ./experimental/erased-defs.html
 ./experimental/explicit-nulls.html
 ./experimental/index.html
+./experimental/main-annotation.html
 ./experimental/named-typeargs-spec.html
 ./experimental/named-typeargs.html
 ./experimental/numeric-literals.html

project/scripts/expected-links/reference-expected-links.txt

@@ -0,0 +1,3 @@
+import scala.annotation.MainAnnotation
+
+@MainAnnotation def f(i: Int, n: Int) = () // error

tests/neg/main-annotation-mainannotation.scala

@@ -0,0 +1,3 @@
+executing program
+result: 28
+executed program