Rework of main.Name and main.ShortName

- Merge Name and ShortName into Alias
- Make Alias take a variable number of arguments
- Distinguish between long and short names by string length

Author: timotheeandres

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

@@ -134,7 +134,7 @@ object MainProxies {
    *       * @param ys all my params y
    *       */
    *     @main(80) def f(
-   *       @main.ShortName('x') @main.Name("myX") x: S,
+   *       @main.Alias("myX") x: S,
    *       ys: T*
    *     ) = ...
    *
@@ -148,7 +148,7 @@ object MainProxies {
    *           "Lorem ipsum dolor sit amet consectetur adipiscing elit.",
    *           new scala.annotation.MainAnnotation.ParameterInfos("x", "S")
    *             .withDocumentation("my param x")
-   *             .withAnnotations(new scala.main.ShortName('x'), new scala.main.Name("myX")),
+   *             .withAnnotations(new scala.main.Alias("myX")),
    *           new scala.annotation.MainAnnotation.ParameterInfos("ys", "T")
    *             .withDocumentation("all my params y")
    *         )

library/src/scala/main.scala

@@ -27,11 +27,11 @@ import annotation._
   * The parameters of a main function may be passed either by position, or by name. Passing an argument positionaly
   * 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
-  * `@main def foo(i: Int, s: String)`, we may have arguments passed:
+  * `@main def foo(i: Int, str: String)`, we may have arguments passed:
   * - by position: `scala foo 1 abc`,
-  * - by name: `scala foo --i 1 --s abc` or `scala foo --s abc --i 1`.
+  * - by name: `scala foo -i 1 --str abc` or `scala foo --str abc -i 1`.
   *
-  * A mixture of both is also possible: `scala foo --s abc 1` is equivalent to all previous examples.
+  * 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.
@@ -41,18 +41,15 @@ import annotation._
   * associated with the function, more precisely its description and the description of the parameters documented with
   * `@param`.
   *
-  *
   * Parameters may be given annotations to add functionalities to the main function:
-  * - `main.ShortName` adds a short name to a parameter. For example, if a parameter `node` has as short name `n`, it
-  * may be addressed using either `--node` or `-n`,
-  * - `main.Name` adds another name to a parameter. For example, if a parameter `node` has as alternative name
-  * `otherNode`, it may be addressed using either `--node` or `--otherNode`.
+  * - `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:
-  * `@main def foo(@main.ShortName('x') number: Int, @main.Name("explanation") s: String)`. The following commands are
+  * `@main def foo(@main.Alias("x") number: Int, @main.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 -s abc`
+  * - `scala foo -x 1 -s abc`
   * - `scala foo --number 1 --explanation abc`
   * - `scala foo -x 1 --explanation abc`
   *
@@ -125,8 +122,20 @@ final class main(maxLineLength: Int) extends MainAnnotation:
       private val nameToParameterInfos: Map[String, ParameterInfos] = parameterInfoss.map(infos => infos.name -> infos).toMap
 
       private val (positionalArgs, byNameArgs, invalidByNameArgs) = {
-        val namesToCanonicalName: Map[String, String] = parameterInfoss.flatMap(infos => (infos.name +: getAlternativeNames(infos)).map(_ -> infos.name)).toMap
-        val shortNamesToCanonicalName: Map[Char, String] = parameterInfoss.flatMap(infos => getShortNames(infos).map(_ -> infos.name)).toMap
+        val namesToCanonicalName: Map[String, String] = parameterInfoss.flatMap(
+          infos =>
+            var names = getAlternativeNames(infos)
+            val canonicalName = infos.name
+            if nameIsValid(canonicalName) then names = canonicalName +: names
+            names.map(_ -> canonicalName)
+        ).toMap
+        val shortNamesToCanonicalName: Map[Char, String] = parameterInfoss.flatMap(
+          infos =>
+            var names = getShortNames(infos)
+            val canonicalName = infos.name
+            if shortNameIsValid(canonicalName) then names = canonicalName(0) +: names
+            names.map(_ -> canonicalName)
+        ).toMap
 
         def getCanonicalArgName(arg: String): Option[String] =
           if arg.startsWith(argMarker) && arg.length > argMarker.length then
@@ -138,7 +147,7 @@ final class main(maxLineLength: Int) extends MainAnnotation:
 
         def isArgName(arg: String): Boolean =
           val isFullName = arg.startsWith(argMarker)
-          val isShortName = arg.startsWith(shortArgMarker) && arg.length == 2 && shortNameIsValid(arg(1))
+          val isShortName = arg.startsWith(shortArgMarker) && arg.length == shortArgMarker.length + 1 && shortNameIsValid(arg(shortArgMarker.length))
           isFullName || isShortName
 
         def recurse(remainingArgs: Seq[String], pa: mutable.Queue[String], bna: Seq[(String, String)], ia: Seq[String]): (mutable.Queue[String], Seq[(String, String)], Seq[String]) =
@@ -170,12 +179,21 @@ final class main(maxLineLength: Int) extends MainAnnotation:
         errors += msg
         () => throw new AssertionError("trying to get invalid argument")
 
-      private def nameIsValid(name: String): Boolean =
-        name.length > 0 // TODO add more checks for illegal characters
+      private inline def nameIsValid(name: String): Boolean =
+        name.length > 1 // TODO add more checks for illegal characters
+
+      private inline def shortNameIsValid(name: String): Boolean =
+        name.length == 1 && shortNameIsValid(name(0))
 
-      private def shortNameIsValid(shortName: Char): Boolean =
+      private inline def shortNameIsValid(shortName: Char): Boolean =
         ('A' <= shortName && shortName <= 'Z') || ('a' <= shortName && shortName <= 'z')
 
+      private def getNameWithMarker(name: String | Char): String = name match {
+        case c: Char => shortArgMarker + c
+        case s: String if shortNameIsValid(s) => shortArgMarker + s
+        case s => argMarker + s
+      }
+
       private def convert[T](argName: String, arg: String, p: ArgumentParser[T]): () => T =
         p.fromStringOption(arg) match
           case Some(t) => () => t
@@ -185,9 +203,9 @@ final class main(maxLineLength: Int) extends MainAnnotation:
         def argsUsage: Seq[String] =
           for ((infos, kind) <- parameterInfoss.zip(argKinds))
           yield {
-            val canonicalName = argMarker + infos.name
-            val shortNames = getShortNames(infos).map(shortArgMarker + _)
-            val alternativeNames = getAlternativeNames(infos).map(argMarker + _)
+            val canonicalName = getNameWithMarker(infos.name)
+            val shortNames = getShortNames(infos).map(getNameWithMarker)
+            val alternativeNames = getAlternativeNames(infos).map(getNameWithMarker)
             val namesPrint = (canonicalName +: alternativeNames ++: shortNames).mkString("[", " | ", "]")
 
             kind match {
@@ -241,9 +259,9 @@ final class main(maxLineLength: Int) extends MainAnnotation:
 
           println("Arguments:")
           for ((infos, kind) <- parameterInfoss.zip(argKinds))
-            val canonicalName = argMarker + infos.name
-            val shortNames = getShortNames(infos).map(shortArgMarker + _)
-            val alternativeNames = getAlternativeNames(infos).map(argMarker + _)
+            val canonicalName = getNameWithMarker(infos.name)
+            val shortNames = getShortNames(infos).map(getNameWithMarker)
+            val alternativeNames = getAlternativeNames(infos).map(getNameWithMarker)
             val otherNames = (alternativeNames ++: shortNames) match {
               case Seq() => ""
               case names => names.mkString("(", ", ", ") ")
@@ -271,28 +289,30 @@ final class main(maxLineLength: Int) extends MainAnnotation:
         }
       end explain
 
+      private def getAliases(paramInfos: ParameterInfos): Seq[String] =
+        paramInfos.annotations.collect{ case a: Alias => a }.flatMap(_.aliases)
+
       private def getAlternativeNames(paramInfos: ParameterInfos): Seq[String] =
-        val (valid, invalid) =
-          paramInfos.annotations.collect{ case annot: Name => annot.name }.partition(nameIsValid)
-        if invalid.nonEmpty then
-          throw IllegalArgumentException(s"invalid names ${invalid.mkString(", ")} for parameter ${paramInfos.name}")
-        valid
+        getAliases(paramInfos).filter(nameIsValid(_))
 
       private def getShortNames(paramInfos: ParameterInfos): Seq[Char] =
-        val (valid, invalid) =
-          paramInfos.annotations.collect{ case annot: ShortName => annot.shortName }.partition(shortNameIsValid)
-        if invalid.nonEmpty then
-          throw IllegalArgumentException(s"invalid short names ${invalid.mkString(", ")} for parameter ${paramInfos.name}")
-        valid
+        getAliases(paramInfos).filter(shortNameIsValid(_)).map(_(0))
+
+      private def getInvalidNames(paramInfos: ParameterInfos): Seq[String | Char] =
+        getAliases(paramInfos).filter(name => !nameIsValid(name) && !shortNameIsValid(name))
+
+      private def checkAliasesValidity(): Unit =
+        val problematicNames = nameToParameterInfos.toList.flatMap((_, infos) => getInvalidNames(infos))
+        if problematicNames.length > 0 then throw IllegalArgumentException(s"The following aliases are invalid: ${problematicNames.mkString(", ")}")
 
-      private def checkNamesUnicity(): Unit =
+      private def checkAliasesUnicity(): Unit =
         val nameAndCanonicalName = nameToParameterInfos.toList.flatMap {
           case (canonicalName, infos) => (canonicalName +: getAlternativeNames(infos) ++: getShortNames(infos)).map(_ -> canonicalName)
         }
         val nameToCanonicalNames = nameAndCanonicalName.groupMap(_._1)(_._2)
 
         for (name, canonicalNames) <- nameToCanonicalNames if canonicalNames.length > 1
-        do throw AssertionError(s"$name is used for multiple parameters: ${canonicalNames.mkString(", ")}")
+        do throw IllegalArgumentException(s"$name is used for multiple parameters: ${canonicalNames.mkString(", ")}")
 
       override def argGetter[T](name: String, optDefaultGetter: Option[() => T])(using p: ArgumentParser[T]): () => T =
         argKinds += (if optDefaultGetter.nonEmpty then ArgumentKind.OptionalArgument else ArgumentKind.SimpleArgument)
@@ -327,9 +347,10 @@ final class main(maxLineLength: Int) extends MainAnnotation:
         () => (byNameGetters ++ positionalGetters).map(_())
 
       override def run(f: => MainResultType): Unit =
+        checkAliasesUnicity()
+        checkAliasesValidity()
         for (remainingArg <- positionalArgs) error(s"unused argument: $remainingArg")
         for (invalidArg <- invalidByNameArgs) error(s"unknown argument name: $invalidArg")
-        checkNamesUnicity()
 
         if args.contains(s"${argMarker}help") then
           usage()
@@ -345,6 +366,5 @@ final class main(maxLineLength: Int) extends MainAnnotation:
 end main
 
 object main:
-  final class ShortName(val shortName: Char) extends MainAnnotation.ParameterAnnotation
-  final class Name(val name: String) extends MainAnnotation.ParameterAnnotation
+  final class Alias(val aliases: String*) extends MainAnnotation.ParameterAnnotation
 end main

project/MiMaFilters.scala

@@ -9,10 +9,7 @@ object MiMaFilters {
     ProblemFilters.exclude[DirectMissingMethodProblem]("scala.main.this"),
     ProblemFilters.exclude[DirectMissingMethodProblem]("scala.main.command"),
     ProblemFilters.exclude[MissingClassProblem]("scala.main$"),
-    ProblemFilters.exclude[MissingClassProblem]("scala.main$Name"),
-    ProblemFilters.exclude[MissingClassProblem]("scala.main$Name$"),
-    ProblemFilters.exclude[MissingClassProblem]("scala.main$ShortName"),
-    ProblemFilters.exclude[MissingClassProblem]("scala.main$ShortName$"),
+    ProblemFilters.exclude[MissingClassProblem]("scala.main$Alias"),
     ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation"),
     ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation$"),
     ProblemFilters.exclude[MissingClassProblem]("scala.annotation.MainAnnotation$Command"),

tests/run/main-annotation-help.check

@@ -150,9 +150,9 @@ Arguments:
     my first element
   --second - MyGeneric[Int]
     my second element
-Usage: doc17 [--a] <Int> [--b] <Int> [--c] <String>
+Usage: doc17 [-a] <Int> [-b] <Int> [-c] <String>
 
 Arguments:
-  --a - Int
-  --b - Int
-  --c - String
+  -a - Int
+  -b - Int
+  -c - String

tests/run/main-annotation-max-line-length.check

@@ -1,40 +1,40 @@
-Usage: doc1 [--a] <Int> [--b] <Int> [--c] <String>
+Usage: doc1 [-a] <Int> [-b] <Int> [-c] <String>
 
 Help is printed normally.
 Arguments:
-  --a - Int
+  -a - Int
     the first argument
-  --b - Int
+  -b - Int
     the second argument
-  --c - String
+  -c - String
     the third argument. This one is a String
-Usage: doc2 [--a] <Int> [--b] <Int>
-            [--c] <String>
+Usage: doc2 [-a] <Int> [-b] <Int>
+            [-c] <String>
 
 Help is printed in a slightly narrow
 column.
 Arguments:
-  --a - Int
+  -a - Int
     the first argument
-  --b - Int
+  -b - Int
     the second argument
-  --c - String
+  -c - String
     the third argument. This one is a
     String
-Usage: doc3 [--a] <Int>
-            [--b] <Int>
-            [--c] <String>
+Usage: doc3 [-a] <Int>
+            [-b] <Int>
+            [-c] <String>
 
 Help is printed in a
 very narrow column!
 Arguments:
-  --a - Int
+  -a - Int
     the first
     argument
-  --b - Int
+  -b - Int
     the second
     argument
-  --c - String
+  -c - String
     the third
     argument. This
     one is a String

tests/run/main-annotation-param-annot-1.check

@@ -26,3 +26,11 @@
 2 + 3 = 5
 2 + 3 = 5
 2 + 3 = 5
+2 + 3 = 5
+2 + 3 = 5
+2 + 3 = 5
+2 + 3 = 5
+2 + 3 = 5
+2 + 3 = 5
+2 + 3 = 5
+2 + 3 = 5

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

@@ -1,31 +1,31 @@
 object myProgram:
   @main def altName1(
-    @main.Name("myNum") num: Int,
+    @main.Alias("myNum") num: Int,
     inc: Int
   ): Unit =
     println(s"$num + $inc = ${num + inc}")
 
   @main def altName2(
-    @main.Name("myNum") num: Int,
-    @main.Name("myInc") inc: Int
+    @main.Alias("myNum") num: Int,
+    @main.Alias("myInc") inc: Int
   ): Unit =
     println(s"$num + $inc = ${num + inc}")
 
   @main def shortName1(
-    @main.ShortName('n') num: Int,
+    @main.Alias("n") num: Int,
     inc: Int
   ): Unit =
     println(s"$num + $inc = ${num + inc}")
 
   @main def shortName2(
-    @main.ShortName('n') num: Int,
-    @main.ShortName('i') inc: Int
+    @main.Alias("n") num: Int,
+    @main.Alias("i") inc: Int
   ): Unit =
     println(s"$num + $inc = ${num + inc}")
 
   @main def mix1(
-    @main.Name("myNum") @main.ShortName('n') num: Int,
-    @main.ShortName('i') @main.Name("myInc") inc: Int
+    @main.Alias("myNum") @main.Alias("n") num: Int,
+    @main.Alias("i") @main.Alias("myInc") inc: Int
   ): Unit =
     println(s"$num + $inc = ${num + inc}")
 
@@ -35,14 +35,20 @@ object myProgram:
     for i <- 0 until 'n' - 'a'
     do
       short = (short.toInt + 1).toChar
-    short
+    short.toString
   }
   def myInc = {new Exception("myInc")}.getMessage
-  def myShortInc = () => 'i'
+  def myShortInc = () => "i"
 
   @main def mix2(
-    @main.Name(myNum) @main.ShortName(myShortNum) num: Int,
-    @main.ShortName(myShortInc()) @main.Name(myInc) inc: Int
+    @main.Alias(myNum) @main.Alias(myShortNum) num: Int,
+    @main.Alias(myShortInc()) @main.Alias(myInc) inc: Int
+  ): Unit =
+    println(s"$num + $inc = ${num + inc}")
+
+  @main def multiple(
+    @main.Alias("myNum", "n") num: Int,
+    @main.Alias("i", "myInc") inc: Int
   ): Unit =
     println(s"$num + $inc = ${num + inc}")
 end myProgram
@@ -87,4 +93,13 @@ object Test:
     callMain("mix2", Array("-n", "2", "--myInc", "3"))
     callMain("mix2", Array("--myNum", "2", "-i", "3"))
     callMain("mix2", Array("-n", "2", "-i", "3"))
+
+    callMain("multiple", Array("--num", "2", "--inc", "3"))
+    callMain("multiple", Array("-n", "2", "--inc", "3"))
+    callMain("multiple", Array("--num", "2", "-i", "3"))
+    callMain("multiple", Array("-n", "2", "-i", "3"))
+    callMain("multiple", Array("--myNum", "2", "--myInc", "3"))
+    callMain("multiple", Array("-n", "2", "--myInc", "3"))
+    callMain("multiple", Array("--myNum", "2", "-i", "3"))
+    callMain("multiple", Array("-n", "2", "-i", "3"))
 end Test