From fa22175d91fd63b833c537990b79569fa3e2f97d Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Mon, 20 Feb 2023 21:45:48 +0100 Subject: Add the ability to pretty print DokkaConfiguration (#2872) --- core/src/main/kotlin/ConfigurationJsonUtils.kt | 50 ++++++++++++++++++++++++++ core/src/main/kotlin/configuration.kt | 10 ------ core/src/main/kotlin/utilities/json.kt | 15 +++++++- 3 files changed, 64 insertions(+), 11 deletions(-) create mode 100644 core/src/main/kotlin/ConfigurationJsonUtils.kt (limited to 'core/src/main/kotlin') diff --git a/core/src/main/kotlin/ConfigurationJsonUtils.kt b/core/src/main/kotlin/ConfigurationJsonUtils.kt new file mode 100644 index 00000000..62c1cc8c --- /dev/null +++ b/core/src/main/kotlin/ConfigurationJsonUtils.kt @@ -0,0 +1,50 @@ +package org.jetbrains.dokka + +import org.jetbrains.dokka.plugability.ConfigurableBlock +import org.jetbrains.dokka.utilities.parseJson +import org.jetbrains.dokka.utilities.serializeAsCompactJson +import org.jetbrains.dokka.utilities.serializeAsPrettyJson + +fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(json) + +fun GlobalDokkaConfiguration(json: String): GlobalDokkaConfiguration = parseJson(json) + +@Deprecated("Renamed to better distinguish between compact/pretty prints", ReplaceWith("this.toCompactJsonString()")) +fun DokkaConfiguration.toJsonString(): String = this.toCompactJsonString() + +@Deprecated("Renamed to better distinguish between compact/pretty prints", ReplaceWith("this.toCompactJsonString()")) +fun T.toJsonString(): String = this.toCompactJsonString() + +/** + * Serializes [DokkaConfiguration] as a machine-readable and compact JSON string. + * + * The returned string is not very human friendly as it will be difficult to parse by eyes due to it + * being compact and in one line. If you want to show the output to a human being, see [toPrettyJsonString]. + */ +fun DokkaConfiguration.toCompactJsonString(): String = serializeAsCompactJson(this) + +/** + * Serializes [DokkaConfiguration] as a human-readable (pretty printed) JSON string. + * + * The returned string will have excessive line breaks and indents, which might not be + * desirable when passing this value between API consumers/producers. If you want + * a machine-readable and compact json string, see [toCompactJsonString]. + */ +fun DokkaConfiguration.toPrettyJsonString(): String = serializeAsPrettyJson(this) + +/** + * Serializes a [ConfigurableBlock] as a machine-readable and compact JSON string. + * + * The returned string is not very human friendly as it will be difficult to parse by eyes due to it + * being compact and in one line. If you want to show the output to a human being, see [toPrettyJsonString]. + */ +fun T.toCompactJsonString(): String = serializeAsCompactJson(this) + +/** + * Serializes a [ConfigurableBlock] as a human-readable (pretty printed) JSON string. + * + * The returned string will have excessive line breaks and indents, which might not be + * desirable when passing this value between API consumers/producers. If you want + * a machine-readable and compact json string, see [toCompactJsonString]. + */ +fun T.toPrettyJsonString(): String = serializeAsCompactJson(this) diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt index 71356e67..9bb81318 100644 --- a/core/src/main/kotlin/configuration.kt +++ b/core/src/main/kotlin/configuration.kt @@ -2,10 +2,7 @@ package org.jetbrains.dokka -import org.jetbrains.dokka.plugability.ConfigurableBlock import org.jetbrains.dokka.utilities.cast -import org.jetbrains.dokka.utilities.parseJson -import org.jetbrains.dokka.utilities.toJsonString import java.io.File import java.io.Serializable import java.net.URL @@ -95,8 +92,6 @@ data class DokkaSourceSetID( } } -fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(json) - /** * Global options can be configured and applied to all packages and modules at once, overwriting package configuration. * @@ -111,8 +106,6 @@ data class GlobalDokkaConfiguration( val sourceLinks: List? ) -fun GlobalDokkaConfiguration(json: String): GlobalDokkaConfiguration = parseJson(json) - fun DokkaConfiguration.apply(globals: GlobalDokkaConfiguration): DokkaConfiguration = this.apply { sourceSets.forEach { it.perPackageOptions.cast>().addAll(globals.perPackageOptions ?: emptyList()) @@ -127,9 +120,6 @@ fun DokkaConfiguration.apply(globals: GlobalDokkaConfiguration): DokkaConfigurat } } -fun DokkaConfiguration.toJsonString(): String = toJsonString(this) -fun T.toJsonString(): String = toJsonString(this) - interface DokkaConfiguration : Serializable { val moduleName: String val moduleVersion: String? diff --git a/core/src/main/kotlin/utilities/json.kt b/core/src/main/kotlin/utilities/json.kt index d3762f6d..61736a99 100644 --- a/core/src/main/kotlin/utilities/json.kt +++ b/core/src/main/kotlin/utilities/json.kt @@ -28,8 +28,21 @@ internal class TypeReference private constructor( } } +// not used anywhere since at least 1.7.20, but might still be referenced in previously compiled +// inline functions. should be safe to remove after a few major releases. @PublishedApi -internal fun toJsonString(value: Any): String = objectMapper.writeValueAsString(value) +@Deprecated( + "Left for previously compiled public inline classes, not for use", + ReplaceWith("serializeAsCompactJson(value)"), + level = DeprecationLevel.ERROR +) +internal fun toJsonString(value: Any): String = serializeAsCompactJson(value) + +internal fun serializeAsCompactJson(value: Any): String = + objectMapper.writeValueAsString(value) + +internal fun serializeAsPrettyJson(value: Any): String = + objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(value) @PublishedApi internal inline fun parseJson(json: String): T = parseJson(json, TypeReference()) -- cgit