convert public case classes in laika.rewrite.link (#490)

Author: jenshalm

core/shared/src/main/scala/laika/directive/std/LinkDirectives.scala

@@ -45,7 +45,7 @@ private[laika] object LinkDirectives {
   private def linkConfig[T](cursor: DocumentCursor): Either[String, LinkConfig] =
     cursor.config
       .getOpt[LinkConfig]
-      .map(_.getOrElse(LinkConfig()))
+      .map(_.getOrElse(LinkConfig.empty))
       .leftMap(_.message)
 
   /** Implementation of the `api` directive that creates links to API documentation based

core/shared/src/main/scala/laika/rewrite/TemplateRewriter.scala

@@ -170,7 +170,9 @@ sealed abstract class OutputContext {
 object OutputContext {
 
   private final case class Impl(fileSuffix: String, formatSelector: String)
-      extends OutputContext
+      extends OutputContext {
+    override def productPrefix: String = "OutputContext"
+  }
 
   private[laika] def apply(fileSuffix: String, formatSelector: String): OutputContext =
     Impl(fileSuffix, formatSelector)

core/shared/src/main/scala/laika/rewrite/link/IconRegistry.scala

@@ -5,11 +5,15 @@ import laika.config.{ ConfigEncoder, DefaultKey, LaikaKeys }
 
 /** Registers Icon AST elements for use with the `@:icon` directive and the `IconReference` AST element.
   */
-case class IconRegistry private (icons: Map[String, Icon])
+class IconRegistry private (private val icons: Map[String, Icon]) {
+
+  def getIcon(id: String): Option[Icon] = icons.get(id)
+
+}
 
 object IconRegistry {
 
-  def apply(icons: (String, Icon)*): IconRegistry = IconRegistry(icons.toMap)
+  def apply(icons: (String, Icon)*): IconRegistry = new IconRegistry(icons.toMap)
 
   implicit val encoder: ConfigEncoder[IconRegistry] = ConfigEncoder.map[Element].contramap(_.icons)
 

core/shared/src/main/scala/laika/rewrite/link/LinkConfig.scala

@@ -16,20 +16,73 @@
 
 package laika.rewrite.link
 
-import laika.ast.{ Path, Target }
-import laika.config._
+import laika.ast.{ ExternalTarget, InternalTarget, Path, Target, VirtualPath }
+import laika.config.*
 
-/** @author Jens Halm
-  */
-case class LinkConfig(
-    targets: Seq[TargetDefinition] = Nil,
-    apiLinks: Seq[ApiLinks] = Nil,
-    sourceLinks: Seq[SourceLinks] = Nil
-)
+sealed abstract class LinkConfig {
+
+  /** List of global link definitions, mapping an identifier to an internal or external target.
+    *
+    * Allows to centralize commonly used URLs and associate them with an id that can be used
+    * in markup sources, avoiding the repetitive definition of those URLs in the markup.
+    *
+    * The use of these ids in markup does not require a directive, it can be used with
+    * "native" markup syntax, e.g. `[linkText][linkId]` in Markdown where `linkId` is
+    * the identifier defined here.
+    */
+  def targets: Seq[TargetDefinition]
+
+  /** Defines a list of base URLs for API links which allows the use
+    * of the `@:api` directive in markup.
+    *
+    * Different base URLs can be defined for different packages,
+    * so that fully qualified class names point to the correct external sources.
+    * In markup it is then sufficient to pass the fully qualified class name
+    * to the directive (e.g. `@:api(com.foo.Person)`)
+    */
+  def apiLinks: Seq[ApiLinks]
+
+  /** Defines a list of base URLs for links to the sources of referenced classes
+    * which allows the use of the `@:source` directive in markup.
+    *
+    * Different base URLs can be defined for different packages,
+    * so that fully qualified class names or a relative path to a markup source file
+    * point to the correct external sources.
+    * In markup it is then sufficient to pass the fully qualified class name
+    * to the directive (e.g. `@:source(com.foo.Person)`) or, when pointing to
+    * markup sources, its relative path (e.g. `@:source(setup/intro.md)`)
+    */
+  def sourceLinks: Seq[SourceLinks]
+
+  def addTargets(newTargets: TargetDefinition*): LinkConfig
+
+  def addApiLinks(newLinks: ApiLinks*): LinkConfig
+
+  def addSourceLinks(newLinks: SourceLinks*): LinkConfig
+
+}
 
 object LinkConfig {
 
-  val empty: LinkConfig = LinkConfig(Nil, Nil, Nil)
+  private final case class Impl(
+      targets: Seq[TargetDefinition],
+      apiLinks: Seq[ApiLinks],
+      sourceLinks: Seq[SourceLinks]
+  ) extends LinkConfig {
+
+    override def productPrefix: String = "LinkConfig"
+
+    def addTargets(newTargets: TargetDefinition*): LinkConfig =
+      copy(targets = targets ++ newTargets)
+
+    def addApiLinks(newLinks: ApiLinks*): LinkConfig = copy(apiLinks = apiLinks ++ newLinks)
+
+    def addSourceLinks(newLinks: SourceLinks*): LinkConfig =
+      copy(sourceLinks = sourceLinks ++ newLinks)
+
+  }
+
+  val empty: LinkConfig = Impl(Nil, Nil, Nil)
 
   implicit val key: DefaultKey[LinkConfig] = DefaultKey(LaikaKeys.links)
 
@@ -42,7 +95,7 @@ object LinkConfig {
       val mappedTargets = targets.map { case (id, targetURL) =>
         TargetDefinition(id, Target.parse(targetURL))
       }
-      LinkConfig(mappedTargets.toSeq, apiLinks, sourceLinks)
+      Impl(mappedTargets.toSeq, apiLinks, sourceLinks)
     }
   }
 
@@ -111,19 +164,49 @@ object LinkValidation {
 
 }
 
-case class TargetDefinition(id: String, target: Target)
+sealed abstract class TargetDefinition {
+  def id: String
+  def target: Target
+}
+
+object TargetDefinition {
+
+  private final case class Impl(id: String, target: Target) extends TargetDefinition {
+    override def productPrefix: String = "TargetDefinition"
+  }
+
+  private[link] def apply(id: String, target: Target): TargetDefinition = Impl(id, target)
 
-case class SourceLinks(baseUri: String, suffix: String, packagePrefix: String = "*")
+  def external(id: String, uri: String): TargetDefinition = Impl(id, ExternalTarget(uri))
+
+  def internal(id: String, path: VirtualPath): TargetDefinition = Impl(id, InternalTarget(path))
+}
+
+sealed abstract class SourceLinks {
+  def baseUri: String
+  def suffix: String
+  def packagePrefix: String
+
+  def withPackagePrefix(prefix: String): SourceLinks
+}
 
 object SourceLinks {
 
+  private final case class Impl(baseUri: String, suffix: String, packagePrefix: String)
+      extends SourceLinks {
+    override def productPrefix: String                 = "SourceLinks"
+    def withPackagePrefix(prefix: String): SourceLinks = copy(packagePrefix = prefix)
+  }
+
+  def apply(baseUri: String, suffix: String): SourceLinks = Impl(baseUri, suffix, "*")
+
   implicit val decoder: ConfigDecoder[SourceLinks] = ConfigDecoder.config.flatMap { config =>
     for {
       baseUri <- config.get[String]("baseUri")
       prefix  <- config.get[String]("packagePrefix", "*")
       suffix  <- config.get[String]("suffix")
     } yield {
-      SourceLinks(baseUri, suffix, prefix)
+      Impl(baseUri, suffix, prefix)
     }
   }
 
@@ -137,21 +220,39 @@ object SourceLinks {
 
 }
 
-case class ApiLinks(
-    baseUri: String,
-    packagePrefix: String = "*",
-    packageSummary: String = "index.html"
-)
+sealed abstract class ApiLinks {
+  def baseUri: String
+  def packagePrefix: String
+  def packageSummary: String
+
+  def withPackagePrefix(prefix: String): ApiLinks
+  def withPackageSummary(prefix: String): ApiLinks
+}
 
 object ApiLinks {
 
+  private final case class Impl(
+      baseUri: String,
+      packagePrefix: String,
+      packageSummary: String
+  ) extends ApiLinks {
+
+    override def productPrefix: String = "ApiLinks"
+
+    def withPackagePrefix(prefix: String): ApiLinks = copy(packagePrefix = prefix)
+
+    def withPackageSummary(summary: String): ApiLinks = copy(packageSummary = summary)
+  }
+
+  def apply(baseUri: String): ApiLinks = Impl(baseUri, "*", "index.html")
+
   implicit val decoder: ConfigDecoder[ApiLinks] = ConfigDecoder.config.flatMap { config =>
     for {
       baseUri <- config.get[String]("baseUri")
       prefix  <- config.get[String]("packagePrefix", "*")
       summary <- config.get[String]("packageSummary", "index.html")
     } yield {
-      ApiLinks(baseUri, prefix, summary)
+      Impl(baseUri, prefix, summary)
     }
   }
 

core/shared/src/test/scala/laika/config/ConfigCodecSpec.scala

@@ -17,7 +17,7 @@
 package laika.config
 
 import cats.data.NonEmptyChain
-import laika.ast.{ DocumentMetadata, ExternalTarget, IconGlyph, IconStyle, InternalTarget }
+import laika.ast.{ DocumentMetadata, IconGlyph, IconStyle }
 import laika.ast.Path.Root
 import laika.ast.RelativePath.CurrentTree
 import laika.rewrite.{ Version, Versions }
@@ -176,23 +176,25 @@ class ConfigCodecSpec extends FunSuite {
 
   object links {
 
-    def sort(config: LinkConfig): LinkConfig = config.copy(targets = config.targets.sortBy(_.id))
-
-    val fullyPopulatedInstance = LinkConfig(
-      Seq(
-        TargetDefinition("bar", InternalTarget(CurrentTree / "bar")),
-        TargetDefinition("ext", ExternalTarget("http://ext.com")),
-        TargetDefinition("foo", InternalTarget(CurrentTree / "foo"))
-      ),
-      Seq(
-        ApiLinks("https://foo.api/", "foo", "package.html"),
-        ApiLinks("https://bar.api/", "foo.bar")
-      ),
-      Seq(
-        SourceLinks("https://foo.source/", "scala", "foo"),
-        SourceLinks("https://bar.source/", "java", "foo.bar")
+    def sort(config: LinkConfig): LinkConfig = LinkConfig.empty
+      .addTargets(config.targets.sortBy(_.id) *)
+      .addApiLinks(config.apiLinks *)
+      .addSourceLinks(config.sourceLinks *)
+
+    val fullyPopulatedInstance = LinkConfig.empty
+      .addTargets(
+        TargetDefinition.internal("bar", CurrentTree / "bar"),
+        TargetDefinition.external("ext", "http://ext.com"),
+        TargetDefinition.internal("foo", CurrentTree / "foo")
+      )
+      .addApiLinks(
+        ApiLinks("https://foo.api/").withPackagePrefix("foo").withPackageSummary("package.html"),
+        ApiLinks("https://bar.api/").withPackagePrefix("foo.bar")
+      )
+      .addSourceLinks(
+        SourceLinks("https://foo.source/", "scala").withPackagePrefix("foo"),
+        SourceLinks("https://bar.source/", "java").withPackagePrefix("foo.bar")
       )
-    )
 
   }
 
@@ -234,10 +236,9 @@ class ConfigCodecSpec extends FunSuite {
       """.stripMargin
     decode[LinkConfig](
       input,
-      LinkConfig(
-        targets = Seq(TargetDefinition("foo", InternalTarget(CurrentTree / "foo"))),
-        apiLinks = Seq(ApiLinks("https://bar.api/"))
-      ),
+      LinkConfig.empty
+        .addTargets(TargetDefinition.internal("foo", CurrentTree / "foo"))
+        .addApiLinks(ApiLinks("https://bar.api/")),
       links.sort
     )
   }

core/shared/src/test/scala/laika/rewrite/RewriteRulesSpec.scala

@@ -317,13 +317,12 @@ class RewriteRulesSpec extends FunSuite with ParagraphCompanionShortcuts with Te
 
     private val linkTarget = RootElement(InternalLinkTarget(Id("ref")))
 
-    private val linkConfig = LinkConfig(targets =
-      Seq(
-        TargetDefinition("int", InternalTarget(RelativePath.parse("../doc-1.md#ref"))),
-        TargetDefinition("ext", ExternalTarget("https://www.foo.com/")),
-        TargetDefinition("inv", InternalTarget(RelativePath.parse("../doc-99.md#ref")))
+    private val linkConfig = LinkConfig.empty
+      .addTargets(
+        TargetDefinition.internal("int", RelativePath.parse("../doc-1.md#ref")),
+        TargetDefinition.external("ext", "https://www.foo.com/"),
+        TargetDefinition.internal("inv", RelativePath.parse("../doc-99.md#ref"))
       )
-    )
 
     def run(ref: LinkIdReference, expected: Block): Unit = {
       val root =