From aa2b2865d0bd9c3a8ff792ec172773c65278f30b Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 22:47:12 +0000 Subject: [PATCH 1/8] Improve documentation wording --- .../java/io/spine/annotation/Internal.java | 43 +++++++++---------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/src/main/java/io/spine/annotation/Internal.java b/src/main/java/io/spine/annotation/Internal.java index 0419dfe57d..8496fee005 100644 --- a/src/main/java/io/spine/annotation/Internal.java +++ b/src/main/java/io/spine/annotation/Internal.java @@ -33,36 +33,35 @@ import java.lang.annotation.Target; /** - * Annotates a program element (class, method, package, etc.) which is not a part of a public API, - * and thus should not be used by people who are not members of the team developing the module - * containing this program element. + * Marks a program element (class, method, package, etc.) as internal to the Spine Event Engine, + * indicating it is NOT part of the public API and hence not intended for use outside + * the module's development team. * - *

If the annotation is used for a constructor, a field, - * a method, or a package, it means - * that corresponding element is internal to the Spine Event Engine and as such should - * not be used programmers using the framework. + *

The usage scenarios for the annotation vary depending on the element it is applied to. * - *

If the annotation is used for a type it means one of the following. + *

If applied to a constructor, field, method, or package

* - *

First reason. This type is internal to the Spine Event Engine framework, - * and is not meant to be used directly by the framework users.

+ *

The annotated program element is not intended for usage by the framework users * - *

Second reason. The type is internal to a bounded context, artifact of which - * exposes the type to the outside world (presumably for historical reasons).

+ *

If applied to a type

* - *

When so, the type with this annotation can be used only inside the bounded context - * which declares it. + *

The annotation applied to a type could mean either: + *

* - * @apiNote If you plan to implement an extension which is going to be wired into - * the framework, you may want to use the internal parts. Please consider consulting with the Spine - * development team, as the internal APIs do not have the same stability guarantee as public ones. - * - *

See {@link SPI} annotation if you plan to write an extension of the framework. + *

See also {@link SPI} for annotations related to framework extensions. * + * @apiNote Implementing an extension to wire into the framework might tempt you + * to use these internal parts. + * However, be aware that they might have less stability than public APIs. + * Consultation with the Spine development team is strongly recommended in these cases. * @see SPI */ @Internal From d718f4f57137e0afe0129d0369e5427caaa70375 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 22:52:39 +0000 Subject: [PATCH 2/8] Update `config` --- config | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config b/config index f3d4902651..7381842cfe 160000 --- a/config +++ b/config @@ -1 +1 @@ -Subproject commit f3d4902651973cd3f40f197f452b55e6f61de0f6 +Subproject commit 7381842cfe351b54baab6749795f6942effea6da From 809fa69d55facec016862cb121b42e6fb908f355 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 22:52:52 +0000 Subject: [PATCH 3/8] Bump version -> `2.0.0-SNAPSHOT.194` --- dependencies.md | 4 ++-- pom.xml | 2 +- version.gradle.kts | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/dependencies.md b/dependencies.md index 51ffe6783d..d3ed89bde7 100644 --- a/dependencies.md +++ b/dependencies.md @@ -1,6 +1,6 @@ -# Dependencies of `io.spine:spine-base:2.0.0-SNAPSHOT.193` +# Dependencies of `io.spine:spine-base:2.0.0-SNAPSHOT.194` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -784,4 +784,4 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Fri Nov 24 17:06:57 WET 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file +This report was generated on **Tue Dec 12 22:49:02 WET 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file diff --git a/pom.xml b/pom.xml index 3880270d41..7c8ff3b44a 100644 --- a/pom.xml +++ b/pom.xml @@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject. --> io.spine base -2.0.0-SNAPSHOT.193 +2.0.0-SNAPSHOT.194 2015 diff --git a/version.gradle.kts b/version.gradle.kts index 4d50f7c779..5ae47d20b9 100644 --- a/version.gradle.kts +++ b/version.gradle.kts @@ -24,4 +24,4 @@ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -val versionToPublish: String by extra("2.0.0-SNAPSHOT.193") +val versionToPublish: String by extra("2.0.0-SNAPSHOT.194") From 2f45fd72a84451a5258a8a485a92ee5474441b52 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 23:00:35 +0000 Subject: [PATCH 4/8] Bump Protobuf -> `3.25.1` --- .../src/main/kotlin/io/spine/internal/dependency/Protobuf.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/buildSrc/src/main/kotlin/io/spine/internal/dependency/Protobuf.kt b/buildSrc/src/main/kotlin/io/spine/internal/dependency/Protobuf.kt index 32c05ecd92..be80d2dfbc 100644 --- a/buildSrc/src/main/kotlin/io/spine/internal/dependency/Protobuf.kt +++ b/buildSrc/src/main/kotlin/io/spine/internal/dependency/Protobuf.kt @@ -33,7 +33,7 @@ package io.spine.internal.dependency ) object Protobuf { private const val group = "com.google.protobuf" - const val version = "3.25.0" + const val version = "3.25.1" /** * The Java library containing proto definitions of Google Protobuf. */ From 7d169f4c32be5fa951278f715aa4d74f3afd92c1 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 23:00:48 +0000 Subject: [PATCH 5/8] Update dependency reports --- dependencies.md | 16 ++++++++-------- pom.xml | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/dependencies.md b/dependencies.md index d3ed89bde7..e47b758b2e 100644 --- a/dependencies.md +++ b/dependencies.md @@ -38,15 +38,15 @@ * **Project URL:** [https://github.com/google/j2objc/](https://github.com/google/j2objc/) * **License:** [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt) -1. **Group** : com.google.protobuf. **Name** : protobuf-java. **Version** : 3.25.0. +1. **Group** : com.google.protobuf. **Name** : protobuf-java. **Version** : 3.25.1. * **Project URL:** [https://developers.google.com/protocol-buffers/](https://developers.google.com/protocol-buffers/) * **License:** [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) -1. **Group** : com.google.protobuf. **Name** : protobuf-java-util. **Version** : 3.25.0. +1. **Group** : com.google.protobuf. **Name** : protobuf-java-util. **Version** : 3.25.1. * **Project URL:** [https://developers.google.com/protocol-buffers/](https://developers.google.com/protocol-buffers/) * **License:** [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) -1. **Group** : com.google.protobuf. **Name** : protobuf-kotlin. **Version** : 3.25.0. +1. **Group** : com.google.protobuf. **Name** : protobuf-kotlin. **Version** : 3.25.1. * **License:** [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) 1. **Group** : org.checkerframework. **Name** : checker-compat-qual. **Version** : 2.5.3. @@ -221,18 +221,18 @@ * **Project URL:** [https://github.com/google/j2objc/](https://github.com/google/j2objc/) * **License:** [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt) -1. **Group** : com.google.protobuf. **Name** : protobuf-java. **Version** : 3.25.0. +1. **Group** : com.google.protobuf. **Name** : protobuf-java. **Version** : 3.25.1. * **Project URL:** [https://developers.google.com/protocol-buffers/](https://developers.google.com/protocol-buffers/) * **License:** [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) -1. **Group** : com.google.protobuf. **Name** : protobuf-java-util. **Version** : 3.25.0. +1. **Group** : com.google.protobuf. **Name** : protobuf-java-util. **Version** : 3.25.1. * **Project URL:** [https://developers.google.com/protocol-buffers/](https://developers.google.com/protocol-buffers/) * **License:** [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) -1. **Group** : com.google.protobuf. **Name** : protobuf-kotlin. **Version** : 3.25.0. +1. **Group** : com.google.protobuf. **Name** : protobuf-kotlin. **Version** : 3.25.1. * **License:** [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) -1. **Group** : com.google.protobuf. **Name** : protoc. **Version** : 3.25.0. +1. **Group** : com.google.protobuf. **Name** : protoc. **Version** : 3.25.1. * **Project URL:** [https://developers.google.com/protocol-buffers/](https://developers.google.com/protocol-buffers/) * **License:** [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause) * **License:** [The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt) @@ -784,4 +784,4 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Tue Dec 12 22:49:02 WET 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file +This report was generated on **Tue Dec 12 22:54:37 WET 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file diff --git a/pom.xml b/pom.xml index 7c8ff3b44a..971055e002 100644 --- a/pom.xml +++ b/pom.xml @@ -32,19 +32,19 @@ all modules and does not describe the project structure per-subproject. com.google.protobuf protobuf-java - 3.25.0 + 3.25.1 compile com.google.protobuf protobuf-java-util - 3.25.0 + 3.25.1 compile com.google.protobuf protobuf-kotlin - 3.25.0 + 3.25.1 compile @@ -174,7 +174,7 @@ all modules and does not describe the project structure per-subproject. com.google.protobuf protoc - 3.25.0 + 3.25.1 com.puppycrawl.tools From 63b7ea9cdff45c139bd7e9c93c8f3cdcaa71d411 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 23:33:20 +0000 Subject: [PATCH 6/8] Add string utilities for indentation Also: * Expose naturalization of line endings. --- src/main/kotlin/io/spine/string/Separator.kt | 4 +- src/main/kotlin/io/spine/string/Strings.kt | 59 ++++++++++++++++--- .../kotlin/io/spine/string/StringsSpec.kt | 21 +++++++ 3 files changed, 73 insertions(+), 11 deletions(-) diff --git a/src/main/kotlin/io/spine/string/Separator.kt b/src/main/kotlin/io/spine/string/Separator.kt index c18e67e202..78239e780c 100644 --- a/src/main/kotlin/io/spine/string/Separator.kt +++ b/src/main/kotlin/io/spine/string/Separator.kt @@ -37,8 +37,8 @@ public enum class Separator( public val value: String, /** - * The representation of [value] to be used for debugging multi-line strings terminated. - * by [system line separator][nl]. + * The representation of [value] to be used for debugging multi-line strings + * terminated by [system line separator][nl]. */ public val escaped: String ) { diff --git a/src/main/kotlin/io/spine/string/Strings.kt b/src/main/kotlin/io/spine/string/Strings.kt index 08c2dac068..110bccb0c5 100644 --- a/src/main/kotlin/io/spine/string/Strings.kt +++ b/src/main/kotlin/io/spine/string/Strings.kt @@ -57,8 +57,8 @@ public fun Iterable.joinBackticked(): String = /** * Obtains the same string but with the first capital letter. * - * If the first char of the string cannot be capitalized (e.g., is not a letter, is already - * capitalized, etc.), obtains the same string. + * If the first char of the string cannot be capitalized (e.g., is not a letter, + * is already capitalized, etc.), obtains the same string. */ public fun String.titleCase(): String = replaceFirstChar { it.titlecase() } @@ -77,6 +77,11 @@ public fun String.titleCase(): String = public fun String.camelCase(): String = split("_").camelCase() +/** + * System-dependent line separator. + */ +private val NL: String = Separator.nl() + /** * Trims the common indent from all the lines, as well as the trailing whitespace. * @@ -90,28 +95,64 @@ public fun String.trimWhitespace(): String { val trimmedLines = lines.map { it.trimEnd() } - return trimmedLines.joinToString(Separator.nl()) + return trimmedLines.joinToString(NL) } /** - * Replaces [Separator.LF] used by Kotlin string utilities for splitting by lines, - * with [Separator.nl] so that we don't have issues when writing generated texts under Windows. + * Replaces [Separator.LF] with [Separator.system]. + * + * [Separator.LF] is used by Kotlin string utilities for splitting by lines. + * This may cause issues when writing generated texts under Windows. + * + * If you could not find a replacement for system-dependent line separation in + * `io.spine.string` package, please use this function after a Kotlin string utility call. + * + * @see String.pi + * @see String.tm + * @see String.ti */ -private fun String.fixLineEndings(): String = replace(Separator.LF.value, Separator.nl()) +public fun String.naturalizeEndings(): String = replace(Separator.LF.value, NL) /** * Trims indentation similarly to [String.trimIndent] but preserving system line separators. */ -public fun String.ti(): String = trimIndent().fixLineEndings() +public fun String.ti(): String = trimIndent().naturalizeEndings() + +/** + * The same as [trimMargin] but with system-dependent line separator. + */ +public fun String.tm(): String = trimMargin().naturalizeEndings() /** * Prepends indentation similarly to [String.prependIndent] but preserving system line separators. + * + * @see Iterable.indent */ public fun String.pi(indent: String = Indent.defaultJavaIndent.value): String = - prependIndent(indent).fixLineEndings() + prependIndent(indent).naturalizeEndings() /** * Joins the elements of this `Iterable` into a single string having each item on a separate line. + * + * The lines are delimited with system line separator. */ public fun Iterable<*>.joinByLines(): String = - joinToString(separator = Separator.nl()) + joinToString(separator = NL) + +/** + * Joins these lines of code into a code block, accounting for extra indent. + * + * Similar to [prependIndent] but with system-dependent line separator. + * + * @param step + * the indentation of each level. + * @param level + * the number of indentation levels to add. If zero, no indentation would be added. + * @see String.pi + */ +public fun Iterable.indent(step: Indent, level: Int): String { + val indentation = step.atLevel(level) + return joinToString(NL) { + indentation + it + } +} diff --git a/src/test/kotlin/io/spine/string/StringsSpec.kt b/src/test/kotlin/io/spine/string/StringsSpec.kt index 821e8f91f7..6ba95613b8 100644 --- a/src/test/kotlin/io/spine/string/StringsSpec.kt +++ b/src/test/kotlin/io/spine/string/StringsSpec.kt @@ -98,4 +98,25 @@ class StringsSpec { val value = "some value" value.stringify() shouldBe value } + + @Test + fun `indent lines`() { + val source = """ + line 1 + line 2 + line 3 + """.ti().lines() + + source.indent(Indent(size = 2), level = 2) shouldBe """ + | line 1 + | line 2 + | line 3 + """.tm() + + source.indent(Indent(size = 3), level = 0) shouldBe """ + |line 1 + |line 2 + |line 3 + """.tm() + } } From 0f4807bb51d7a275a4ea319ced6eeb1297aa5edc Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 23:35:03 +0000 Subject: [PATCH 7/8] Suppress detekt `TooManyFunctions` --- src/main/kotlin/io/spine/string/Strings.kt | 1 + 1 file changed, 1 insertion(+) diff --git a/src/main/kotlin/io/spine/string/Strings.kt b/src/main/kotlin/io/spine/string/Strings.kt index 110bccb0c5..e5c80ee356 100644 --- a/src/main/kotlin/io/spine/string/Strings.kt +++ b/src/main/kotlin/io/spine/string/Strings.kt @@ -25,6 +25,7 @@ */ @file:JvmName("Strings") +@file:Suppress("TooManyFunctions") // Extension functions for `String` are grouped here. package io.spine.string From 554d73ad7dd0df7548a86c3dd9662ceb7356a5dd Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Tue, 12 Dec 2023 23:35:11 +0000 Subject: [PATCH 8/8] Update dependency report --- dependencies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dependencies.md b/dependencies.md index e47b758b2e..b835eedfcf 100644 --- a/dependencies.md +++ b/dependencies.md @@ -784,4 +784,4 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Tue Dec 12 22:54:37 WET 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file +This report was generated on **Tue Dec 12 23:35:01 WET 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file