Add life-cycle methods to PostProcessor modifiers

docs/modifiers.md

@@ -301,6 +301,19 @@ val message = "hello world!"
 ```
 ````
 
+In addition to the `process` method, the `PostModifier` trait also has several 
+life-cycle methods that signal when a `PostModifier` instance:
+* Has started for the first time (`onStart`) when MDoc is launched;
+* Just before compilation and processing occurs (`preProcess`) on each source 
+document file;
+* Just after compilation and processing has finished (`postProcess`) on each 
+source document file;
+* Has finished after processing the last source document file (`onExit`)
+before MDoc terminates.
+These methods can be used to initialize and deactivate resources required by 
+the `PostModifier` instances.  
+
+
 ## StringModifier
 
 A `StringModifier` is a custom modifier that processes the plain text contents

mdoc-docs/src/main/resources/META-INF/services/mdoc.PostModifier

@@ -1 +1,2 @@
 mdoc.docs.EvilplotModifier
+mdoc.docs.LifeCycleModifier

mdoc-docs/src/main/scala/mdoc/docs/EvilplotModifier.scala

@@ -3,7 +3,10 @@ package mdoc.docs
 import com.cibo.evilplot.geometry.Drawable
 import java.nio.file.Files
 import java.nio.file.Paths
+
 import mdoc._
+import mdoc.internal.cli.Exit
+
 import scala.meta.inputs.Position
 
 class EvilplotModifier extends PostModifier {
@@ -36,4 +39,12 @@ class EvilplotModifier extends PostModifier {
         ""
     }
   }
+
+  override def onStart(settings: MainSettings): Unit = ()
+
+  override def preProcess(ctx: PostModifierContext): Unit = ()
+
+  override def postProcess(ctx: PostModifierContext): Unit = ()
+
+  override def onExit(exit: Exit): Unit = ()
 }

mdoc-docs/src/main/scala/mdoc/docs/LifeCycleModifier.scala

@@ -0,0 +1,50 @@
+package mdoc.docs
+
+import mdoc._
+import mdoc.internal.cli.Exit
+
+/**
+  * Global counter used to test the [[mdoc.Main]] process counting.
+  */
+object LifeCycleCounter {
+  val numberOfStarts: ThreadLocal[Integer] = ThreadLocal.withInitial(() => 0)
+  val numberOfExists: ThreadLocal[Integer] = ThreadLocal.withInitial(() => 0)
+}
+
+class LifeCycleModifier extends PostModifier {
+  val name = "lifecycle"
+
+  // Starts and stops per instance
+  var numberOfStarts = 0
+  var numberOfExists = 0
+  // Pre and post processing per instance
+  var numberOfPreProcess = 0
+  var numberOfPostProcess = 0
+
+  def process(ctx: PostModifierContext): String = {
+    // Used for checking the counting
+    s"numberOfStarts = $numberOfStarts ; numberOfExists = $numberOfExists ; numberOfPreProcess = $numberOfPreProcess ; numberOfPostProcess = $numberOfPostProcess"
+  }
+
+  /**
+    * This is called once when the [[mdoc.Main]] process starts
+    * @param settings CLI or API settings used by mdoc
+    */
+  override def onStart(settings: MainSettings): Unit = {
+    numberOfStarts += 1
+    LifeCycleCounter.numberOfStarts.set(LifeCycleCounter.numberOfStarts.get() + 1)
+  }
+
+  override def preProcess(ctx: PostModifierContext): Unit = { numberOfPreProcess += 1 }
+
+  override def postProcess(ctx: PostModifierContext): Unit = { numberOfPostProcess += 1 }
+
+  /**
+    * This is called once when the [[mdoc.Main]] process finsihes
+    * @param exit is the exit code returned by mdoc's processing
+    */
+  override def onExit(exit: Exit): Unit = {
+    numberOfExists += 1
+    LifeCycleCounter.numberOfExists.set(LifeCycleCounter.numberOfExists.get() + 1)
+  }
+}

mdoc/src/main/scala/mdoc/Main.scala

@@ -8,7 +8,6 @@ import scala.meta.io.AbsolutePath
 import mdoc.internal.cli.MainOps
 import mdoc.internal.cli.Settings
 import mdoc.internal.io.ConsoleReporter
-import mdoc.internal.markdown.Markdown
 
 object Main {
 
@@ -23,10 +22,11 @@ object Main {
   def process(args: Array[String], reporter: Reporter, cwd: Path): Int = {
     val base = Settings.default(AbsolutePath(cwd))
     val ctx = Settings.fromCliArgs(args.toList, base)
-    MainOps.process(ctx, reporter)
+    val mainSettings = ctx.andThen(s => Configured.ok(new MainSettings(s, reporter)))
+    MainOps.process(mainSettings, reporter)
   }
   def process(settings: MainSettings): Int = {
-    MainOps.process(Configured.ok(settings.settings), settings.reporter)
+    MainOps.process(Configured.ok(settings), settings.reporter)
   }
 
 }

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

@@ -11,7 +11,7 @@ import scala.meta.io.AbsolutePath
 import mdoc.internal.cli.Settings
 import mdoc.internal.io.ConsoleReporter
 
-final class MainSettings private (
+final class MainSettings private[mdoc] (
     private[mdoc] val settings: Settings,
     private[mdoc] val reporter: Reporter
 ) {

mdoc/src/main/scala/mdoc/PostModifier.scala

@@ -1,19 +1,25 @@
 package mdoc
 
 import java.util.ServiceLoader
-import mdoc.internal.cli.Settings
+
+import mdoc.internal.cli.{Exit, Settings}
 import metaconfig.ConfDecoder
 import metaconfig.ConfEncoder
 import metaconfig.ConfError
 import metaconfig.generic.Surface
+
 import scala.meta.inputs.Input
 import scala.meta.io.AbsolutePath
 import scala.collection.JavaConverters._
 import scala.meta.io.RelativePath
 
 trait PostModifier {
   val name: String
+  def onStart(settings: MainSettings): Unit = ()
+  def preProcess(ctx: PostModifierContext): Unit = ()
   def process(ctx: PostModifierContext): String
+  def postProcess(ctx: PostModifierContext): Unit = ()
+  def onExit(exit: Exit): Unit = ()
 }
 
 object PostModifier {

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

@@ -6,7 +6,8 @@ import io.methvin.watcher.DirectoryChangeEvent
 import java.nio.file.Files
 import java.nio.file.StandardCopyOption
 import java.util.concurrent.Executors
-import mdoc.Reporter
+
+import mdoc.{MainSettings, Reporter}
 import mdoc.internal.BuildInfo
 import mdoc.internal.io.IO
 import mdoc.internal.io.MdocFileListener
@@ -17,6 +18,7 @@ import mdoc.internal.markdown.LinkHygiene
 import mdoc.internal.markdown.Markdown
 import mdoc.internal.pos.DiffUtils
 import metaconfig.Configured
+
 import scala.meta.Input
 import scala.meta.internal.io.FileIO
 import scala.meta.internal.io.PathIO
@@ -209,28 +211,30 @@ final class MainOps(
 }
 
 object MainOps {
-  def process(settings: Configured[Settings], reporter: Reporter): Int = {
+  def process(settings: Configured[MainSettings], reporter: Reporter): Int = {
     settings match {
-      case Configured.Ok(setting) if setting.help =>
+      case Configured.Ok(setting) if setting.settings.help =>
         reporter.println(Settings.help(BuildInfo.version, 80))
         0
-      case Configured.Ok(setting) if setting.usage =>
+      case Configured.Ok(setting) if setting.settings.usage =>
         reporter.println(Settings.usage)
         0
-      case Configured.Ok(setting) if setting.version =>
+      case Configured.Ok(setting) if setting.settings.version =>
         reporter.println(Settings.version(BuildInfo.version))
         0
       case els =>
-        els.andThen(_.validate(reporter)) match {
+        els.andThen(_.settings.validate(reporter)) match {
           case Configured.NotOk(error) =>
             error.all.foreach(message => reporter.error(message))
             1
           case Configured.Ok(ctx) =>
             if (ctx.settings.verbose) {
               ctx.reporter.setDebugEnabled(true)
             }
+            ctx.settings.postModifiers.foreach(_.onStart(settings.get))
             val runner = new MainOps(ctx)
             val exit = runner.run()
+            ctx.settings.postModifiers.foreach(_.onExit(exit))
             if (exit.isSuccess) {
               0
             } else {

mdoc/src/main/scala/mdoc/internal/markdown/Processor.scala

@@ -171,7 +171,9 @@ class Processor(implicit ctx: Context) {
               inputFile,
               ctx.settings
             )
+            modifier.preProcess(postCtx)
             val postRender = modifier.process(postCtx)
+            modifier.postProcess(postCtx)
             replaceNodeWithText(doc, block, postRender)
           case m: Modifier.Builtin =>
             if (m.isPassthrough) {

tests/unit/src/test/resources/META-INF/services/mdoc.PostModifier

@@ -1,2 +1,4 @@
 tests.markdown.EvilplotPostModifier
 tests.markdown.BulletPostModifier
+tests.markdown.LifeCycleModifier
+

tests/unit/src/test/scala-2.11/tests/markdown/EvilplotPostModifier.scala

@@ -1,9 +1,18 @@
 package tests.markdown
 
-import mdoc.PostModifier
-import mdoc.PostModifierContext
+import mdoc.{MainSettings, PostModifier, PostModifierContext}
+import mdoc.internal.cli.Exit
 
 class EvilplotPostModifier extends PostModifier {
   val name = "evilplot"
+
   def process(ctx: PostModifierContext): String = ""
+
+  override def onStart(settings: MainSettings): Unit = ()
+
+  override def preProcess(ctx: PostModifierContext): Unit = ()
+
+  override def postProcess(ctx: PostModifierContext): Unit = ()
+
+  override def onExit(exit: Exit): Unit = ()
 }

tests/unit/src/test/scala-2.12/tests/markdown/EvilplotPostModifier.scala

@@ -2,8 +2,9 @@ package tests.markdown
 
 import com.cibo.evilplot.geometry.Drawable
 import java.nio.file.Files
-import mdoc.PostModifier
-import mdoc.PostModifierContext
+
+import mdoc.{MainSettings, PostModifier, PostModifierContext}
+import mdoc.internal.cli.Exit
 
 class EvilplotPostModifier extends PostModifier {
   val name = "evilplot"
@@ -28,4 +29,13 @@ class EvilplotPostModifier extends PostModifier {
         ""
     }
   }
+
+  override def onStart(settings: MainSettings): Unit = ()
+
+  override def preProcess(ctx: PostModifierContext): Unit = ()
+
+  override def postProcess(ctx: PostModifierContext): Unit = ()
+
+  override def onExit(exit: Exit): Unit = ()
+
 }

tests/unit/src/test/scala-2.12/tests/markdown/PostModifierSuite.scala

@@ -53,4 +53,26 @@ class PostModifierSuite extends BaseMarkdownSuite {
     "error: expected int runtime value. Obtained message"
   )
 
+  check(
+    "lifecycle-1",
+    """
+      |```scala mdoc:lifecycle
+      |val x = "message"
+      |```
+    """.stripMargin,
+    "numberOfStarts = 0 ; numberOfExists = 0 ; numberOfPreProcess = 1 ; numberOfPostProcess = 0"
+  )
+
+  // Process counts are per PostModifier instance, starts and exists per mdoc.Main process
+  // Because each test runs its own mdoc.Main process, the process counts are the same
+  check(
+    "lifecycle-2",
+    """
+      |```scala mdoc:lifecycle
+      |val x = "message"
+      |```
+    """.stripMargin,
+    "numberOfStarts = 0 ; numberOfExists = 0 ; numberOfPreProcess = 1 ; numberOfPostProcess = 0"
+  )
+
 }

tests/unit/src/test/scala-2.13/tests/markdown/EvilplotPostModifier.scala

@@ -1,9 +1,17 @@
 package tests.markdown
 
-import mdoc.PostModifier
-import mdoc.PostModifierContext
+import mdoc.{MainSettings, PostModifier, PostModifierContext}
+import mdoc.internal.cli.Exit
 
 class EvilplotPostModifier extends PostModifier {
   val name = "evilplot"
   def process(ctx: PostModifierContext): String = ""
+
+  override def onStart(settings: MainSettings): Unit = ()
+
+  override def preProcess(ctx: PostModifierContext): Unit = ()
+
+  override def postProcess(ctx: PostModifierContext): Unit = ()
+
+  override def onExit(exit: Exit): Unit = ()
 }