diff --git a/MIGRATION.md b/MIGRATION.md new file mode 100644 index 0000000..615c748 --- /dev/null +++ b/MIGRATION.md @@ -0,0 +1,29 @@ +# MIGRATION + +## Preamble + +`2.0.0` release contained a breaking API change which broke binary compatibility. +This was attributed to an issue with Java 9 `Module`s, for which JPMS disallows +split packages. The `encoding-base16`, `encoding-base32` and `encoding-base64` +dependencies were the cause of the issue because their builder classes and functions +were located in the same package named `io.matthewnelson.encoding.builders`. Those +classes and functions were subsequently deprecated in release `1.2.3` so consumers +could gracefully update before upgrading to `2.0.0` where they have been removed. + +For more details, see [[#124]][124]. + +## Migration guide for 1.x.x -> 2.0.0 + + - Update dependency to `1.2.3` + - Migration method 1: + - Use your IDE or editor to search your project for the following + ``` + import io.matthewnelson.encoding.builders + ``` + - Replace `.builders` with the new package location (either `base16`, `base32`, or `base64`) + - Migration method 2: + - Use the provided `ReplaceWith` functionality of the `@Deprecated` notice + to update to the new builder class/function package locations. + - Update dependency to `2.0.0` + +[124]: https://github.com/05nelsonm/encoding/issues/124 \ No newline at end of file diff --git a/library/encoding-base16/api/encoding-base16.api b/library/encoding-base16/api/encoding-base16.api index 140c598..5bb0910 100644 --- a/library/encoding-base16/api/encoding-base16.api +++ b/library/encoding-base16/api/encoding-base16.api @@ -21,6 +21,24 @@ public final class io/matthewnelson/encoding/base16/Base16$Config : io/matthewne public synthetic fun (ZBZLkotlin/jvm/internal/DefaultConstructorMarker;)V } +public final class io/matthewnelson/encoding/base16/Base16ConfigBuilder { + public field encodeToLowercase Z + public field isLenient Z + public field lineBreakInterval B + public fun ()V + public fun (Lio/matthewnelson/encoding/base16/Base16$Config;)V + public final fun build ()Lio/matthewnelson/encoding/base16/Base16$Config; + public final fun strict ()Lio/matthewnelson/encoding/base16/Base16ConfigBuilder; +} + +public final class io/matthewnelson/encoding/base16/BuildersKt { + public static final fun Base16 ()Lio/matthewnelson/encoding/base16/Base16; + public static final fun Base16 (Lio/matthewnelson/encoding/base16/Base16$Config;Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base16/Base16; + public static final fun Base16 (Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base16/Base16; + public static final fun Base16 (Z)Lio/matthewnelson/encoding/base16/Base16; + public static synthetic fun Base16$default (ZILjava/lang/Object;)Lio/matthewnelson/encoding/base16/Base16; +} + public final class io/matthewnelson/encoding/builders/Base16ConfigBuilder { public field encodeToLowercase Z public field isLenient Z diff --git a/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/component/encoding/base16/Base16.kt b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/component/encoding/base16/Base16.kt index 37ae048..8262eea 100644 --- a/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/component/encoding/base16/Base16.kt +++ b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/component/encoding/base16/Base16.kt @@ -17,7 +17,7 @@ package io.matthewnelson.component.encoding.base16 -import io.matthewnelson.encoding.builders.Base16 +import io.matthewnelson.encoding.base16.Base16 import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray import io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray @@ -28,7 +28,7 @@ import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base16())", imports = [ - "io.matthewnelson.encoding.builders.Base16", + "io.matthewnelson.encoding.base16.Base16", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -44,7 +44,7 @@ public inline fun String.decodeBase16ToArray(): ByteArray? { replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base16())", imports = [ - "io.matthewnelson.encoding.builders.Base16", + "io.matthewnelson.encoding.base16.Base16", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -59,7 +59,7 @@ public fun CharArray.decodeBase16ToArray(): ByteArray? { replaceWith = ReplaceWith( expression = "this.encodeToString(Base16())", imports = [ - "io.matthewnelson.encoding.builders.Base16", + "io.matthewnelson.encoding.base16.Base16", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToString", ], ), @@ -75,7 +75,7 @@ public inline fun ByteArray.encodeBase16(): String { replaceWith = ReplaceWith( expression = "this.encodeToCharArray(Base16())", imports = [ - "io.matthewnelson.encoding.builders.Base16", + "io.matthewnelson.encoding.base16.Base16", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray", ], ), @@ -91,7 +91,7 @@ public inline fun ByteArray.encodeBase16ToCharArray(): CharArray { ReplaceWith( expression = "this.encodeToByteArray(Base16())", imports = [ - "io.matthewnelson.encoding.builders.Base16", + "io.matthewnelson.encoding.base16.Base16", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray", ], ), diff --git a/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Base16.kt b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Base16.kt index 4bab0a7..27e633a 100644 --- a/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Base16.kt +++ b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Base16.kt @@ -17,8 +17,6 @@ package io.matthewnelson.encoding.base16 -import io.matthewnelson.encoding.builders.Base16 -import io.matthewnelson.encoding.builders.Base16ConfigBuilder import io.matthewnelson.encoding.core.* import io.matthewnelson.encoding.core.util.DecoderInput import io.matthewnelson.encoding.core.util.FeedBuffer @@ -49,7 +47,7 @@ import kotlin.jvm.JvmSynthetic * val decoded = encoded.decodeToByteArray(Base16).decodeToString() * assertEquals(text, decoded) * - * @see [io.matthewnelson.encoding.builders.Base16] + * @see [io.matthewnelson.encoding.base16.Base16] * @see [Base16.Config] * @see [Base16.CHARS_UPPER] * @see [Base16.CHARS_LOWER] diff --git a/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Builders.kt b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Builders.kt new file mode 100644 index 0000000..5a553ef --- /dev/null +++ b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/base16/Builders.kt @@ -0,0 +1,144 @@ +/* + * Copyright (c) 2023 Matthew Nelson + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + **/ +@file:Suppress("SpellCheckingInspection") + +package io.matthewnelson.encoding.base16 + +import io.matthewnelson.encoding.base16.Base16.Config +import io.matthewnelson.encoding.core.EncodingException +import kotlin.jvm.JvmField +import kotlin.jvm.JvmOverloads + +/** + * Creates a configured [Base16] encoder/decoder. + * + * @param [config] inherit settings from. + * @see [Base16ConfigBuilder] + * */ +public fun Base16( + config: Config?, + block: Base16ConfigBuilder.() -> Unit +): Base16 { + val builder = Base16ConfigBuilder(config) + block.invoke(builder) + return Base16(builder.build()) +} + +/** + * Creates a configured [Base16] encoder/decoder. + * + * @see [Base16ConfigBuilder] + * */ +public fun Base16( + block: Base16ConfigBuilder.() -> Unit +): Base16 { + return Base16(config = null, block) +} + +/** + * Creates a configured [Base16] encoder/decoder + * using the default settings. + * + * @param [strict] If true, configures the encoder/decoder + * to be in strict accordance with RFC 4648. + * @see [Base16ConfigBuilder] + * */ +@JvmOverloads +public fun Base16(strict: Boolean = false): Base16 = Base16 { if (strict) strict() } + + +/** + * Builder for creating a [Base16.Config]. + * + * @see [strict] + * @see [io.matthewnelson.encoding.base16.Base16] + * */ +public class Base16ConfigBuilder { + + public constructor() + public constructor(config: Config?): this() { + if (config == null) return + isLenient = config.isLenient ?: true + lineBreakInterval = config.lineBreakInterval + encodeToLowercase = config.encodeToLowercase + } + + /** + * If true, spaces and new lines ('\n', '\r', ' ', '\t') + * will be skipped over when decoding (against RFC 4648). + * + * If false, an [EncodingException] will be thrown if + * those characters are encountered when decoding. + * */ + @JvmField + public var isLenient: Boolean = true + + /** + * For every [lineBreakInterval] of encoded data, a + * line break will be output. + * + * Will **ONLY** output line breaks if [isLenient] is + * set to **true**. + * + * e.g. + * + * isLenient = true + * lineBreakInterval = 0 + * // 48656C6C6F20576F726C6421 + * + * isLenient = true + * lineBreakInterval = 16 + * // 48656C6C6F20576F + * // 726C6421 + * + * isLenient = false + * lineBreakInterval = 16 + * // 48656C6C6F20576F726C6421 + * + * Enable by setting to a value between 1 and 127, and + * setting [isLenient] to true. + * + * A great value is 64 + * */ + @JvmField + public var lineBreakInterval: Byte = 0 + + /** + * If true, will output lowercase characters when + * encoding (against RFC 4648). + * + * If false, will output uppercase characters when + * encoding. + * */ + @JvmField + public var encodeToLowercase: Boolean = false + + /** + * A shortcut for configuring things to be in strict + * adherence with RFC 4648. + * */ + public fun strict(): Base16ConfigBuilder { + isLenient = false + lineBreakInterval = 0 + encodeToLowercase = false + return this + } + + /** + * Builds a [Base16.Config] for the provided settings. + * */ + public fun build(): Config = Config.from(this) +} diff --git a/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base16.kt b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base16.kt index c2a2d52..b9f720e 100644 --- a/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base16.kt +++ b/library/encoding-base16/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base16.kt @@ -13,22 +13,37 @@ * See the License for the specific language governing permissions and * limitations under the License. **/ -@file:Suppress("SpellCheckingInspection") +@file:Suppress("SpellCheckingInspection", "DEPRECATION") package io.matthewnelson.encoding.builders -import io.matthewnelson.encoding.base16.Base16 import io.matthewnelson.encoding.base16.Base16.Config +import io.matthewnelson.encoding.base16.Base16 import io.matthewnelson.encoding.core.EncodingException import kotlin.jvm.JvmField import kotlin.jvm.JvmOverloads /** - * Creates a configured [Base16] encoder/decoder. + * Deprecated * - * @param [config] inherit settings from. - * @see [Base16ConfigBuilder] + * @see [io.matthewnelson.encoding.base16.Base16] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base16 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base16(config) { block() }", + imports = [ + "io.matthewnelson.encoding.base16.Base16" + ] + ) +) public fun Base16( config: Config?, block: Base16ConfigBuilder.() -> Unit @@ -39,10 +54,26 @@ public fun Base16( } /** - * Creates a configured [Base16] encoder/decoder. + * Deprecated * - * @see [Base16ConfigBuilder] + * @see [io.matthewnelson.encoding.base16.Base16] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base16 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base16 { block() }", + imports = [ + "io.matthewnelson.encoding.base16.Base16" + ] + ) +) public fun Base16( block: Base16ConfigBuilder.() -> Unit ): Base16 { @@ -50,23 +81,51 @@ public fun Base16( } /** - * Creates a configured [Base16] encoder/decoder - * using the default settings. + * Deprecated * - * @param [strict] If true, configures the encoder/decoder - * to be in strict accordance with RFC 4648. - * @see [Base16ConfigBuilder] + * @see [io.matthewnelson.encoding.base16.Base16] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base16 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base16(strict)", + imports = [ + "io.matthewnelson.encoding.base16.Base16" + ] + ) +) @JvmOverloads public fun Base16(strict: Boolean = false): Base16 = Base16 { if (strict) strict() } /** - * Builder for creating a [Base16.Config]. + * Deprecated * - * @see [strict] - * @see [io.matthewnelson.encoding.builders.Base16] + * @see [io.matthewnelson.encoding.base16.Base16ConfigBuilder] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base16 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base16ConfigBuilder", + imports = [ + "io.matthewnelson.encoding.base16.Base16ConfigBuilder" + ] + ) +) public class Base16ConfigBuilder { public constructor() @@ -141,5 +200,11 @@ public class Base16ConfigBuilder { /** * Builds a [Base16.Config] for the provided settings. * */ - public fun build(): Config = Config.from(this) + public fun build(): Config { + val b = io.matthewnelson.encoding.base16.Base16ConfigBuilder() + b.isLenient = isLenient + b.lineBreakInterval = lineBreakInterval + b.encodeToLowercase = encodeToLowercase + return b.build() + } } diff --git a/library/encoding-base16/src/commonTest/kotlin/io/matthewnelson/encoding/base16/Base16UnitTest.kt b/library/encoding-base16/src/commonTest/kotlin/io/matthewnelson/encoding/base16/Base16UnitTest.kt index 20d5bd1..cb4da53 100644 --- a/library/encoding-base16/src/commonTest/kotlin/io/matthewnelson/encoding/base16/Base16UnitTest.kt +++ b/library/encoding-base16/src/commonTest/kotlin/io/matthewnelson/encoding/base16/Base16UnitTest.kt @@ -15,7 +15,6 @@ **/ package io.matthewnelson.encoding.base16 -import io.matthewnelson.encoding.builders.Base16 import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArray import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString diff --git a/library/encoding-base32/api/encoding-base32.api b/library/encoding-base32/api/encoding-base32.api index 65a16c7..4f37e6d 100644 --- a/library/encoding-base32/api/encoding-base32.api +++ b/library/encoding-base32/api/encoding-base32.api @@ -113,6 +113,59 @@ public final class io/matthewnelson/encoding/base32/Base32$Hex$Config : io/matth public synthetic fun (ZBZZLkotlin/jvm/internal/DefaultConstructorMarker;)V } +public final class io/matthewnelson/encoding/base32/Base32CrockfordConfigBuilder { + public field encodeToLowercase Z + public field finalizeWhenFlushed Z + public field hyphenInterval B + public field isLenient Z + public fun ()V + public fun (Lio/matthewnelson/encoding/base32/Base32$Crockford$Config;)V + public final fun build ()Lio/matthewnelson/encoding/base32/Base32$Crockford$Config; + public final fun checkSymbol ()Ljava/lang/Character; + public final fun checkSymbol (Ljava/lang/Character;)Lio/matthewnelson/encoding/base32/Base32CrockfordConfigBuilder; + public final fun strict ()Lio/matthewnelson/encoding/base32/Base32CrockfordConfigBuilder; +} + +public final class io/matthewnelson/encoding/base32/Base32DefaultConfigBuilder { + public field encodeToLowercase Z + public field isLenient Z + public field lineBreakInterval B + public field padEncoded Z + public fun ()V + public fun (Lio/matthewnelson/encoding/base32/Base32$Default$Config;)V + public final fun build ()Lio/matthewnelson/encoding/base32/Base32$Default$Config; + public final fun strict ()Lio/matthewnelson/encoding/base32/Base32DefaultConfigBuilder; +} + +public final class io/matthewnelson/encoding/base32/Base32HexConfigBuilder { + public field encodeToLowercase Z + public field isLenient Z + public field lineBreakInterval B + public field padEncoded Z + public fun ()V + public fun (Lio/matthewnelson/encoding/base32/Base32$Hex$Config;)V + public final fun build ()Lio/matthewnelson/encoding/base32/Base32$Hex$Config; + public final fun strict ()Lio/matthewnelson/encoding/base32/Base32HexConfigBuilder; +} + +public final class io/matthewnelson/encoding/base32/BuildersKt { + public static final fun Base32Crockford ()Lio/matthewnelson/encoding/base32/Base32$Crockford; + public static final fun Base32Crockford (Lio/matthewnelson/encoding/base32/Base32$Crockford$Config;Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base32/Base32$Crockford; + public static final fun Base32Crockford (Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base32/Base32$Crockford; + public static final fun Base32Crockford (Z)Lio/matthewnelson/encoding/base32/Base32$Crockford; + public static synthetic fun Base32Crockford$default (ZILjava/lang/Object;)Lio/matthewnelson/encoding/base32/Base32$Crockford; + public static final fun Base32Default ()Lio/matthewnelson/encoding/base32/Base32$Default; + public static final fun Base32Default (Lio/matthewnelson/encoding/base32/Base32$Default$Config;Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base32/Base32$Default; + public static final fun Base32Default (Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base32/Base32$Default; + public static final fun Base32Default (Z)Lio/matthewnelson/encoding/base32/Base32$Default; + public static synthetic fun Base32Default$default (ZILjava/lang/Object;)Lio/matthewnelson/encoding/base32/Base32$Default; + public static final fun Base32Hex ()Lio/matthewnelson/encoding/base32/Base32$Hex; + public static final fun Base32Hex (Lio/matthewnelson/encoding/base32/Base32$Hex$Config;Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base32/Base32$Hex; + public static final fun Base32Hex (Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base32/Base32$Hex; + public static final fun Base32Hex (Z)Lio/matthewnelson/encoding/base32/Base32$Hex; + public static synthetic fun Base32Hex$default (ZILjava/lang/Object;)Lio/matthewnelson/encoding/base32/Base32$Hex; +} + public final class io/matthewnelson/encoding/builders/Base32CrockfordConfigBuilder { public field encodeToLowercase Z public field finalizeWhenFlushed Z diff --git a/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/component/encoding/base32/Base32.kt b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/component/encoding/base32/Base32.kt index 154609d..11ce7b4 100644 --- a/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/component/encoding/base32/Base32.kt +++ b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/component/encoding/base32/Base32.kt @@ -26,9 +26,9 @@ package io.matthewnelson.component.encoding.base32 -import io.matthewnelson.encoding.builders.Base32Crockford -import io.matthewnelson.encoding.builders.Base32Default -import io.matthewnelson.encoding.builders.Base32Hex +import io.matthewnelson.encoding.base32.Base32Crockford +import io.matthewnelson.encoding.base32.Base32Default +import io.matthewnelson.encoding.base32.Base32Hex import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray import io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray @@ -59,7 +59,7 @@ public sealed class Base32 { ) public data class Crockford @JvmOverloads constructor( @Deprecated( - message = "Replaced by EncoderDecoder. Use io.matthewnelson.builders.Base32Crockford to set", + message = "Replaced by EncoderDecoder. Use io.matthewnelson.base32.Base32Crockford to set", level = DeprecationLevel.WARNING ) val checkSymbol: Char? = null @@ -93,13 +93,13 @@ public sealed class Base32 { } @Deprecated( - message = "Replaced by EncoderDecoder. Use io.matthewnelson.builders.Base32Crockford to set", + message = "Replaced by EncoderDecoder. Use io.matthewnelson.base32.Base32Crockford to set", level = DeprecationLevel.WARNING ) inline val hasCheckSymbol: Boolean get() = checkSymbol != null @Deprecated( - message = "Replaced by EncoderDecoder. Use io.matthewnelson.builders.Base32Crockford to set", + message = "Replaced by EncoderDecoder. Use io.matthewnelson.base32.Base32Crockford to set", level = DeprecationLevel.WARNING ) inline val checkByte: Byte? get() = checkSymbol?.uppercaseChar()?.code?.toByte() @@ -161,7 +161,7 @@ public sealed class Base32 { replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base32Default())", imports = [ - "io.matthewnelson.encoding.builders.Base32Default", + "io.matthewnelson.encoding.base32.Base32Default", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -178,7 +178,7 @@ public inline fun String.decodeBase32ToArray(base32: Base32.Default = Base32.Def replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base32Hex())", imports = [ - "io.matthewnelson.encoding.builders.Base32Hex", + "io.matthewnelson.encoding.base32.Base32Hex", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -194,7 +194,7 @@ public inline fun String.decodeBase32ToArray(base32: Base32.Hex): ByteArray? { replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base32Crockford { checkSymbol('value') })", imports = [ - "io.matthewnelson.encoding.builders.Base32Crockford", + "io.matthewnelson.encoding.base32.Base32Crockford", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -210,7 +210,7 @@ public inline fun String.decodeBase32ToArray(base32: Base32.Crockford): ByteArra replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base32Default())", imports = [ - "io.matthewnelson.encoding.builders.Base32Default", + "io.matthewnelson.encoding.base32.Base32Default", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -226,7 +226,7 @@ public fun CharArray.decodeBase32ToArray(base32: Base32.Default = Base32.Default replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base32Hex())", imports = [ - "io.matthewnelson.encoding.builders.Base32Hex", + "io.matthewnelson.encoding.base32.Base32Hex", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -241,7 +241,7 @@ public fun CharArray.decodeBase32ToArray(base32: Base32.Hex): ByteArray? { replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base32Crockford { checkSymbol('value') })", imports = [ - "io.matthewnelson.encoding.builders.Base32Crockford", + "io.matthewnelson.encoding.base32.Base32Crockford", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -256,7 +256,7 @@ public fun CharArray.decodeBase32ToArray(base32: Base32.Crockford): ByteArray? { replaceWith = ReplaceWith( expression = "this.encodeToString(Base32Default())", imports = [ - "io.matthewnelson.encoding.builders.Base32Default", + "io.matthewnelson.encoding.base32.Base32Default", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToString", ], ), @@ -273,7 +273,7 @@ public inline fun ByteArray.encodeBase32(base32: Base32.Default = Base32.Default replaceWith = ReplaceWith( expression = "this.encodeToString(Base32Hex())", imports = [ - "io.matthewnelson.encoding.builders.Base32Hex", + "io.matthewnelson.encoding.base32.Base32Hex", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToString", ], ), @@ -289,7 +289,7 @@ public inline fun ByteArray.encodeBase32(base32: Base32.Hex): String { replaceWith = ReplaceWith( expression = "this.encodeToString(Base32Crockford { checkSymbol('value') })", imports = [ - "io.matthewnelson.encoding.builders.Base32Crockford", + "io.matthewnelson.encoding.base32.Base32Crockford", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToString", ], ), @@ -305,7 +305,7 @@ public inline fun ByteArray.encodeBase32(base32: Base32.Crockford): String { replaceWith = ReplaceWith( expression = "this.encodeToCharArray(Base32Default())", imports = [ - "io.matthewnelson.encoding.builders.Base32Default", + "io.matthewnelson.encoding.base32.Base32Default", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray", ], ), @@ -322,7 +322,7 @@ public inline fun ByteArray.encodeBase32ToCharArray(base32: Base32.Default = Bas replaceWith = ReplaceWith( expression = "this.encodeToCharArray(Base32Hex())", imports = [ - "io.matthewnelson.encoding.builders.Base32Hex", + "io.matthewnelson.encoding.base32.Base32Hex", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray", ], ), @@ -338,7 +338,7 @@ public inline fun ByteArray.encodeBase32ToCharArray(base32: Base32.Hex): CharArr replaceWith = ReplaceWith( expression = "this.encodeToCharArray(Base32Crockford { checkSymbol('value') })", imports = [ - "io.matthewnelson.encoding.builders.Base32Crockford", + "io.matthewnelson.encoding.base32.Base32Crockford", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray", ], ), @@ -354,7 +354,7 @@ public inline fun ByteArray.encodeBase32ToCharArray(base32: Base32.Crockford): C replaceWith = ReplaceWith( expression = "this.encodeToByteArray(Base32Default())", imports = [ - "io.matthewnelson.encoding.builders.Base32Default", + "io.matthewnelson.encoding.base32.Base32Default", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray", ], ), @@ -370,7 +370,7 @@ public fun ByteArray.encodeBase32ToByteArray(base32: Base32.Default = Base32.Def replaceWith = ReplaceWith( expression = "this.encodeToByteArray(Base32Hex())", imports = [ - "io.matthewnelson.encoding.builders.Base32Hex", + "io.matthewnelson.encoding.base32.Base32Hex", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray", ], ), @@ -385,7 +385,7 @@ public fun ByteArray.encodeBase32ToByteArray(base32: Base32.Hex): ByteArray { replaceWith = ReplaceWith( expression = "this.encodeToByteArray(Base32Crockford { checkSymbol('value') })", imports = [ - "io.matthewnelson.encoding.builders.Base32Crockford", + "io.matthewnelson.encoding.base32.Base32Crockford", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray", ], ), diff --git a/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Base32.kt b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Base32.kt index 3b68627..e394ff3 100644 --- a/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Base32.kt +++ b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Base32.kt @@ -21,7 +21,6 @@ import io.matthewnelson.encoding.base32.internal.decodeOutMaxSize import io.matthewnelson.encoding.base32.internal.encodeOutSize import io.matthewnelson.encoding.base32.internal.isCheckSymbol import io.matthewnelson.encoding.base32.internal.toBits -import io.matthewnelson.encoding.builders.* import io.matthewnelson.encoding.core.* import io.matthewnelson.encoding.core.util.* import io.matthewnelson.encoding.core.util.FeedBuffer diff --git a/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Builders.kt b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Builders.kt new file mode 100644 index 0000000..ef82cd3 --- /dev/null +++ b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/base32/Builders.kt @@ -0,0 +1,490 @@ +/* + * Copyright (c) 2023 Matthew Nelson + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + **/ +@file:Suppress("FunctionName", "SpellCheckingInspection") + +package io.matthewnelson.encoding.base32 + +import io.matthewnelson.encoding.base32.internal.isCheckSymbol +import io.matthewnelson.encoding.core.EncodingException +import io.matthewnelson.encoding.core.Encoder +import kotlin.jvm.JvmField +import kotlin.jvm.JvmName +import kotlin.jvm.JvmOverloads + +/** + * Creates a configured [Base32.Crockford] encoder/decoder. + * + * @param [config] inherit settings from. + * @see [Base32CrockfordConfigBuilder] + * */ +public fun Base32Crockford( + config: Base32.Crockford.Config?, + block: Base32CrockfordConfigBuilder.() -> Unit, +): Base32.Crockford { + val builder = Base32CrockfordConfigBuilder(config) + block.invoke(builder) + return Base32.Crockford(builder.build()) +} + +/** + * Creates a configured [Base32.Crockford] encoder/decoder. + * + * @see [Base32CrockfordConfigBuilder] + * */ +public fun Base32Crockford( + block: Base32CrockfordConfigBuilder.() -> Unit, +): Base32.Crockford { + return Base32Crockford(config = null, block) +} + +/** + * Creates a configured [Base32.Crockford] encoder/decoder + * using the default settings. + * + * @param [strict] If true, configures the encoder/decoder + * to be in strict accordance with the Crockford spec. + * @see [Base32CrockfordConfigBuilder] + * */ +@JvmOverloads +public fun Base32Crockford(strict: Boolean = false): Base32.Crockford = Base32Crockford { if (strict) strict() } + +/** + * Creates a configured [Base32.Default] encoder/decoder. + * + * @param [config] to inherit from. + * @see [Base32DefaultConfigBuilder] + * */ +public fun Base32Default( + config: Base32.Default.Config?, + block: Base32DefaultConfigBuilder.() -> Unit, +): Base32.Default { + val builder = Base32DefaultConfigBuilder(config) + block.invoke(builder) + return Base32.Default(builder.build()) +} + +/** + * Creates a configured [Base32.Default] encoder/decoder. + * + * @see [Base32DefaultConfigBuilder] + * */ +public fun Base32Default( + block: Base32DefaultConfigBuilder.() -> Unit, +): Base32.Default { + return Base32Default(config = null, block) +} + +/** + * Creates a configured [Base32.Default] encoder/decoder + * using the default settings. + * + * @param [strict] If true, configures the encoder/decoder + * to be in strict accordance with RFC 4648. + * @see [Base32DefaultConfigBuilder] + * */ +@JvmOverloads +public fun Base32Default(strict: Boolean = false): Base32.Default = Base32Default { if (strict) strict() } + +/** + * Creates a configured [Base32.Hex] encoder/decoder. + * + * @param [config] to inherit from. + * @see [Base32HexConfigBuilder] + * */ +public fun Base32Hex( + config: Base32.Hex.Config?, + block: Base32HexConfigBuilder.() -> Unit, +): Base32.Hex { + val builder = Base32HexConfigBuilder(config) + block.invoke(builder) + return Base32.Hex(builder.build()) +} + +/** + * Creates a configured [Base32.Hex] encoder/decoder. + * + * @see [Base32HexConfigBuilder] + * */ +public fun Base32Hex( + block: Base32HexConfigBuilder.() -> Unit, +): Base32.Hex { + return Base32Hex(config = null, block) +} + +/** + * Creates a configured [Base32.Hex] encoder/decoder + * using the default settings. + * + * @param [strict] If true, configures the encoder/decoder + * to be in strict accordance with RFC 4648. + * @see [Base32HexConfigBuilder] + * */ +@JvmOverloads +public fun Base32Hex(strict: Boolean = false): Base32.Hex = Base32Hex { if (strict) strict() } + +/** + * Builder for creating a [Base32.Crockford.Config]. + * + * @see [strict] + * @see [Base32Crockford] + * */ +public class Base32CrockfordConfigBuilder { + + public constructor() + public constructor(config: Base32.Crockford.Config?): this() { + if (config == null) return + isLenient = config.isLenient ?: true + encodeToLowercase = config.encodeToLowercase + hyphenInterval = config.hyphenInterval + checkSymbol = config.checkSymbol + finalizeWhenFlushed = config.finalizeWhenFlushed + } + + /** + * If true, spaces and new lines ('\n', '\r', ' ', '\t') + * will be skipped over when decoding (against Crockford spec). + * + * If false, an [EncodingException] will be thrown if + * those characters are encountered when decoding. + * */ + @JvmField + public var isLenient: Boolean = true + + /** + * If true, will output lowercase characters when + * encoding (against Crockford spec). + * + * If false, will output uppercase characters when + * encoding. + * */ + @JvmField + public var encodeToLowercase: Boolean = false + + /** + * For every [hyphenInterval] of encoded output, a + * hyphen ("-") will be inserted. + * + * e.g. + * + * hyphenInterval = 0 + * // 91JPRV3F41BPYWKCCGGG + * + * hyphenInterval = 5 + * // 91JPR-V3F41-BPYWK-CCGGG + * + * hyphenInterval = 4 + * // 91JP-RV3F-41BP-YWKC-CGGG + * + * Enable by setting to a value between 1 and 127. + * */ + @JvmField + public var hyphenInterval: Byte = 0 + + @get:JvmName("checkSymbol") + public var checkSymbol: Char? = null + private set + + /** + * Specify an optional check symbol to be appended to the encoded + * output, and verified when decoding (fail quickly). + * + * Valid check symbols are: + * - '*', '~', '$', '=', 'U', 'u' + * - or null to omit + * + * @throws [IllegalArgumentException] If not a valid check symbol. + * */ + @Throws(IllegalArgumentException::class) + public fun checkSymbol(symbol: Char?): Base32CrockfordConfigBuilder { + when { + symbol == null || symbol.isCheckSymbol() -> { + checkSymbol = symbol + } + else -> { + throw IllegalArgumentException( + "CheckSymbol[$symbol] not recognized.\n" + + "Must be one of the following characters: *, ~, \$, =, U, u\n" + + "OR null to omit" + ) + } + } + + return this + } + + /** + * If true, whenever [Encoder.Feed.flush] is invoked: + * - The [checkSymbol] will be appended. + * - The counter for [hyphenInterval] insertion will be reset. + * + * If false + * - Appendage of the [checkSymbol] will only occur when + * [Encoder.Feed.doFinal] is invoked. + * - The counter for [hyphenInterval] insertion will not be reset. + * + * If neither [checkSymbol] or [hyphenInterval] are set, this has + * no effect when encoding. + * + * e.g. + * + * // WHEN FALSE + * val sb = StringBuilder() + * Base32Crockford { + * hyphenInterval = 4 + * checkSymbol('*') + * finalizeWhenFlushed = false + * }.newEncoderFeed { encodedChar -> + * sb.append(encodedChar) + * }.use { feed -> + * bytes1.forEach { b -> feed.consume(b) } + * feed.flush() + * bytes2.forEach { b -> feed.consume(b) } + * } + * + * println(sb.toString()) + * // 91JP-RV3F-41BP-YWKC-CGGG-* + * + * // WHEN TRUE + * val sb = StringBuilder() + * Base32Crockford { + * hyphenInterval = 4 + * checkSymbol('*') + * finalizeWhenFlushed = true + * }.newEncoderFeed { encodedChar -> + * sb.append(encodedChar) + * }.use { feed -> + * bytes1.forEach { b -> feed.consume(b) } + * feed.flush() + * + * // Could do something here like insert a line + * // break. It has its use cases. + * + * bytes2.forEach { b -> feed.consume(b) } + * } + * + * println(sb.toString()) + * // 91JP-RV3F-*41BP-YWKC-CGGG-* + * + * */ + @JvmField + public var finalizeWhenFlushed: Boolean = false + + /** + * A shortcut for configuring things to be in strict + * adherence with the Crockford spec. + * */ + public fun strict(): Base32CrockfordConfigBuilder { + isLenient = false + encodeToLowercase = false + finalizeWhenFlushed = false + return this + } + + /** + * Builds a [Base32.Crockford.Config] for the provided settings. + * */ + public fun build(): Base32.Crockford.Config = Base32.Crockford.Config.from(this) +} + +/** + * Builder for creating a [Base32.Default.Config]. + * + * @see [strict] + * @see [Base32Default] + * */ +public class Base32DefaultConfigBuilder { + + public constructor() + public constructor(config: Base32.Default.Config?): this() { + if (config == null) return + isLenient = config.isLenient ?: true + lineBreakInterval = config.lineBreakInterval + encodeToLowercase = config.encodeToLowercase + padEncoded = config.padEncoded + } + + /** + * If true, spaces and new lines ('\n', '\r', ' ', '\t') + * will be skipped over when decoding (against RFC 4648). + * + * If false, an [EncodingException] will be thrown if + * those characters are encountered when decoding. + * */ + @JvmField + public var isLenient: Boolean = true + + /** + * For every [lineBreakInterval] of encoded data, a + * line break will be output. + * + * Will **ONLY** output line breaks if [isLenient] is + * set to **true**. + * + * e.g. + * + * isLenient = true + * lineBreakInterval = 0 + * // JBSWY3DPEBLW64TMMQQQ==== + * + * isLenient = true + * lineBreakInterval = 16 + * // JBSWY3DPEBLW64TM + * // MQQQ==== + * + * isLenient = false + * lineBreakInterval = 16 + * // JBSWY3DPEBLW64TMMQQQ==== + * + * Enable by setting to a value between 1 and 127, and + * setting [isLenient] to true. + * + * A great value is 64 + * */ + @JvmField + public var lineBreakInterval: Byte = 0 + + /** + * If true, will output lowercase characters when + * encoding (against RFC 4648). + * + * If false, will output uppercase characters when + * encoding. + * */ + @JvmField + public var encodeToLowercase: Boolean = false + + /** + * If true, padding **WILL** be applied to the encoded + * output. + * + * If false, padding **WILL NOT** be applied to the + * encoded output (against RFC 4648). + * */ + @JvmField + public var padEncoded: Boolean = true + + /** + * A shortcut for configuring things to be in strict + * adherence with RFC 4648. + * */ + public fun strict(): Base32DefaultConfigBuilder { + isLenient = false + lineBreakInterval = 0 + encodeToLowercase = false + padEncoded = true + return this + } + + /** + * Builds a [Base32.Default.Config] for the provided settings. + * */ + public fun build(): Base32.Default.Config = Base32.Default.Config.from(this) +} + +/** + * Builder for creating a [Base32.Hex.Config]. + * + * @see [strict] + * @see [Base32Hex] + * */ +public class Base32HexConfigBuilder { + + public constructor() + public constructor(config: Base32.Hex.Config?): this() { + if (config == null) return + isLenient = config.isLenient ?: true + lineBreakInterval = config.lineBreakInterval + encodeToLowercase = config.encodeToLowercase + padEncoded = config.padEncoded + } + + /** + * If true, spaces and new lines ('\n', '\r', ' ', '\t') + * will be skipped over when decoding (against RFC 4648). + * + * If false, an [EncodingException] will be thrown if + * those characters are encountered when decoding. + * */ + @JvmField + public var isLenient: Boolean = true + + /** + * For every [lineBreakInterval] of encoded data, a + * line break will be output. + * + * Will **ONLY** output line breaks if [isLenient] is + * set to **true**. + * + * e.g. + * + * isLenient = true + * lineBreakInterval = 0 + * // 91IMOR3F41BMUSJCCGGG==== + * + * isLenient = true + * lineBreakInterval = 16 + * // 91IMOR3F41BMUSJC + * // CGGG==== + * + * isLenient = false + * lineBreakInterval = 16 + * // 91IMOR3F41BMUSJCCGGG==== + * + * Enable by setting to a value between 1 and 127, and + * setting [isLenient] to true. + * + * A great value is 64 + * */ + @JvmField + public var lineBreakInterval: Byte = 0 + + /** + * If true, will output lowercase characters when + * encoding (against RFC 4648). + * + * If false, will output uppercase characters when + * encoding. + * */ + @JvmField + public var encodeToLowercase: Boolean = false + + /** + * If true, padding **WILL** be applied to the encoded + * output. + * + * If false, padding **WILL NOT** be applied to the + * encoded output (against RFC 4648). + * */ + @JvmField + public var padEncoded: Boolean = true + + /** + * A shortcut for configuring things to be in strict + * adherence with RFC 4648. + * */ + public fun strict(): Base32HexConfigBuilder { + isLenient = false + lineBreakInterval = 0 + encodeToLowercase = false + padEncoded = true + return this + } + + /** + * Builds a [Base32.Hex.Config] for the provided settings. + * */ + public fun build(): Base32.Hex.Config = Base32.Hex.Config.from(this) +} diff --git a/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base32.kt b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base32.kt index 8bc117d..1b6418a 100644 --- a/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base32.kt +++ b/library/encoding-base32/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base32.kt @@ -13,7 +13,7 @@ * See the License for the specific language governing permissions and * limitations under the License. **/ -@file:Suppress("FunctionName", "SpellCheckingInspection") +@file:Suppress("FunctionName", "SpellCheckingInspection", "DEPRECATION") package io.matthewnelson.encoding.builders @@ -26,11 +26,27 @@ import kotlin.jvm.JvmName import kotlin.jvm.JvmOverloads /** - * Creates a configured [Base32.Crockford] encoder/decoder. + * Deprecated * - * @param [config] inherit settings from. - * @see [Base32CrockfordConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Crockford] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """ + , + replaceWith = ReplaceWith( + expression = "Base32Crockford(config) { block() }", + imports = [ + "io.matthewnelson.encoding.base32.Base32Crockford" + ] + ) +) public fun Base32Crockford( config: Base32.Crockford.Config?, block: Base32CrockfordConfigBuilder.() -> Unit, @@ -41,10 +57,26 @@ public fun Base32Crockford( } /** - * Creates a configured [Base32.Crockford] encoder/decoder. + * Deprecated * - * @see [Base32CrockfordConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Crockford] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Crockford { block() }", + imports = [ + "io.matthewnelson.encoding.base32.Base32Crockford" + ] + ) +) public fun Base32Crockford( block: Base32CrockfordConfigBuilder.() -> Unit, ): Base32.Crockford { @@ -52,22 +84,50 @@ public fun Base32Crockford( } /** - * Creates a configured [Base32.Crockford] encoder/decoder - * using the default settings. + * Deprecated * - * @param [strict] If true, configures the encoder/decoder - * to be in strict accordance with the Crockford spec. - * @see [Base32CrockfordConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Crockford] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Crockford(strict)", + imports = [ + "io.matthewnelson.encoding.base32.Base32Crockford" + ] + ) +) @JvmOverloads public fun Base32Crockford(strict: Boolean = false): Base32.Crockford = Base32Crockford { if (strict) strict() } /** - * Creates a configured [Base32.Default] encoder/decoder. + * Deprecated * - * @param [config] to inherit from. - * @see [Base32DefaultConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Default] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Default(config) { block() }", + imports = [ + "io.matthewnelson.encoding.base32.Base32Default" + ] + ) +) public fun Base32Default( config: Base32.Default.Config?, block: Base32DefaultConfigBuilder.() -> Unit, @@ -78,10 +138,26 @@ public fun Base32Default( } /** - * Creates a configured [Base32.Default] encoder/decoder. + * Deprecated * - * @see [Base32DefaultConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Default] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Default { block() }", + imports = [ + "io.matthewnelson.encoding.base32.Base32Default" + ] + ) +) public fun Base32Default( block: Base32DefaultConfigBuilder.() -> Unit, ): Base32.Default { @@ -89,22 +165,50 @@ public fun Base32Default( } /** - * Creates a configured [Base32.Default] encoder/decoder - * using the default settings. + * Deprecated * - * @param [strict] If true, configures the encoder/decoder - * to be in strict accordance with RFC 4648. - * @see [Base32DefaultConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Default] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Default(strict)", + imports = [ + "io.matthewnelson.encoding.base32.Base32Default" + ] + ) +) @JvmOverloads public fun Base32Default(strict: Boolean = false): Base32.Default = Base32Default { if (strict) strict() } /** - * Creates a configured [Base32.Hex] encoder/decoder. + * Deprecated * - * @param [config] to inherit from. - * @see [Base32HexConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Hex] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Hex(config) { block() }", + imports = [ + "io.matthewnelson.encoding.base32.Base32Hex" + ] + ) +) public fun Base32Hex( config: Base32.Hex.Config?, block: Base32HexConfigBuilder.() -> Unit, @@ -115,10 +219,26 @@ public fun Base32Hex( } /** - * Creates a configured [Base32.Hex] encoder/decoder. + * Deprecated * - * @see [Base32HexConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Hex] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Hex { block() }", + imports = [ + "io.matthewnelson.encoding.base32.Base32Hex" + ] + ) +) public fun Base32Hex( block: Base32HexConfigBuilder.() -> Unit, ): Base32.Hex { @@ -126,22 +246,50 @@ public fun Base32Hex( } /** - * Creates a configured [Base32.Hex] encoder/decoder - * using the default settings. + * Deprecated * - * @param [strict] If true, configures the encoder/decoder - * to be in strict accordance with RFC 4648. - * @see [Base32HexConfigBuilder] + * @see [io.matthewnelson.encoding.base32.Base32Hex] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32Hex(strict)", + imports = [ + "io.matthewnelson.encoding.base32.Base32Hex" + ] + ) +) @JvmOverloads public fun Base32Hex(strict: Boolean = false): Base32.Hex = Base32Hex { if (strict) strict() } /** - * Builder for creating a [Base32.Crockford.Config]. + * Deprecated * - * @see [strict] - * @see [Base32Crockford] + * @see [io.matthewnelson.encoding.base32.Base32CrockfordConfigBuilder] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32CrockfordConfigBuilder", + imports = [ + "io.matthewnelson.encoding.base32.Base32CrockfordConfigBuilder" + ] + ) +) public class Base32CrockfordConfigBuilder { public constructor() @@ -297,15 +445,38 @@ public class Base32CrockfordConfigBuilder { /** * Builds a [Base32.Crockford.Config] for the provided settings. * */ - public fun build(): Base32.Crockford.Config = Base32.Crockford.Config.from(this) + public fun build(): Base32.Crockford.Config { + val b = io.matthewnelson.encoding.base32.Base32CrockfordConfigBuilder() + b.isLenient = isLenient + b.encodeToLowercase = encodeToLowercase + b.hyphenInterval = hyphenInterval + b.checkSymbol(checkSymbol) + b.finalizeWhenFlushed = finalizeWhenFlushed + return b.build() + } } /** - * Builder for creating a [Base32.Default.Config]. + * Deprecated * - * @see [strict] - * @see [Base32Default] + * @see [io.matthewnelson.encoding.base32.Base32DefaultConfigBuilder] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32DefaultConfigBuilder", + imports = [ + "io.matthewnelson.encoding.base32.Base32DefaultConfigBuilder" + ] + ) +) public class Base32DefaultConfigBuilder { public constructor() @@ -392,15 +563,37 @@ public class Base32DefaultConfigBuilder { /** * Builds a [Base32.Default.Config] for the provided settings. * */ - public fun build(): Base32.Default.Config = Base32.Default.Config.from(this) + public fun build(): Base32.Default.Config { + val b = io.matthewnelson.encoding.base32.Base32DefaultConfigBuilder() + b.isLenient = isLenient + b.lineBreakInterval = lineBreakInterval + b.encodeToLowercase = encodeToLowercase + b.padEncoded = padEncoded + return b.build() + } } /** - * Builder for creating a [Base32.Hex.Config]. + * Deprecated * - * @see [strict] - * @see [Base32Hex] + * @see [io.matthewnelson.encoding.base32.Base32HexConfigBuilder] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base32 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base32HexConfigBuilder", + imports = [ + "io.matthewnelson.encoding.base32.Base32HexConfigBuilder" + ] + ) +) public class Base32HexConfigBuilder { public constructor() @@ -487,5 +680,12 @@ public class Base32HexConfigBuilder { /** * Builds a [Base32.Hex.Config] for the provided settings. * */ - public fun build(): Base32.Hex.Config = Base32.Hex.Config.from(this) + public fun build(): Base32.Hex.Config { + val b = io.matthewnelson.encoding.base32.Base32HexConfigBuilder() + b.isLenient = isLenient + b.lineBreakInterval = lineBreakInterval + b.encodeToLowercase = encodeToLowercase + b.padEncoded = padEncoded + return b.build() + } } diff --git a/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32CrockfordUnitTest.kt b/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32CrockfordUnitTest.kt index f521200..eb66049 100644 --- a/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32CrockfordUnitTest.kt +++ b/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32CrockfordUnitTest.kt @@ -17,7 +17,6 @@ package io.matthewnelson.encoding.base32 -import io.matthewnelson.encoding.builders.Base32Crockford import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArray import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString diff --git a/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32DefaultUnitTest.kt b/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32DefaultUnitTest.kt index c766f79..109fca9 100644 --- a/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32DefaultUnitTest.kt +++ b/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32DefaultUnitTest.kt @@ -17,7 +17,6 @@ package io.matthewnelson.encoding.base32 -import io.matthewnelson.encoding.builders.Base32Default import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArray import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString diff --git a/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32HexUnitTest.kt b/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32HexUnitTest.kt index 092c53a..6b84848 100644 --- a/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32HexUnitTest.kt +++ b/library/encoding-base32/src/commonTest/kotlin/io/matthewnelson/encoding/base32/Base32HexUnitTest.kt @@ -17,7 +17,6 @@ package io.matthewnelson.encoding.base32 -import io.matthewnelson.encoding.builders.Base32Hex import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArray import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString diff --git a/library/encoding-base64/api/encoding-base64.api b/library/encoding-base64/api/encoding-base64.api index e46b18e..47f7826 100644 --- a/library/encoding-base64/api/encoding-base64.api +++ b/library/encoding-base64/api/encoding-base64.api @@ -61,6 +61,25 @@ public final class io/matthewnelson/encoding/base64/Base64$UrlSafe : io/matthewn public static final field INSTANCE Lio/matthewnelson/encoding/base64/Base64$UrlSafe; } +public final class io/matthewnelson/encoding/base64/Base64ConfigBuilder { + public field encodeToUrlSafe Z + public field isLenient Z + public field lineBreakInterval B + public field padEncoded Z + public fun ()V + public fun (Lio/matthewnelson/encoding/base64/Base64$Config;)V + public final fun build ()Lio/matthewnelson/encoding/base64/Base64$Config; + public final fun strict ()Lio/matthewnelson/encoding/base64/Base64ConfigBuilder; +} + +public final class io/matthewnelson/encoding/base64/BuildersKt { + public static final fun Base64 ()Lio/matthewnelson/encoding/base64/Base64; + public static final fun Base64 (Lio/matthewnelson/encoding/base64/Base64$Config;Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base64/Base64; + public static final fun Base64 (Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base64/Base64; + public static final fun Base64 (Z)Lio/matthewnelson/encoding/base64/Base64; + public static synthetic fun Base64$default (ZILjava/lang/Object;)Lio/matthewnelson/encoding/base64/Base64; +} + public final class io/matthewnelson/encoding/builders/Base64BuildersKt { public static final fun Base64 ()Lio/matthewnelson/encoding/base64/Base64; public static final fun Base64 (Lio/matthewnelson/encoding/base64/Base64$Config;Lkotlin/jvm/functions/Function1;)Lio/matthewnelson/encoding/base64/Base64; diff --git a/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/component/base64/Base64.kt b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/component/base64/Base64.kt index de6fecc..ed651b8 100644 --- a/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/component/base64/Base64.kt +++ b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/component/base64/Base64.kt @@ -34,7 +34,6 @@ package io.matthewnelson.component.base64 -import io.matthewnelson.encoding.builders.Base64 import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray import io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray @@ -118,7 +117,7 @@ public sealed class Base64 { replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base64())", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), @@ -126,7 +125,7 @@ public sealed class Base64 { ) @Suppress("NOTHING_TO_INLINE") public inline fun String.decodeBase64ToArray(): ByteArray? { - return decodeToByteArrayOrNull(Base64()) + return decodeToByteArrayOrNull(io.matthewnelson.encoding.base64.Base64()) } @Deprecated( @@ -134,14 +133,14 @@ public inline fun String.decodeBase64ToArray(): ByteArray? { replaceWith = ReplaceWith( expression = "this.decodeToByteArrayOrNull(Base64())", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull", ], ), level = DeprecationLevel.WARNING, ) public fun CharArray.decodeBase64ToArray(): ByteArray? { - return decodeToByteArrayOrNull(Base64()) + return decodeToByteArrayOrNull(io.matthewnelson.encoding.base64.Base64()) } @Deprecated( @@ -149,7 +148,7 @@ public fun CharArray.decodeBase64ToArray(): ByteArray? { replaceWith = ReplaceWith( expression = "this.encodeToString(Base64())", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToString", ], ), @@ -158,7 +157,7 @@ public fun CharArray.decodeBase64ToArray(): ByteArray? { @JvmOverloads @Suppress("NOTHING_TO_INLINE") public inline fun ByteArray.encodeBase64(base64: Base64.Default = Base64.Default): String { - return encodeToString(Base64()) + return encodeToString(io.matthewnelson.encoding.base64.Base64()) } @Deprecated( @@ -166,7 +165,7 @@ public inline fun ByteArray.encodeBase64(base64: Base64.Default = Base64.Default replaceWith = ReplaceWith( expression = "this.encodeToString(Base64 { encodeToUrlSafe = true; padEncoded = true/false })", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToString", ], ), @@ -174,7 +173,7 @@ public inline fun ByteArray.encodeBase64(base64: Base64.Default = Base64.Default ) @Suppress("NOTHING_TO_INLINE") public inline fun ByteArray.encodeBase64(base64: Base64.UrlSafe): String { - return encodeToString(Base64 { + return encodeToString(io.matthewnelson.encoding.base64.Base64 { encodeToUrlSafe = true padEncoded = base64.pad }) @@ -185,7 +184,7 @@ public inline fun ByteArray.encodeBase64(base64: Base64.UrlSafe): String { replaceWith = ReplaceWith( expression = "this.encodeToCharArray(Base64())", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray", ], ), @@ -194,7 +193,7 @@ public inline fun ByteArray.encodeBase64(base64: Base64.UrlSafe): String { @JvmOverloads @Suppress("NOTHING_TO_INLINE") public inline fun ByteArray.encodeBase64ToCharArray(base64: Base64.Default = Base64.Default): CharArray { - return encodeToCharArray(Base64()) + return encodeToCharArray(io.matthewnelson.encoding.base64.Base64()) } @Deprecated( @@ -202,7 +201,7 @@ public inline fun ByteArray.encodeBase64ToCharArray(base64: Base64.Default = Bas replaceWith = ReplaceWith( expression = "this.encodeToCharArray(Base64 { encodeToUrlSafe = true; padEncoded = true/false })", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToCharArray", ], ), @@ -210,7 +209,7 @@ public inline fun ByteArray.encodeBase64ToCharArray(base64: Base64.Default = Bas ) @Suppress("NOTHING_TO_INLINE") public inline fun ByteArray.encodeBase64ToCharArray(base64: Base64.UrlSafe): CharArray { - return encodeToCharArray(Base64 { + return encodeToCharArray(io.matthewnelson.encoding.base64.Base64 { encodeToUrlSafe = true padEncoded = base64.pad }) @@ -221,7 +220,7 @@ public inline fun ByteArray.encodeBase64ToCharArray(base64: Base64.UrlSafe): Cha replaceWith = ReplaceWith( expression = "this.encodeToByteArray(Base64())", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray", ], ), @@ -229,7 +228,7 @@ public inline fun ByteArray.encodeBase64ToCharArray(base64: Base64.UrlSafe): Cha ) @JvmOverloads public fun ByteArray.encodeBase64ToByteArray(base64: Base64.Default = Base64.Default): ByteArray { - return encodeToByteArray(Base64()) + return encodeToByteArray(io.matthewnelson.encoding.base64.Base64()) } @Deprecated( @@ -237,14 +236,14 @@ public fun ByteArray.encodeBase64ToByteArray(base64: Base64.Default = Base64.Def replaceWith = ReplaceWith( expression = "this.encodeToByteArray(Base64 { encodeToUrlSafe = true; padEncoded = true/false })", imports = [ - "io.matthewnelson.encoding.builders.Base64", + "io.matthewnelson.encoding.base64.Base64", "io.matthewnelson.encoding.core.Encoder.Companion.encodeToByteArray", ], ), level = DeprecationLevel.WARNING, ) public fun ByteArray.encodeBase64ToByteArray(base64: Base64.UrlSafe): ByteArray { - return encodeToByteArray(Base64 { + return encodeToByteArray(io.matthewnelson.encoding.base64.Base64 { encodeToUrlSafe = true padEncoded = base64.pad }) diff --git a/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Base64.kt b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Base64.kt index daa90e2..ddf903f 100644 --- a/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Base64.kt +++ b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Base64.kt @@ -17,9 +17,6 @@ package io.matthewnelson.encoding.base64 -import io.matthewnelson.encoding.base64.Base64.Default -import io.matthewnelson.encoding.builders.Base64 -import io.matthewnelson.encoding.builders.Base64ConfigBuilder import io.matthewnelson.encoding.core.* import io.matthewnelson.encoding.core.util.DecoderInput import io.matthewnelson.encoding.core.util.FeedBuffer @@ -55,7 +52,7 @@ import kotlin.jvm.JvmSynthetic * val decoded = encoded.decodeToByteArray(Base64.Default).decodeToString() * assertEquals(text, decoded) * - * @see [io.matthewnelson.encoding.builders.Base64] + * @see [io.matthewnelson.encoding.base64.Base64] * @see [Base64.Config] * @see [Default.CHARS] * @see [UrlSafe.CHARS] diff --git a/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Builders.kt b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Builders.kt new file mode 100644 index 0000000..d8f647d --- /dev/null +++ b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/base64/Builders.kt @@ -0,0 +1,147 @@ +/* + * Copyright (c) 2023 Matthew Nelson + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + **/ +package io.matthewnelson.encoding.base64 + +import io.matthewnelson.encoding.core.EncodingException +import kotlin.jvm.JvmField +import kotlin.jvm.JvmOverloads + +/** + * Creates a configured [Base64] encoder/decoder. + * + * @param [config] inherit settings from. + * @see [Base64ConfigBuilder] + * */ +public fun Base64( + config: Base64.Config?, + block: Base64ConfigBuilder.() -> Unit, +): Base64 { + val builder = Base64ConfigBuilder(config) + block.invoke(builder) + return Base64(builder.build()) +} + +/** + * Creates a configured [Base64] encoder/decoder. + * + * @see [Base64ConfigBuilder] + * */ +public fun Base64( + block: Base64ConfigBuilder.() -> Unit, +): Base64 { + return Base64(null, block) +} + +/** + * Creates a configured [Base64] encoder/decoder + * using the default settings. + * + * @param [strict] If true, configures the encoder/decoder + * to be in strict accordance with RFC 4648. + * @see [Base64ConfigBuilder] + * */ +@JvmOverloads +public fun Base64(strict: Boolean = false): Base64 = Base64 { if (strict) strict() } + +/** + * Builder for creating a [Base64.Config]. + * + * @see [strict] + * @see [io.matthewnelson.encoding.builders.Base64] + * */ +public class Base64ConfigBuilder { + + public constructor() + public constructor(config: Base64.Config?): this() { + if (config == null) return + isLenient = config.isLenient ?: true + lineBreakInterval = config.lineBreakInterval + encodeToUrlSafe = config.encodeToUrlSafe + padEncoded = config.padEncoded + } + + /** + * If true, spaces and new lines ('\n', '\r', ' ', '\t') + * will be skipped over when decoding (against RFC 4648). + * + * If false, an [EncodingException] will be thrown if + * those characters are encountered when decoding. + * */ + @JvmField + public var isLenient: Boolean = true + + /** + * For every [lineBreakInterval] of encoded data, a + * line break will be output. + * + * Will **ONLY** output line breaks if [isLenient] is + * set to **true**. + * + * e.g. + * + * isLenient = true + * lineBreakInterval = 0 + * // SGVsbG8gV29ybGQh + * + * isLenient = true + * lineBreakInterval = 10 + * // SGVsbG8gV2 + * // 9ybGQh + * + * isLenient = false + * lineBreakInterval = 10 + * // SGVsbG8gV29ybGQh + * + * Enable by setting to a value between 1 and 127, and + * setting [isLenient] to true. + * + * A great value is 64 + * */ + @JvmField + public var lineBreakInterval: Byte = 0 + + /** + * If true, will output Base64 UrlSafe characters + * when encoding. + * + * If false, will output Base64 Default characters + * when encoding. + * */ + @JvmField + public var encodeToUrlSafe: Boolean = false + + /** + * If true, padding **WILL** be applied to the encoded + * output. + * + * If false, padding **WILL NOT** be applied to the + * encoded output (against RFC 4648). + * */ + @JvmField + public var padEncoded: Boolean = true + + /** + * A shortcut for configuring things to be in strict + * adherence with RFC 4648. + * */ + public fun strict(): Base64ConfigBuilder { + isLenient = false + padEncoded = true + return this + } + + public fun build(): Base64.Config = Base64.Config.from(this) +} diff --git a/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base64Builders.kt b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base64Builders.kt index 171e8d3..7be8030 100644 --- a/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base64Builders.kt +++ b/library/encoding-base64/src/commonMain/kotlin/io/matthewnelson/encoding/builders/Base64Builders.kt @@ -13,6 +13,8 @@ * See the License for the specific language governing permissions and * limitations under the License. **/ +@file:Suppress("DEPRECATION") + package io.matthewnelson.encoding.builders import io.matthewnelson.encoding.base64.Base64 @@ -21,11 +23,26 @@ import kotlin.jvm.JvmField import kotlin.jvm.JvmOverloads /** - * Creates a configured [Base64] encoder/decoder. + * Deprecated * - * @param [config] inherit settings from. - * @see [Base64ConfigBuilder] + * @see [io.matthewnelson.encoding.base64.Base64] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base64 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base64(config) { block() }", + imports = [ + "io.matthewnelson.encoding.base64.Base64" + ] + ) +) public fun Base64( config: Base64.Config?, block: Base64ConfigBuilder.() -> Unit, @@ -36,10 +53,26 @@ public fun Base64( } /** - * Creates a configured [Base64] encoder/decoder. + * Deprecated * - * @see [Base64ConfigBuilder] + * @see [io.matthewnelson.encoding.base64.Base64] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base64 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base64 { block() }", + imports = [ + "io.matthewnelson.encoding.base64.Base64" + ] + ) +) public fun Base64( block: Base64ConfigBuilder.() -> Unit, ): Base64 { @@ -47,22 +80,50 @@ public fun Base64( } /** - * Creates a configured [Base64] encoder/decoder - * using the default settings. + * Deprecated * - * @param [strict] If true, configures the encoder/decoder - * to be in strict accordance with RFC 4648. - * @see [Base64ConfigBuilder] + * @see [io.matthewnelson.encoding.base64.Base64] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base64 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base64(strict)", + imports = [ + "io.matthewnelson.encoding.base64.Base64" + ] + ) +) @JvmOverloads public fun Base64(strict: Boolean = false): Base64 = Base64 { if (strict) strict() } /** - * Builder for creating a [Base64.Config]. + * Deprecated * - * @see [strict] - * @see [io.matthewnelson.encoding.builders.Base64] + * @see [io.matthewnelson.encoding.base64.Base64ConfigBuilder] * */ +@Deprecated( + message = """ + Moved to package io.matthewnelson.encoding.base64 + + Will be removed in 2.0.0 because of an issue with + Java 9 modules and JPMS not allowing split packages + + See: https://github.com/05nelsonm/encoding/blob/master/MIGRATION.md + """, + replaceWith = ReplaceWith( + expression = "Base64ConfigBuilder", + imports = [ + "io.matthewnelson.encoding.base64.Base64ConfigBuilder" + ] + ) +) public class Base64ConfigBuilder { public constructor() @@ -144,5 +205,12 @@ public class Base64ConfigBuilder { return this } - public fun build(): Base64.Config = Base64.Config.from(this) + public fun build(): Base64.Config { + val b = io.matthewnelson.encoding.base64.Base64ConfigBuilder() + b.isLenient = isLenient + b.lineBreakInterval = lineBreakInterval + b.encodeToUrlSafe = encodeToUrlSafe + b.padEncoded = padEncoded + return b.build() + } } diff --git a/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64DefaultUnitTest.kt b/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64DefaultUnitTest.kt index 1f2063f..ca6e042 100644 --- a/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64DefaultUnitTest.kt +++ b/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64DefaultUnitTest.kt @@ -17,7 +17,6 @@ package io.matthewnelson.encoding.base64 -import io.matthewnelson.encoding.builders.Base64 import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArray import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString diff --git a/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64UrlSafeUnitTest.kt b/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64UrlSafeUnitTest.kt index b971ede..33908f7 100644 --- a/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64UrlSafeUnitTest.kt +++ b/library/encoding-base64/src/commonTest/kotlin/io/matthewnelson/encoding/base64/Base64UrlSafeUnitTest.kt @@ -18,7 +18,6 @@ package io.matthewnelson.encoding.base64 import io.matthewnelson.encoding.test.BaseNEncodingTest -import io.matthewnelson.encoding.builders.Base64 import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArray import io.matthewnelson.encoding.core.Decoder.Companion.decodeToByteArrayOrNull import io.matthewnelson.encoding.core.Encoder.Companion.encodeToString