Add -h to display help

- --help and -h display usage and help
- if an argument or an alias is the same as either help or h, disable help printing for that argument

Author: timotheeandres

library/src/scala/main.scala

@@ -36,10 +36,13 @@ import annotation._
   * 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.
   *
-  * A special argument is used to display help regarding a main function: `--help`. If used as argument, the program
+  * 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`.
+  * `@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 `@main 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
@@ -69,6 +72,20 @@ final class main extends MainAnnotation:
       private val argMarker = "--"
       private val shortArgMarker = "-"
 
+      /**
+        * The name of the special argument to display the method's help.
+        * If one of the method's parameters is called the same, will be ignored.
+        */
+      private val helpArg = "help"
+      private var helpIsOverridden = false
+
+      /**
+        * The short name of the special argument to display the method's help.
+        * If one of the method's parameters uses the same short name, will be ignored.
+        */
+      private val shortHelpArg = 'h'
+      private var shortHelpIsOverridden = false
+
       private val maxUsageLineLength = 120
 
       /** A map from argument canonical name (the name of the parameter in the method definition) to parameter informations */
@@ -90,6 +107,9 @@ final class main extends MainAnnotation:
             names.map(_ -> canonicalName)
         ).toMap
 
+        helpIsOverridden = namesToCanonicalName.exists((name, _) => name == helpArg)
+        shortHelpIsOverridden = shortNamesToCanonicalName.exists((name, _) => name == shortHelpArg)
+
         def getCanonicalArgName(arg: String): Option[String] =
           if arg.startsWith(argMarker) && arg.length > argMarker.length then
             namesToCanonicalName.get(arg.drop(argMarker.length))
@@ -305,7 +325,10 @@ final class main extends MainAnnotation:
         for (remainingArg <- positionalArgs) error(s"unused argument: $remainingArg")
         for (invalidArg <- invalidByNameArgs) error(s"unknown argument name: $invalidArg")
 
-        if args.contains(s"${argMarker}help") then
+        val displayHelp =
+          (!helpIsOverridden && args.contains(getNameWithMarker(helpArg))) || (!shortHelpIsOverridden && args.contains(getNameWithMarker(shortHelpArg)))
+
+        if displayHelp then
           usage()
           println()
           explain()

tests/run/main-annotation-help-override.check

@@ -0,0 +1,56 @@
+##### --help
+Usage: helpOverride1 [--notHelp] <Int>
+
+A method that should let --help and -h display help.
+Arguments:
+  --notHelp - Int
+Error: invalid argument for help: --help
+Usage: helpOverride2 [--help] <Int>
+Usage: helpOverride3 [-h] <Int>
+
+A method that should let --help display help, but not -h.
+Arguments:
+  -h - Int
+Error: invalid argument for help: --help
+Error: missing argument for h
+Usage: helpOverride4 [--help] <Int> [-h] <Int>
+Error: invalid argument for notHelp: --help
+Usage: helpOverride5 [--notHelp | --help] <Int>
+Usage: helpOverride6 [--notHelp | -h] <Int>
+
+A method that should let --help display help, but not -h.
+Arguments:
+  --notHelp (-h) - Int
+Error: invalid argument for notHelp: --help
+Error: missing argument for notH
+Usage: helpOverride7 [--notHelp | --help] <Int> [--notH | -h] <Int>
+Error: invalid argument for notHelp: --help
+Usage: helpOverride8 [--notHelp | --help | -h] <Int>
+##### -h
+Usage: helpOverride1 [--notHelp] <Int>
+
+A method that should let --help and -h display help.
+Arguments:
+  --notHelp - Int
+Usage: helpOverride2 [--help] <Int>
+
+A method that should let -h display help, but not --help.
+Arguments:
+  --help - Int
+Error: invalid argument for h: -h
+Usage: helpOverride3 [-h] <Int>
+Error: invalid argument for help: -h
+Error: missing argument for h
+Usage: helpOverride4 [--help] <Int> [-h] <Int>
+Usage: helpOverride5 [--notHelp | --help] <Int>
+
+A method that should let -h display help, but not --help.
+Arguments:
+  --notHelp (--help) - Int
+Error: invalid argument for notHelp: -h
+Usage: helpOverride6 [--notHelp | -h] <Int>
+Error: invalid argument for notHelp: -h
+Error: missing argument for notH
+Usage: helpOverride7 [--notHelp | --help] <Int> [--notH | -h] <Int>
+Error: invalid argument for notHelp: -h
+Usage: helpOverride8 [--notHelp | --help | -h] <Int>

tests/run/main-annotation-help-override.scala

@@ -0,0 +1,47 @@
+import scala.util.Try
+
+object myProgram:
+
+  /** A method that should let --help and -h display help. */
+  @main def helpOverride1(notHelp: Int) = ???
+
+  /** A method that should let -h display help, but not --help. */
+  @main def helpOverride2(help: Int) = ???
+
+  /** A method that should let --help display help, but not -h. */
+  @main def helpOverride3(h: Int) = ???
+
+  /** A method that should not let --help and -h display help. */
+  @main def helpOverride4(help: Int, h: Int) = ???
+
+
+  /** A method that should let -h display help, but not --help. */
+  @main def helpOverride5(@main.Alias("help") notHelp: Int) = ???
+
+  /** A method that should let --help display help, but not -h. */
+  @main def helpOverride6(@main.Alias("h") notHelp: Int) = ???
+
+  /** A method that should not let --help and -h display help. */
+  @main def helpOverride7(@main.Alias("help") notHelp: Int, @main.Alias("h") notH: Int) = ???
+
+  /** A method that should not let --help and -h display help. */
+  @main def helpOverride8(@main.Alias("help", "h") notHelp: Int) = ???
+
+end myProgram
+
+object Test:
+  val allClazzes: Seq[Class[?]] =
+    LazyList.from(1).map(i => Try(Class.forName("helpOverride" + i.toString))).takeWhile(_.isSuccess).map(_.get)
+
+  def callAllMains(args: Array[String]): Unit =
+    for (clazz <- allClazzes) {
+      val method = clazz.getMethod("main", classOf[Array[String]])
+      method.invoke(null, args)
+    }
+
+  def main(args: Array[String]): Unit =
+    println("##### --help")
+    callAllMains(Array("--help"))
+    println("##### -h")
+    callAllMains(Array("-h"))
+end Test