Add public API for evaluating worksheets. (#208)

Add public API for evaluating worksheets.

build.sbt

@@ -53,6 +53,18 @@ lazy val fansiVersion = Def.setting {
   else "0.2.7"
 }
 
+lazy val interfaces = project
+  .in(file("mdoc-interfaces"))
+  .settings(
+    moduleName := "mdoc-interfaces",
+    autoScalaLibrary := false,
+    crossVersion := CrossVersion.disabled,
+    javacOptions in (Compile / doc) ++= List(
+      "-tag",
+      "implNote:a:Implementation Note:"
+    )
+  )
+
 lazy val runtime = project
   .settings(
     moduleName := "mdoc-runtime",
@@ -61,6 +73,7 @@ lazy val runtime = project
       "com.lihaoyi" %% "pprint" % pprintVersion.value
     )
   )
+  .dependsOn(interfaces)
 
 lazy val mdoc = project
   .settings(
@@ -189,6 +202,7 @@ lazy val plugin = project
     },
     publishLocal := publishLocal
       .dependsOn(
+        publishLocal in interfaces,
         publishLocal in runtime,
         publishLocal in mdoc,
         publishLocal in js

mdoc-interfaces/src/main/scala/mdoc/interfaces/Diagnostic.java

@@ -0,0 +1,9 @@
+package mdoc.interfaces;
+
+public abstract class Diagnostic {
+
+  public abstract RangePosition position();
+  public abstract String message();
+  public abstract DiagnosticSeverity severity();
+
+}

mdoc-interfaces/src/main/scala/mdoc/interfaces/DiagnosticSeverity.java

@@ -0,0 +1,3 @@
+package mdoc.interfaces;
+
+public enum DiagnosticSeverity { Info, Warning, Error}

mdoc-interfaces/src/main/scala/mdoc/interfaces/EvaluatedWorksheet.java

@@ -0,0 +1,10 @@
+package mdoc.interfaces;
+
+import java.util.List;
+
+public abstract class EvaluatedWorksheet {
+
+  public abstract List<Diagnostic> diagnostics();
+  public abstract List<EvaluatedWorksheetStatement> statements();
+
+}

mdoc-interfaces/src/main/scala/mdoc/interfaces/EvaluatedWorksheetStatement.java

@@ -0,0 +1,9 @@
+package mdoc.interfaces;
+
+public abstract class EvaluatedWorksheetStatement {
+
+  public abstract RangePosition position();
+  public abstract String summary();
+  public abstract String details();
+
+}

mdoc-interfaces/src/main/scala/mdoc/interfaces/Mdoc.java

@@ -0,0 +1,18 @@
+package mdoc.interfaces;
+
+import java.util.List;
+import java.nio.file.Path;
+import java.io.PrintStream;
+
+public abstract class Mdoc {
+
+  public abstract EvaluatedWorksheet evaluateWorksheet(String filename, String text);
+  public abstract Mdoc withClasspath(List<Path> classpath);
+  public abstract Mdoc withScalacOptions(List<String> options);
+  public abstract Mdoc withSettings(List<String> settings);
+  public abstract Mdoc withConsoleReporter(PrintStream out);
+  public abstract Mdoc withScreenHeight(int screenHeight);
+  public abstract Mdoc withScreenWidth(int screenWidth);
+  public abstract void shutdown();
+
+}

mdoc-interfaces/src/main/scala/mdoc/interfaces/RangePosition.java

@@ -0,0 +1,8 @@
+package mdoc.interfaces;
+
+public abstract class RangePosition {
+  public abstract int startLine();
+  public abstract int startColumn();
+  public abstract int endLine();
+  public abstract int endColumn();
+}

mdoc/src/main/resources/META-INF/services/mdoc.interfaces.Mdoc

@@ -0,0 +1 @@
+mdoc.internal.worksheets.Mdoc

mdoc/src/main/scala-2.11/mdoc/internal/worksheets/Compat.scala

@@ -0,0 +1,10 @@
+package mdoc.internal.worksheets
+
+import scala.tools.nsc.Global
+
+object Compat {
+  def usedDummy() = () // Only here to avoid "unused import" warning.
+  implicit class XtensionCompiler(compiler: Global) {
+    def close(): Unit = () // do nothing, not available
+  }
+}

mdoc/src/main/scala-2.12/mdoc/internal/worksheets/Compat.scala

@@ -0,0 +1,5 @@
+package mdoc.internal.worksheets
+
+object Compat {
+  def usedDummy() = () // Only here to avoid "unused import" warning.
+}

mdoc/src/main/scala-2.13/mdoc/internal/worksheets/Compat.scala

@@ -0,0 +1,5 @@
+package mdoc.internal.worksheets
+
+object Compat {
+  def usedDummy() = () // Only here to avoid "unused import" warning.
+}

mdoc/src/main/scala/mdoc/MainSettings.scala

@@ -92,6 +92,12 @@ final class MainSettings private (
   def withVariablePrinter(variablePrinter: Variable => String): MainSettings = {
     copy(settings.copy(variablePrinter = variablePrinter))
   }
+  def withScreenWidth(screenWidth: Int): MainSettings = {
+    copy(settings.copy(screenWidth = screenWidth))
+  }
+  def withScreenHeight(screenHeight: Int): MainSettings = {
+    copy(settings.copy(screenHeight = screenHeight))
+  }
 
   private[this] implicit def cwd: AbsolutePath = settings.cwd
   private[this] def copy(

mdoc/src/main/scala/mdoc/internal/cli/Settings.scala

@@ -130,6 +130,12 @@ case class Settings(
     @Description("The input stream to listen for enter key during file watching.")
     inputStream: InputStream = System.in,
     @Hidden()
+    @Description("The width of the screen, used to line wrap pretty-printed objects.")
+    screenWidth: Int = 120,
+    @Hidden()
+    @Description("The height of the screen, used to truncate large pretty-printed objects.")
+    screenHeight: Int = 50,
+    @Hidden()
     @Description("The generator for header IDs, defaults to GitHub ID generator")
     headerIdGenerator: String => String = GitHubIdGenerator,
     @Hidden()

mdoc/src/main/scala/mdoc/internal/io/Diagnostic.scala

@@ -0,0 +1,10 @@
+package mdoc.internal.io
+
+import mdoc.interfaces.DiagnosticSeverity
+import mdoc.interfaces.RangePosition
+
+case class Diagnostic(
+    val position: RangePosition,
+    val message: String,
+    val severity: DiagnosticSeverity
+) extends mdoc.interfaces.Diagnostic

mdoc/src/main/scala/mdoc/internal/io/StoreReporter.scala

@@ -0,0 +1,49 @@
+package mdoc.internal.io
+
+import scala.meta._
+import scala.collection.mutable
+import java.io.ByteArrayOutputStream
+import java.io.PrintStream
+import mdoc.interfaces.DiagnosticSeverity
+import mdoc.document.RangePosition
+import mdoc.internal.pos.PositionSyntax._
+
+class StoreReporter() extends ConsoleReporter(System.out) {
+  val diagnostics: mutable.LinkedHashSet[Diagnostic] =
+    mutable.LinkedHashSet.empty[Diagnostic]
+
+  override def reset(): Unit = diagnostics.clear()
+
+  override def warningCount: Int =
+    diagnostics.count(_.severity == DiagnosticSeverity.Warning)
+  override def errorCount: Int =
+    diagnostics.count(_.severity == DiagnosticSeverity.Error)
+  override def hasErrors: Boolean = errorCount > 0
+  override def hasWarnings: Boolean = warningCount > 0
+
+  override def warning(pos: Position, msg: String): Unit = {
+    diagnostics += new Diagnostic(
+      pos.toMdoc,
+      msg,
+      DiagnosticSeverity.Warning
+    )
+    super.warning(pos, msg)
+  }
+  override def error(pos: Position, throwable: Throwable): Unit = {
+    val out = new ByteArrayOutputStream()
+    throwable.printStackTrace(new PrintStream(out))
+    diagnostics += new Diagnostic(
+      pos.toMdoc,
+      out.toString(),
+      DiagnosticSeverity.Error
+    )
+  }
+  override def error(pos: Position, msg: String): Unit = {
+    diagnostics += new Diagnostic(
+      pos.toMdoc,
+      msg,
+      DiagnosticSeverity.Error
+    )
+    super.error(pos, msg)
+  }
+}

mdoc/src/main/scala/mdoc/internal/pos/PositionSyntax.scala

@@ -87,6 +87,13 @@ object PositionSyntax {
       case _ =>
         pos
     }
+    def toMdoc: RangePosition =
+      new RangePosition(
+        pos.startLine,
+        pos.startColumn,
+        pos.endLine,
+        pos.endColumn
+      )
     def contains(offset: Int): Boolean = {
       if (pos.start == pos.end) pos.end == offset
       else {

mdoc/src/main/scala/mdoc/internal/worksheets/EvaluatedWorksheet.scala

@@ -0,0 +1,9 @@
+package mdoc.internal.worksheets
+
+import java.{util => ju}
+import mdoc.{interfaces => i}
+
+case class EvaluatedWorksheet(
+    val diagnostics: ju.List[i.Diagnostic],
+    val statements: ju.List[i.EvaluatedWorksheetStatement]
+) extends mdoc.interfaces.EvaluatedWorksheet

mdoc/src/main/scala/mdoc/internal/worksheets/EvaluatedWorksheetStatement.scala

@@ -0,0 +1,8 @@
+package mdoc.internal.worksheets
+import mdoc.interfaces.RangePosition
+
+case class EvaluatedWorksheetStatement(
+    val position: RangePosition,
+    val summary: String,
+    val details: String
+) extends mdoc.interfaces.EvaluatedWorksheetStatement

mdoc/src/main/scala/mdoc/internal/worksheets/Mdoc.scala

@@ -0,0 +1,63 @@
+package mdoc.internal.worksheets
+
+import java.{util => ju}
+import java.io.File
+import java.io.PrintStream
+import java.nio.file.Path
+import scala.collection.JavaConverters._
+import mdoc.{interfaces => i}
+import mdoc.internal.cli.Context
+import mdoc.internal.cli.Settings
+import scala.meta.internal.io.PathIO
+import mdoc.internal.io.ConsoleReporter
+import mdoc.internal.markdown.MarkdownCompiler
+import scala.meta.inputs.Input
+import mdoc.internal.worksheets.Compat._
+import mdoc.MainSettings
+
+class Mdoc(settings: MainSettings) extends i.Mdoc {
+
+  private var myContext: Context = null
+
+  def this() = this(MainSettings())
+
+  def withClasspath(classpath: ju.List[Path]): i.Mdoc =
+    new Mdoc(this.settings.withClasspath(classpath.iterator().asScala.mkString(File.pathSeparator)))
+  def withScalacOptions(options: ju.List[String]): i.Mdoc =
+    new Mdoc(this.settings.withScalacOptions(options.iterator().asScala.mkString(" ")))
+  def withSettings(settings: ju.List[String]): i.Mdoc =
+    new Mdoc(this.settings.withArgs(settings.iterator().asScala.toList))
+  def withConsoleReporter(out: PrintStream): i.Mdoc =
+    new Mdoc(this.settings.withReporter(new ConsoleReporter(out)))
+  def withScreenWidth(screenWidth: Int): i.Mdoc =
+    new Mdoc(this.settings.withScreenWidth(screenWidth))
+  def withScreenHeight(screenHeight: Int): i.Mdoc =
+    new Mdoc(this.settings.withScreenHeight(screenHeight))
+
+  def shutdown(): Unit = {
+    if (myContext != null) {
+      myContext.compiler.global.close()
+      usedDummy()
+    }
+  }
+
+  def evaluateWorksheet(filename: String, text: String): EvaluatedWorksheet =
+    new WorksheetProvider(settings.settings).evaluateWorksheet(
+      Input.VirtualFile(filename, text),
+      context
+    )
+
+  private def context(): Context = {
+    if (myContext == null) {
+      myContext = Context(
+        settings.settings,
+        settings.reporter,
+        MarkdownCompiler.fromClasspath(
+          settings.settings.classpath,
+          settings.settings.scalacOptions
+        )
+      )
+    }
+    myContext
+  }
+}