Add mainargs.Parser as a shorthand alias for ParserForMethods and ParserForClass (#201)

lihaoyi · web-flow · commit bf29601392f0 · 2025-10-23T12:35:40.000+08:00
The two factory objects have distinct APIs, so we can combine them onto
one `Parser` factory object that just always does the right thing. For
binary compatibility reasons, all the older APIs and class layout are
left unchanged
diff --git a/build.mill b/build.mill
@@ -1,4 +1,5 @@
-//| mill-version: 1.0.0
+//| mill-version: 1.0.6
+//| mill-jvm-version: 11
 //| mvnDeps:
 //| - com.github.lolgab::mill-mima_mill1:0.2.0
 
@@ -30,7 +31,7 @@ trait MainArgsPublishModule
 
   def publishVersion = VcsVersion.vcsState().format()
 
-  override def mimaPreviousVersions = Seq("0.6.0")
+  override def mimaPreviousVersions = Seq("0.7.0", "0.7.1", "0.7.2", "0.7.3", "0.7.4", "0.7.5", "0.7.6")
 
   def mimaReportBinaryIssues() =
     if (this.isInstanceOf[ScalaNativeModule] || this.isInstanceOf[ScalaJSModule]) Task.Command{}
diff --git a/example/caseclass/src/Main.scala b/example/caseclass/src/Main.scala
@@ -12,7 +12,7 @@ object Main {
       bool: Flag = Flag()
   )
   def main(args: Array[String]): Unit = {
-    val config = ParserForClass[Config].constructOrExit(args)
+    val config = Parser[Config].constructOrExit(args)
     println(config)
   }
 }
diff --git a/example/classarg/src/Main.scala b/example/classarg/src/Main.scala
@@ -1,5 +1,5 @@
 package example.classarg
-import mainargs.{main, arg, ParserForMethods, ParserForClass, Flag}
+import mainargs.{main, arg, Parser, ParserForClass, Flag}
 
 object Main {
   @main
@@ -11,7 +11,7 @@ object Main {
       @arg(doc = "Example flag")
       bool: Flag = Flag()
   )
-  implicit def configParser = ParserForClass[Config]
+  implicit def configParser = Parser[Config]
 
   @main
   def bar(
@@ -26,5 +26,5 @@ object Main {
     println((config.foo * config.myNum + " " + config.bool.value + "\n") * n)
   }
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/example/custom/src/Main.scala b/example/custom/src/Main.scala
@@ -1,5 +1,5 @@
 package example.custom
-import mainargs.{main, arg, ParserForMethods, TokensReader}
+import mainargs.{main, arg, Parser, TokensReader}
 
 object Main {
   implicit object PathRead extends TokensReader[os.Path](
@@ -12,5 +12,5 @@ object Main {
     println("to:   " + to)
   }
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/example/hello/src/Main.scala b/example/hello/src/Main.scala
@@ -1,5 +1,5 @@
 package example.hello
-import mainargs.{main, arg, ParserForMethods, Flag}
+import mainargs.{main, arg, Parser, Flag}
 
 object Main {
   @main
@@ -14,5 +14,5 @@ object Main {
     println(foo * myNum + " " + bool.value)
   }
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/example/hello2/src/Main.scala b/example/hello2/src/Main.scala
@@ -1,5 +1,5 @@
 package example.hello2
-import mainargs.{main, arg, ParserForMethods, Flag}
+import mainargs.{main, arg, Parser, Flag}
 
 object Main {
   @main
@@ -21,5 +21,5 @@ object Main {
   ) = {
     println(s * i)
   }
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/example/optseq/src/Main.scala b/example/optseq/src/Main.scala
@@ -1,5 +1,5 @@
 package example.optseq
-import mainargs.{main, arg, ParserForMethods, TokensReader}
+import mainargs.{main, arg, Parser, TokensReader}
 
 object Main {
   @main
@@ -11,5 +11,5 @@ object Main {
   @main
   def runVec(seq: Vector[Int]) = println(seq)
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/example/short/src/Main.scala b/example/short/src/Main.scala
@@ -1,5 +1,5 @@
 package example.hello
-import mainargs.{main, arg, ParserForMethods, Flag}
+import mainargs.{main, arg, Parser, Flag}
 
 object Main {
   @main
@@ -8,5 +8,5 @@ object Main {
   @main
   def strs(a: Flag, b: String) = println(Seq(a.value, b))
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/example/vararg/src/Main.scala b/example/vararg/src/Main.scala
@@ -1,11 +1,11 @@
 package example.vararg
-import mainargs.{main, arg, ParserForMethods, Leftover}
+import mainargs.{main, arg, Parser, Leftover}
 
 object Main {
   @main
   def run(foo: String, myNum: Int = 2, rest: Leftover[String]) = {
     println(foo * myNum + " " + rest.value)
   }
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/example/vararg2/src/Main.scala b/example/vararg2/src/Main.scala
@@ -6,7 +6,7 @@ object Main {
   case class Config(foo: String, myNum: Int = 2, rest: Leftover[String])
 
   def main(args: Array[String]): Unit = {
-    val config = ParserForClass[Config].constructOrExit(args)
+    val config = Parser[Config].constructOrExit(args)
     println(config)
   }
 }
diff --git a/example/varargold/src/Main.scala b/example/varargold/src/Main.scala
@@ -1,11 +1,11 @@
 package example.vararg
-import mainargs.{main, arg, ParserForMethods, Leftover}
+import mainargs.{main, arg, Parser, Leftover}
 
 object Main {
   @main
   def run(foo: String, myNum: Int, rest: String*) = {
     println(foo * myNum + " " + rest.value)
   }
 
-  def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)
+  def main(args: Array[String]): Unit = Parser(this).runOrExit(args)
 }
diff --git a/mainargs/src/Parser.scala b/mainargs/src/Parser.scala
@@ -5,6 +5,7 @@ import acyclic.skipped
 import scala.language.experimental.macros
 import java.io.PrintStream
 
+object Parser extends ParserForMethodsCompanionVersionSpecific with ParserForClassCompanionVersionSpecific
 object ParserForMethods extends ParserForMethodsCompanionVersionSpecific
 class ParserForMethods[B](val mains: MethodMains[B]) {
   @deprecated("Binary Compatibility Shim", "mainargs 0.6.0")
diff --git a/mainargs/test/src-jvm-2/AmmoniteTests.scala b/mainargs/test/src-jvm-2/AmmoniteTests.scala
@@ -90,7 +90,7 @@ object AmmoniteConfig {
       @arg(doc = "Print this message")
       help: Flag
   )
-  implicit val coreParser = ParserForClass[Core]
+  implicit val coreParser = Parser[Core]
 
   @main
   case class Predef(
@@ -108,7 +108,7 @@ object AmmoniteConfig {
       )
       noHomePredef: Flag
   )
-  implicit val predefParser = ParserForClass[Predef]
+  implicit val predefParser = Parser[Predef]
 
   @main
   case class Repl(
@@ -130,11 +130,11 @@ object AmmoniteConfig {
       )
       classBased: Flag
   )
-  implicit val replParser = ParserForClass[Repl]
+  implicit val replParser = Parser[Repl]
 }
 
 object AmmoniteTests extends TestSuite {
-  val parser = ParserForClass[AmmoniteConfig]
+  val parser = Parser[AmmoniteConfig]
   val tests = Tests {
 
     test("formatMainMethods.unsorted") {
diff --git a/mainargs/test/src-jvm-2/MillTests.scala b/mainargs/test/src-jvm-2/MillTests.scala
@@ -88,7 +88,7 @@ object MillTests extends TestSuite {
 
   val tests = Tests {
 
-    val parser = ParserForClass[Config]
+    val parser = Parser[Config]
 
     test("formatMainMethods") {
       val rendered = parser.helpText(sorted = false)
diff --git a/mainargs/test/src/ClassTests.scala b/mainargs/test/src/ClassTests.scala
@@ -43,11 +43,11 @@ object ClassTests extends TestSuite {
     ) = new Compat(home, silent, leftoverArgs)
   }
 
-  implicit val fooParser: ParserForClass[Foo] = ParserForClass[Foo]
-  implicit val barParser: ParserForClass[Bar] = ParserForClass[Bar]
-  implicit val quxParser: ParserForClass[Qux] = ParserForClass[Qux]
-  implicit val cliParser: ParserForClass[Cli] = ParserForClass[Cli]
-  implicit val compatParser: ParserForClass[Compat] = ParserForClass[Compat]
+  implicit val fooParser: ParserForClass[Foo] = Parser[Foo]
+  implicit val barParser: ParserForClass[Bar] = Parser[Bar]
+  implicit val quxParser: ParserForClass[Qux] = Parser[Qux]
+  implicit val cliParser: ParserForClass[Cli] = Parser[Cli]
+  implicit val compatParser: ParserForClass[Compat] = Parser[Compat]
 
   class PathWrap {
     @main
@@ -60,7 +60,7 @@ object ClassTests extends TestSuite {
       }
     }
 
-    implicit val fooParser: ParserForClass[Foo] = ParserForClass[Foo]
+    implicit val fooParser: ParserForClass[Foo] = Parser[Foo]
   }
 
   object Main {
@@ -204,7 +204,7 @@ object ClassTests extends TestSuite {
         Qux("cow", Bar(Flag(true), Foo(1, 2), "xxx"))
     }
     test("success") {
-      ParserForMethods(Main).runOrThrow(
+      Parser(Main).runOrThrow(
         Seq("-x", "1", "-y", "2", "-z", "hello")
       ) ==> "false 1 2 hello false"
     }
@@ -225,7 +225,7 @@ object ClassTests extends TestSuite {
       }
       test("path-dependent-default-method") {
         val p = new PathWrap
-        ParserForMethods(p.Main).runOrThrow(
+        Parser(p.Main).runOrThrow(
           Seq("-x", "1", "-y", "2", "-z", "hello")
         ) ==> "false 1 2 hello false"
       }
diff --git a/mainargs/test/src/ClassWithDefaultTests.scala b/mainargs/test/src/ClassWithDefaultTests.scala
@@ -6,14 +6,14 @@ object ClassWithDefaultTests extends TestSuite {
   @main
   case class Foo(x: Int, y: Int = 1)
 
-  implicit val fooParser: ParserForClass[Foo] = ParserForClass[Foo]
+  implicit val fooParser: ParserForClass[Foo] = Parser[Foo]
 
   object Main {
     @main
     def run(foo: Foo, bool: Boolean = false) = s"${foo.x} ${foo.y} $bool"
   }
 
-  val mainParser = ParserForMethods(Main)
+  val mainParser = Parser(Main)
 
   val tests = Tests {
     test("simple") {
diff --git a/mainargs/test/src/ConstantTests.scala b/mainargs/test/src/ConstantTests.scala
@@ -12,7 +12,7 @@ object ConstantTests extends TestSuite {
     @main
     def flaggy(a: Injected, b: Boolean) = a.toString + " " + b
   }
-  val check = new Checker(ParserForMethods(Base), allowPositional = true)
+  val check = new Checker(Parser(Base), allowPositional = true)
 
   val tests = Tests {
     test - check(
diff --git a/mainargs/test/src/CoreTests.scala b/mainargs/test/src/CoreTests.scala
@@ -258,7 +258,7 @@ object CorePositionalDisabledOnlyTests extends TestSuite {
 }
 
 object CorePositionalEnabledOnlyTests extends TestSuite {
-  val check = new Checker(ParserForMethods(CoreBase), allowPositional = true)
+  val check = new Checker(Parser(CoreBase), allowPositional = true)
 
   val tests = Tests {
     test("invoke") {
diff --git a/mainargs/test/src/DashedArgumentName.scala b/mainargs/test/src/DashedArgumentName.scala
@@ -16,8 +16,8 @@ object DashedArgumentName extends TestSuite {
     @main(name = "camelOptFor29NameForce")
     def camelOptFor29NameForce(@arg(name = "camelOptFor29ArgForce") camelOptFor29ArgForce: Boolean) = camelOptFor29ArgForce
   }
-  val check = new Checker(ParserForMethods(Base), allowPositional = true)
-  val snakeCaseCheck = new Checker(ParserForMethods(Base), allowPositional = true, nameMapper = Util.snakeCaseNameMapper)
+  val check = new Checker(Parser(Base), allowPositional = true)
+  val snakeCaseCheck = new Checker(Parser(Base), allowPositional = true, nameMapper = Util.snakeCaseNameMapper)
 
   val tests = Tests {
     test("backticked") {
diff --git a/mainargs/test/src/EqualsSyntaxTests.scala b/mainargs/test/src/EqualsSyntaxTests.scala
@@ -19,27 +19,27 @@ object EqualsSyntaxTests extends TestSuite {
 
   val tests = Tests {
     test("simple") {
-      ParserForMethods(Main).runOrThrow(Array("--foo=bar", "--my-num=3")) ==>
+      Parser(Main).runOrThrow(Array("--foo=bar", "--my-num=3")) ==>
         "barbarbar false"
     }
     test("multipleEquals") {
       // --foo=bar syntax still works when there's an `=` on the right
-      ParserForMethods(Main).runOrThrow(Array("--foo=bar=qux")) ==>
+      Parser(Main).runOrThrow(Array("--foo=bar=qux")) ==>
         "bar=quxbar=qux false"
     }
     test("empty") {
       // --foo= syntax sets `foo` to an empty string
-      ParserForMethods(Main).runOrThrow(Array("--foo=")) ==>
+      Parser(Main).runOrThrow(Array("--foo=")) ==>
         " false"
     }
     test("shortName") {
       // -f=bar syntax does work for short names
-      ParserForMethods(Main).runEither(Array("-f=bar")) ==>
+      Parser(Main).runEither(Array("-f=bar")) ==>
         Right("barbar false")
     }
     test("notFlags") {
       // -f=bar syntax doesn't work for flags
-      ParserForMethods(Main).runEither(Array("--foo=bar", "--bool=true")) ==>
+      Parser(Main).runEither(Array("--foo=bar", "--bool=true")) ==>
          Left("""Unknown argument: "--bool=true"
                 |Expected Signature: run
                 |  --bool          Example flag
diff --git a/mainargs/test/src/FlagTests.scala b/mainargs/test/src/FlagTests.scala
@@ -10,7 +10,7 @@ object FlagTests extends TestSuite {
     def str(a: Flag, b: String) = Seq(a.value, b)
   }
 
-  val check = new Checker(ParserForMethods(Base), allowPositional = true)
+  val check = new Checker(Parser(Base), allowPositional = true)
 
   val tests = Tests {
     test - check(
diff --git a/mainargs/test/src/HelloWorldTests.scala b/mainargs/test/src/HelloWorldTests.scala
@@ -19,27 +19,27 @@ object HelloWorldTests extends TestSuite {
 
   val tests = Tests {
     test("explicit") {
-      ParserForMethods(Main).runOrThrow(Array("--foo", "bar", "--my-num", "3")) ==>
+      Parser(Main).runOrThrow(Array("--foo", "bar", "--my-num", "3")) ==>
         "barbarbar false"
     }
     test("short") {
-      ParserForMethods(Main).runOrThrow(Array("-f", "bar")) ==>
+      Parser(Main).runOrThrow(Array("-f", "bar")) ==>
         "barbar false"
     }
     test("default") {
-      ParserForMethods(Main).runOrThrow(Array("--foo", "bar")) ==>
+      Parser(Main).runOrThrow(Array("--foo", "bar")) ==>
         "barbar false"
     }
     test("positional") {
-      ParserForMethods(Main).runOrThrow(Array("qux", "4"), allowPositional = true) ==>
+      Parser(Main).runOrThrow(Array("qux", "4"), allowPositional = true) ==>
         "quxquxquxqux false"
     }
     test("flags") {
-      ParserForMethods(Main).runOrThrow(Array("qux", "4", "--bool"), allowPositional = true) ==>
+      Parser(Main).runOrThrow(Array("qux", "4", "--bool"), allowPositional = true) ==>
         "quxquxquxqux true"
     }
     test("either") {
-      ParserForMethods(Main).runEither(Array("qux", "4", "--bool"), allowPositional = true) ==>
+      Parser(Main).runEither(Array("qux", "4", "--bool"), allowPositional = true) ==>
         Right("quxquxquxqux true")
     }
   }
diff --git a/mainargs/test/src/HygieneTests.scala b/mainargs/test/src/HygieneTests.scala
@@ -20,7 +20,7 @@ object HygieneTests extends TestSuite {
   val tests = Tests {
     import scala.collection.mutable._
     test("importingSeqShouldntFailCompile") {
-      ParserForMethods(Main)
+      Parser(Main)
     }
 
   }
diff --git a/mainargs/test/src/InvocationArgs.scala b/mainargs/test/src/InvocationArgs.scala
@@ -37,7 +37,7 @@ case class LargeArgs(
 )
 
 object LargeClassTests extends TestSuite{
-  val largeArgsParser = ParserForClass[LargeArgs]
+  val largeArgsParser = Parser[LargeArgs]
 
   val tests = Tests {
     test("simple") {
diff --git a/mainargs/test/src/IssueTests.scala b/mainargs/test/src/IssueTests.scala
diff --git a/mainargs/test/src/ManyTests.scala b/mainargs/test/src/ManyTests.scala
diff --git a/mainargs/test/src/MultiTraitTests.scala b/mainargs/test/src/MultiTraitTests.scala
diff --git a/mainargs/test/src/OptionSeqTests.scala b/mainargs/test/src/OptionSeqTests.scala
diff --git a/mainargs/test/src/ParserTests.scala b/mainargs/test/src/ParserTests.scala
diff --git a/mainargs/test/src/PositionalTests.scala b/mainargs/test/src/PositionalTests.scala
diff --git a/mainargs/test/src/VarargsCustomTests.scala b/mainargs/test/src/VarargsCustomTests.scala
diff --git a/mainargs/test/src/VarargsNewTests.scala b/mainargs/test/src/VarargsNewTests.scala
diff --git a/mainargs/test/src/VarargsOldTests.scala b/mainargs/test/src/VarargsOldTests.scala
diff --git a/mainargs/test/src/VarargsWrappedTests.scala b/mainargs/test/src/VarargsWrappedTests.scala
diff --git a/readme.md b/readme.md

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ object Main {`
`12`	`12`	`bool: Flag = Flag()`
`13`	`13`	`)`
`14`	`14`	`def main(args: Array[String]): Unit = {`
`15`		`- val config = ParserForClass[Config].constructOrExit(args)`
	`15`	`+ val config = Parser[Config].constructOrExit(args)`
`16`	`16`	`println(config)`
`17`	`17`	`}`
`18`	`18`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`package example.classarg`
`2`		`-import mainargs.{main, arg, ParserForMethods, ParserForClass, Flag}`
	`2`	`+import mainargs.{main, arg, Parser, ParserForClass, Flag}`
`3`	`3`
`4`	`4`	`object Main {`
`5`	`5`	`@main`
`@@ -11,7 +11,7 @@ object Main {`
`11`	`11`	`@arg(doc = "Example flag")`
`12`	`12`	`bool: Flag = Flag()`
`13`	`13`	`)`
`14`		`- implicit def configParser = ParserForClass[Config]`
	`14`	`+ implicit def configParser = Parser[Config]`
`15`	`15`
`16`	`16`	`@main`
`17`	`17`	`def bar(`
`@@ -26,5 +26,5 @@ object Main {`
`26`	`26`	`println((config.foo * config.myNum + " " + config.bool.value + "\n") * n)`
`27`	`27`	`}`
`28`	`28`
`29`		`- def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)`
	`29`	`+ def main(args: Array[String]): Unit = Parser(this).runOrExit(args)`
`30`	`30`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`package example.custom`
`2`		`-import mainargs.{main, arg, ParserForMethods, TokensReader}`
	`2`	`+import mainargs.{main, arg, Parser, TokensReader}`
`3`	`3`
`4`	`4`	`object Main {`
`5`	`5`	`implicit object PathRead extends TokensReader[os.Path](`
`@@ -12,5 +12,5 @@ object Main {`
`12`	`12`	`println("to: " + to)`
`13`	`13`	`}`
`14`	`14`
`15`		`- def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)`
	`15`	`+ def main(args: Array[String]): Unit = Parser(this).runOrExit(args)`
`16`	`16`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`package example.hello`
`2`		`-import mainargs.{main, arg, ParserForMethods, Flag}`
	`2`	`+import mainargs.{main, arg, Parser, Flag}`
`3`	`3`
`4`	`4`	`object Main {`
`5`	`5`	`@main`
`@@ -14,5 +14,5 @@ object Main {`
`14`	`14`	`println(foo * myNum + " " + bool.value)`
`15`	`15`	`}`
`16`	`16`
`17`		`- def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)`
	`17`	`+ def main(args: Array[String]): Unit = Parser(this).runOrExit(args)`
`18`	`18`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`package example.hello2`
`2`		`-import mainargs.{main, arg, ParserForMethods, Flag}`
	`2`	`+import mainargs.{main, arg, Parser, Flag}`
`3`	`3`
`4`	`4`	`object Main {`
`5`	`5`	`@main`
`@@ -21,5 +21,5 @@ object Main {`
`21`	`21`	`) = {`
`22`	`22`	`println(s * i)`
`23`	`23`	`}`
`24`		`- def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)`
	`24`	`+ def main(args: Array[String]): Unit = Parser(this).runOrExit(args)`
`25`	`25`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,11 @@`
`1`	`1`	`package example.vararg`
`2`		`-import mainargs.{main, arg, ParserForMethods, Leftover}`
	`2`	`+import mainargs.{main, arg, Parser, Leftover}`
`3`	`3`
`4`	`4`	`object Main {`
`5`	`5`	`@main`
`6`	`6`	`def run(foo: String, myNum: Int = 2, rest: Leftover[String]) = {`
`7`	`7`	`println(foo * myNum + " " + rest.value)`
`8`	`8`	`}`
`9`	`9`
`10`		`- def main(args: Array[String]): Unit = ParserForMethods(this).runOrExit(args)`
	`10`	`+ def main(args: Array[String]): Unit = Parser(this).runOrExit(args)`
`11`	`11`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ object Main {`
`6`	`6`	`case class Config(foo: String, myNum: Int = 2, rest: Leftover[String])`
`7`	`7`
`8`	`8`	`def main(args: Array[String]): Unit = {`
`9`		`- val config = ParserForClass[Config].constructOrExit(args)`
	`9`	`+ val config = Parser[Config].constructOrExit(args)`
`10`	`10`	`println(config)`
`11`	`11`	`}`
`12`	`12`	`}`