Better compiler entry points

- Document the entry points
- It is now possible to set a custom reporter without using a custom
  context
- Use `null` for optional arguments to make it easier to run the
  compiler using reflection or from Java.
- DPDirectCompiler does not use a custom context anymore

Author: smarter

src/dotty/tools/dotc/Driver.scala

@@ -40,19 +40,57 @@ abstract class Driver extends DotClass {
     (fileNames, ctx)
   }
 
-  def process(args: Array[String], rootCtx: Context): Reporter = {
-    val (fileNames, ctx) = setup(args, rootCtx)
-    doCompile(newCompiler(), fileNames)(ctx)
-  }
 
-  def process(args: Array[String], callback: CompilerCallback): Reporter = {
-    process(args, initCtx.setCompilerCallback(callback))
+  /** Principal entry point to the compiler.
+   *  Creates a new compiler instance and run it with arguments `args`.
+   *
+   *  The optional arguments of this method all have `null` as their default
+   *  value, this makes it easier to call this method by reflection or from Java.
+   *
+   *  @param args       Arguments to pass to the compiler.
+   *  @param reporter   Used to log errors, warnings, and info messages.
+   *                    The default reporter is used if this is `null`.
+   *  @param callback   Used to execute custom code during the compilation
+   *                    process. No callbacks will be executed if this is `null`.
+   *  @return           The `Reporter` used. Use `Reporter#hasErrors` to check
+   *                    if compilation succeeded.
+   */
+  final def process(args: Array[String], reporter: Reporter = null,
+    callback: CompilerCallback = null): Reporter = {
+    val ctx = initCtx.fresh
+    if (reporter != null)
+      ctx.setReporter(reporter)
+    if (callback != null)
+      ctx.setCompilerCallback(callback)
+    process(args, ctx)
   }
 
-  // We overload `process` instead of using a default argument so that we
-  // can easily call this method using reflection from `RawCompiler` in sbt.
-  def process(args: Array[String]): Reporter = {
-    process(args, initCtx)
+  /** Entry point to the compiler with no optional arguments.
+   *
+   *  This overload is provided for compatibility reasons: the
+   *  `RawCompiler` of sbt expects this method to exist and calls
+   *  it using reflection. Keeping it means that we can change
+   *  the other overloads without worrying about breaking compatibility
+   *  with sbt.
+   */
+  final def process(args: Array[String]): Reporter =
+    process(args, null, null)
+
+  /** Entry point to the compiler using a custom `Context`.
+   *
+   *  In most cases, you do not need a custom `Context` and should
+   *  instead use one of the other overloads of `process`. However,
+   *  the other overloads cannot be overriden, instead you
+   *  should override this one which they call internally.
+   *
+   *  @param args       Arguments to pass to the compiler.
+   *  @param rootCtx    The root Context to use.
+   *  @return           The `Reporter` used. Use `Reporter#hasErrors` to check
+   *                    if compilation succeeded.
+   */
+  def process(args: Array[String], rootCtx: Context): Reporter = {
+    val (fileNames, ctx) = setup(args, rootCtx)
+    doCompile(newCompiler(), fileNames)(ctx)
   }
 
   def main(args: Array[String]): Unit = {

src/dotty/tools/dotc/core/Contexts.scala

@@ -427,6 +427,7 @@ object Contexts {
     def setPeriod(period: Period): this.type = { this.period = period; this }
     def setMode(mode: Mode): this.type = { this.mode = mode; this }
     def setTyperState(typerState: TyperState): this.type = { this.typerState = typerState; this }
+    def setReporter(reporter: Reporter): this.type = setTyperState(typerState.withReporter(reporter))
     def setNewTyperState: this.type = setTyperState(typerState.fresh(isCommittable = true))
     def setExploreTyperState: this.type = setTyperState(typerState.fresh(isCommittable = false))
     def setPrinterFn(printer: Context => Printer): this.type = { this.printerFn = printer; this }

test/dotty/partest/DPDirectCompiler.scala

@@ -13,20 +13,14 @@ class DPDirectCompiler(runner: DPTestRunner) extends nest.DirectCompiler(runner)
     val clogWriter = new PrintWriter(clogFWriter, true)
     clogWriter.println("\ncompiling " + sources.mkString(" ") + "\noptions: " + opts0.mkString(" "))
 
-    implicit val ctx: dotty.tools.dotc.core.Contexts.Context = {
-      val base = new dotty.tools.dotc.core.Contexts.ContextBase
-      base.initialCtx.fresh
-    }
-
     try {
       val processor =
         if (opts0.exists(_.startsWith("#"))) dotty.tools.dotc.Bench else dotty.tools.dotc.Main
       val clogger = new ConsoleReporter(writer = clogWriter)
-      val logCtx = ctx.fresh.setTyperState(ctx.typerState.withReporter(clogger))
-      val reporter = processor.process((sources.map(_.toString) ::: opts0).toArray, logCtx)
+      val reporter = processor.process((sources.map(_.toString) ::: opts0).toArray, clogger)
       if (!reporter.hasErrors) runner.genPass()
       else {
-        reporter.printSummary(ctx)
+        clogWriter.println(reporter.summary)
         runner.genFail(s"compilation failed with ${reporter.errorCount} errors")
       }
     } catch {