Add CommandInfo

Author: nicolasstucki

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

@@ -149,11 +149,15 @@ object MainProxies {
    *     final class f {
    *       static def main(args: Array[String]): Unit = {
    *         val cmd = new myMain(80).command(
-   *           args,
-   *           "f",
-   *           "Lorem ipsum dolor sit amet consectetur adipiscing elit.",
-   *           new scala.annotation.MainAnnotation.ParameterInfo("x", "S", false, false, "my param x", Seq(new scala.main.Alias("myX")))
-   *           new scala.annotation.MainAnnotation.ParameterInfo("ys", "T", false, false, "all my params y", Seq())
+   *           info = new CommandInfo(
+   *             name = "f",
+   *             documentation = "Lorem ipsum dolor sit amet consectetur adipiscing elit.",
+   *             parameters = Seq(
+   *               new scala.annotation.MainAnnotation.ParameterInfo("x", "S", false, false, "my param x", Seq(new scala.main.Alias("myX")))
+   *               new scala.annotation.MainAnnotation.ParameterInfo("ys", "T", false, false, "all my params y", Seq())
+   *             )
+   *           )
+   *           args = args
    *         )
    *
    *         val args0: () => S = cmd.argGetter[S](0, None)
@@ -310,16 +314,22 @@ object MainProxies {
     end instantiateAnnotation
 
     def generateMainClass(mainCall: Tree, args: List[Tree], parameterInfos: List[Tree]): TypeDef =
+      val cmdInfo =
+        val nameTree = Literal(Constant(mainFun.showName))
+        val docTree = Literal(Constant(documentation.mainDoc))
+        val paramInfos = Apply(ref(defn.SeqModule.termRef), parameterInfos)
+        New(TypeTree(defn.MainAnnotationCommandInfo.typeRef), List(List(nameTree, docTree, paramInfos)))
+
       val cmd = ValDef(
         nme.cmd,
         TypeTree(),
         Apply(
           Select(instantiateAnnotation(mainAnnot), defn.MainAnnotation_command.name),
-          Ident(nme.args) :: Literal(Constant(mainFun.showName)) :: Literal(Constant(documentation.mainDoc)) :: parameterInfos
+          List(cmdInfo, Ident(nme.args))
         )
       )
       val run = Apply(Select(Ident(nme.cmd), defn.MainAnnotationCommand_run.name), mainCall)
-      val body = Block(cmd :: args, run)
+      val body = Block(cmdInfo :: cmd :: args, run)
       val mainArg = ValDef(nme.args, TypeTree(defn.ArrayType.appliedTo(defn.StringType)), EmptyTree)
         .withFlags(Param)
       /** Replace typed `Ident`s that have been typed with a TypeSplice with the reference to the symbol.

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

@@ -853,6 +853,7 @@ class Definitions {
 
   @tu lazy val MainAnnotationClass: ClassSymbol = requiredClass("scala.annotation.MainAnnotation")
     @tu lazy val MainAnnotation_command: Symbol = MainAnnotationClass.requiredMethod("command")
+  @tu lazy val MainAnnotationCommandInfo: ClassSymbol = requiredClass("scala.annotation.MainAnnotation.CommandInfo")
   @tu lazy val MainAnnotationParameterInfo: ClassSymbol = requiredClass("scala.annotation.MainAnnotation.ParameterInfo")
     @tu lazy val MainAnnotationParameterInfo_withDocumentation: Symbol = MainAnnotationParameterInfo.requiredMethod("withDocumentation")
     @tu lazy val MainAnnotationParameterInfo_withAnnotations: Symbol = MainAnnotationParameterInfo.requiredMethod("withAnnotations")

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

@@ -19,12 +19,17 @@ When a users annotates a method with an annotation that extends `MainAnnotation`
 ```scala
 object foo {
   def main(args: Array[String]): Unit = {
+
     val cmd = new myMain().command(
-      args = args,
-      commandName = "sum",
-      documentation = "Sum all the numbers",
-      new ParameterInfo("first", "scala.Int", hasDefault=false, isVarargs=false, "Fist number to sum", Seq()),
-      new ParameterInfo("rest", "scala.Int" , hasDefault=false, isVarargs=true, "The rest of the numbers to sum", Seq())
+      info = new CommandInfo(
+        name = "sum",
+        documentation = "Sum all the numbers",
+        parameters = Seq(
+          new ParameterInfo("first", "scala.Int", hasDefault=false, isVarargs=false, "Fist number to sum", Seq()),
+          new ParameterInfo("rest", "scala.Int" , hasDefault=false, isVarargs=true, "The rest of the numbers to sum", Seq())
+        )
+      ),
+      args = args
     )
     val args0 = cmd.argGetter[Int](0, None) // using cmd.Parser[Int]
     val args1 = cmd.varargGetter[Int] // using cmd.Parser[Int]
@@ -52,20 +57,20 @@ class myMain extends MainAnnotation:
   type Result = Int
 
   /** A new command with arguments from `args` */
-  def command(args: Array[String], commandName: String, documentation: String, parameterInfos: ParameterInfo*): Command[Parser, Result] =
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result] =
     if args.contains("--help") then
-      println(documentation)
+      println(info.documentation)
       // TODO: Print documentation of the parameters
       System.exit(0)
-    assert(parameterInfos.forall(!_.hasDefault), "Default arguments are not supported")
+    assert(info.parameters.forall(!_.hasDefault), "Default arguments are not supported")
     val (plainArgs, varargs) =
-      if parameterInfos.last.isVarargs then
-        val numPlainArgs = parameterInfos.length - 1
+      if info.parameters.last.isVarargs then
+        val numPlainArgs = info.parameters.length - 1
         assert(numPlainArgs <= args.length, "Not enough arguments")
         (args.take(numPlainArgs), args.drop(numPlainArgs))
       else
-        assert(parameterInfos.length <= args.length, "Not enough arguments")
-        assert(parameterInfos.length >= args.length, "Too many arguments")
+        assert(info.parameters.length <= args.length, "Not enough arguments")
+        assert(info.parameters.length >= args.length, "Too many arguments")
         (args, Array.empty[String])
     new MyCommand(plainArgs, varargs)
 

library/src/scala/annotation/MainAnnotation.scala

@@ -24,11 +24,15 @@ package scala.annotation
  *  object foo {
  *    def main(args: Array[String]): Unit = {
  *      val cmd = new myMain().command(
- *        args = args,
- *        commandName = "sum",
- *        documentation = "Sum all the numbers",
- *        new ParameterInfo("first", "scala.Int", hasDefault=false, isVarargs=false, "Fist number to sum"),
- *        new ParameterInfo("rest", "scala.Int" , hasDefault=false, isVarargs=true, "The rest of the numbers to sum")
+ *        info = new CommandInfo(
+ *          name = "foo.main",
+ *          documentation = "Sum all the numbers",
+ *          parameters = Seq(
+ *            new ParameterInfo("first", "scala.Int", hasDefault=false, isVarargs=false, "Fist number to sum"),
+ *            new ParameterInfo("rest", "scala.Int" , hasDefault=false, isVarargs=true, "The rest of the numbers to sum")
+ *          )
+ *        )
+ *        args = args
  *      )
  *      val args0 = cmd.argGetter[Int](0, None) // using cmd.Parser[Int]
  *      val args1 = cmd.varargGetter[Int] // using cmd.Parser[Int]
@@ -52,18 +56,38 @@ trait MainAnnotation extends StaticAnnotation:
 
   /** A new command with arguments from `args`
    *
+   *  @param info The information about the command (name, documentation and info about parameters)
    *  @param args The command line arguments
-   *  @param commandName The name of the command (name of the annotated method)
-   *  @param documentation The documentation of the command (without the `@param` documentation)
-   *  @param parameterInfos Information about all the parameters (name, type, has default, is varargs and documentation)
    */
-  def command(args: Array[String], commandName: String, documentation: String, parameterInfos: ParameterInfo*): Command[Parser, Result]
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result]
 
 end MainAnnotation
 
 @experimental
 object MainAnnotation:
 
+  /** A class representing a command to run */
+  trait Command[Parser[_], Result]:
+
+    /** 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](idx: Int, defaultArgument: Option[() => T])(using Parser[T]): () => T
+
+    /** The getter for a final varargs argument of type `T*` */
+    def varargGetter[T](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 Command
+
+  final class CommandInfo(val name: String, val documentation: String, val parameters: Seq[ParameterInfo])
+
   /** ParameterInfo with a name, the type of the parameter and if it has a default
    *
    *  @param name The name of the parameter
@@ -79,7 +103,7 @@ object MainAnnotation:
     paramIsVarargs: Boolean,
     paramDocumentation: String,
     paramAnnotations: Seq[ParameterAnnotation],
-  ) {
+  ):
 
     /** The name of the parameter */
     def name: String = paramName
@@ -100,27 +124,10 @@ object MainAnnotation:
     def annotations: Seq[ParameterAnnotation] = paramAnnotations
 
     override def toString: String = s"$name: $typeName"
-  }
 
-  /** A class representing a command to run */
-  trait Command[Parser[_], Result]:
+  end ParameterInfo
 
-    /** 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](idx: Int, defaultArgument: Option[() => T])(using Parser[T]): () => T
 
-    /** The getter for a final varargs argument of type `T*` */
-    def varargGetter[T](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 Command
 
   /** Marker trait for annotations that will be included in the ParameterInfo annotations. */
   trait ParameterAnnotation extends StaticAnnotation

tests/run/main-annotation-example.scala

@@ -21,7 +21,7 @@ end Test
 
 @experimental
 class myMain extends MainAnnotation:
-  import MainAnnotation.{ ParameterInfo, Command }
+  import MainAnnotation.{ Command, CommandInfo, ParameterInfo }
 
   // Parser used to parse command line arguments
   type Parser[T] = util.CommandLineParser.FromString[T]
@@ -30,19 +30,19 @@ class myMain extends MainAnnotation:
   type Result = Int
 
   /** A new command with arguments from `args` */
-  def command(args: Array[String], commandName: String, documentation: String, parameterInfos: ParameterInfo*): Command[Parser, Result] =
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result] =
     if args.contains("--help") then
-      println(documentation)
+      println(info.documentation)
       System.exit(0)
-    assert(parameterInfos.forall(!_.hasDefault), "Default arguments are not supported")
+    assert(info.parameters.forall(!_.hasDefault), "Default arguments are not supported")
     val (plainArgs, varargs) =
-      if parameterInfos.last.isVarargs then
-        val numPlainArgs = parameterInfos.length - 1
+      if info.parameters.last.isVarargs then
+        val numPlainArgs = info.parameters.length - 1
         assert(numPlainArgs <= args.length, "Not enough arguments")
         (args.take(numPlainArgs), args.drop(numPlainArgs))
       else
-        assert(parameterInfos.length <= args.length, "Not enough arguments")
-        assert(parameterInfos.length >= args.length, "Too many arguments")
+        assert(info.parameters.length <= args.length, "Not enough arguments")
+        assert(info.parameters.length >= args.length, "Too many arguments")
         (args, Array.empty[String])
     new MyCommand(plainArgs, varargs)
 

tests/run/main-annotation-homemade-annot-1.scala

@@ -35,13 +35,13 @@ class mainAwait(timeout: Int = 2) extends MainAnnotation:
   override type Result = Future[Any]
 
   // This is a toy example, it only works with positional args
-  override def command(args: Array[String], commandName: String, docComment: String, parameterInfos: ParameterInfo*) =
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result] =
     new Command[Parser, Result]:
       override def argGetter[T](idx: Int, defaultArgument: Option[() => T])(using p: Parser[T]): () => T =
         () => p.fromString(args(idx))
 
       override def varargGetter[T](using p: Parser[T]): () => Seq[T] =
-        () => for i <- ((parameterInfos.length-1) until args.length) yield p.fromString(args(i))
+        () => for i <- ((info.parameters.length-1) until args.length) yield p.fromString(args(i))
 
       override def run(f: () => Result): Unit = println(Await.result(f(), Duration(timeout, SECONDS)))
 end mainAwait

tests/run/main-annotation-homemade-annot-2.scala

@@ -34,14 +34,14 @@ class myMain(runs: Int = 3)(after: String*) extends MainAnnotation:
   override type Parser[T] = util.CommandLineParser.FromString[T]
   override type Result = Any
 
-  override def command(args: Array[String], commandName: String, docComment: String, parameterInfos: ParameterInfo*) =
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result] =
     new Command[Parser, Result]:
 
       override def argGetter[T](idx: Int, defaultArgument: Option[() => T])(using p: Parser[T]): () => T =
         () => p.fromString(args(idx))
 
       override def varargGetter[T](using p: Parser[T]): () => Seq[T] =
-        () => for i <- (parameterInfos.length until args.length) yield p.fromString(args(i))
+        () => for i <- (info.parameters.length until args.length) yield p.fromString(args(i))
 
       override def run(f: () => Result): Unit =
         for (_ <- 1 to runs)

tests/run/main-annotation-homemade-annot-3.scala

@@ -16,7 +16,7 @@ class mainNoArgs extends MainAnnotation:
   override type Parser[T] = util.CommandLineParser.FromString[T]
   override type Result = Any
 
-  override def command(args: Array[String], commandName: String, docComment: String, parameterInfos: ParameterInfo*) =
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result] =
     new Command[Parser, Result]:
       override def argGetter[T](idx: Int, defaultArgument: Option[() => T])(using p: Parser[T]): () => T = ???
 

tests/run/main-annotation-homemade-annot-4.scala

@@ -16,7 +16,7 @@ class mainManyArgs(i1: Int, s2: String, i3: Int) extends MainAnnotation:
   override type Parser[T] = util.CommandLineParser.FromString[T]
   override type Result = Any
 
-  override def command(args: Array[String], commandName: String, docComment: String, parameterInfos: ParameterInfo*) =
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result] =
     new Command[Parser, Result]:
       override def argGetter[T](idx: Int, optDefaultGetter: Option[() => T])(using p: Parser[T]): () => T = ???
 

tests/run/main-annotation-homemade-annot-5.scala

@@ -18,7 +18,7 @@ class mainManyArgs(o: Option[Int]) extends MainAnnotation:
   override type Parser[T] = util.CommandLineParser.FromString[T]
   override type Result = Any
 
-  override def command(args: Array[String], commandName: String, docComment: String, parameterInfos: ParameterInfo*) =
+  def command(info: CommandInfo, args: Array[String]): Command[Parser, Result] =
     new Command[Parser, Result]:
       override def argGetter[T](idx: Int, defaultArgument: Option[() => T])(using p: Parser[T]): () => T = ???