diff --git a/api/build.gradle.kts b/api/build.gradle.kts index af5896de..cfe98d56 100644 --- a/api/build.gradle.kts +++ b/api/build.gradle.kts @@ -7,7 +7,11 @@ publishing { publications { create("maven") { artifactId = "mappie-api" - from(components["kotlin"]) + from(components["java"]) } } +} + +java { + withSourcesJar() } \ No newline at end of file diff --git a/api/src/main/kotlin/io/github/mappie/api/EnumMapper.kt b/api/src/main/kotlin/io/github/mappie/api/EnumMapper.kt index f29de3f6..f35c3842 100644 --- a/api/src/main/kotlin/io/github/mappie/api/EnumMapper.kt +++ b/api/src/main/kotlin/io/github/mappie/api/EnumMapper.kt @@ -2,7 +2,31 @@ package io.github.mappie.api +/** + * Base class for enum mappers. See the [documentation](https://mr-mappie.github.io/mappie/enum-mapping/enum-mapping-overview/) + * for a complete overview of how to generate enum mappers. + * + * For example + * ```kotlin + * class PersonMapper : EnumMapper() { + * override fun map(from: Color) = mapping() + * } + * ``` + * will generate a mapper from `Color` to `Colour`, assuming both `Color` and `Colour` have a resolvable mapping. + * + * @param FROM the source type to map from. + * @param TO the target type to map to. + */ abstract class EnumMapper, TO : Enum<*>> : Mapper() { + /** + * Explicitly construct a mapping to [TO] from source entry [source]. + * + * For example + * ```kotlin + * Color.UNKNOWN mappedFromEnumEntry Color.ORANGE + * ``` + * will generate an explicit mapping, mapping `Color.ORANGE` to `Color.UNKNOWN`. + */ protected infix fun TO.mappedFromEnumEntry(source: FROM): EnumMapper = generated() } \ No newline at end of file diff --git a/api/src/main/kotlin/io/github/mappie/api/Mapper.kt b/api/src/main/kotlin/io/github/mappie/api/Mapper.kt index a0feb15a..4a20a27d 100644 --- a/api/src/main/kotlin/io/github/mappie/api/Mapper.kt +++ b/api/src/main/kotlin/io/github/mappie/api/Mapper.kt @@ -4,11 +4,29 @@ package io.github.mappie.api abstract class Mapper { + /** + * Map [from] to an instance of [TO]. + * + * @param from the source value. + * @return [from] mapped to an instance of [TO]. + */ abstract fun map(from: FROM): TO + /** + * Map each element in [from] to an instance of [TO]. + * + * @param from the source values. + * @return [from] mapped to a list of instances of [TO]. + */ fun mapList(from: List): List = ArrayList(from.size).apply { from.forEach { add(map(it)) } } + /** + * Mapping function which instructs Mappie to generate code for this implementation. + * + * @param builder the configuration for the generation of this mapping. + * @return An instance of the mapped value at runtime. + */ protected fun mapping(builder: Mapper.() -> Unit = { }): TO = generated() } diff --git a/api/src/main/kotlin/io/github/mappie/api/ObjectMapper.kt b/api/src/main/kotlin/io/github/mappie/api/ObjectMapper.kt index 4b271050..42e56ca8 100644 --- a/api/src/main/kotlin/io/github/mappie/api/ObjectMapper.kt +++ b/api/src/main/kotlin/io/github/mappie/api/ObjectMapper.kt @@ -4,27 +4,80 @@ package io.github.mappie.api import kotlin.reflect.KProperty1 -abstract class CollectionMapper : Mapper, List>() { - - abstract infix fun filteredBy(predicate: (FROM) -> Boolean): CollectionMapper -} +/** + * Base mapper class for list mappers. Cannot be instantiated, but can be created by using the field [ObjectMapper.forList]. + */ +sealed class ListMapper : Mapper, List>() +/** + * Base class for object mappers. See the [documentation](https://mr-mappie.github.io/mappie/object-mapping/object-mapping-overview/) + * for a complete overview of how to generate object mappers. + * + * For example + * ```kotlin + * class PersonMapper : ObjectMapper() { + * override fun map(from: PersonDto) = mapping() + * } + * ``` + * will generate a mapper from `PersonDto` to `Person`, assuming both `PersonDto` and `Person` have a resolvable mapping. + * + * @param FROM the source type to map from. + * @param TO the target type to map to. + */ abstract class ObjectMapper : Mapper() { - val forList: CollectionMapper get() = + /** + * A mapper for [List] to be used in [TransformableValue.via]. + */ + val forList: ListMapper get() = error("The mapper forList should only be used in the context of 'via'. Use mapList instead.") + /** + * Explicitly construct a mapping to [TO] from property source [source]. + * + * For example + * ```kotlin + * Person::name mappedFromProperty PersonDto::fullName + * ``` + * will generate an explicit mapping, setting constructor parameter `Person.name` to `PersonDto.fullName`. + */ protected infix fun KProperty1.mappedFromProperty(source: KProperty1): TransformableValue = generated() - protected infix fun KProperty1.mappedFromConstant(value: TO_TYPE): ObjectMapper = + /** + * Explicitly construct a mapping to [TO] from constant source [value]. + * + * For example + * ```kotlin + * Person::name mappedFromConstant "John Doe" + * ``` + * will generate an explicit mapping, setting constructor parameter `Person.name` to `"John Doe"`. + */ + protected infix fun KProperty1.mappedFromConstant(value: TO_TYPE): Unit = generated() - protected infix fun KProperty1.mappedFromExpression(function: (FROM) -> TO_TYPE): ObjectMapper = + /** + * Explicitly construct a mapping to [TO] from expression source [function]. + * + * For example + * ```kotlin + * Person::name mappedFromConstant { personDto -> personDto.fullName + " (full)" } + * ``` + * will generate an explicit mapping, setting constructor parameter `Person.name` to `"John Doe (full)"`, + * assuming `personDto.fullName == "John Doe"`. + */ + protected infix fun KProperty1.mappedFromExpression(function: (FROM) -> TO_TYPE): Unit = generated() + /** + * Reference a constructor parameter in lieu of a property reference, if it not exists as a property. + * + * For example + * ```kotlin + * parameter("name") mappedFromProperty PersonDto::fullName + * ``` + * will generate an explicit mapping, setting constructor parameter `name` to `PersonDto.fullName`. + */ protected fun parameter(name: String): KProperty1 = generated() - - protected fun result(source: TO): ObjectMapper = generated() } \ No newline at end of file diff --git a/api/src/main/kotlin/io/github/mappie/api/TransformableValue.kt b/api/src/main/kotlin/io/github/mappie/api/TransformableValue.kt index b5951dbd..17083401 100644 --- a/api/src/main/kotlin/io/github/mappie/api/TransformableValue.kt +++ b/api/src/main/kotlin/io/github/mappie/api/TransformableValue.kt @@ -1,6 +1,12 @@ package io.github.mappie.api +/** + * The result of an explicit mapping definition which can be transformed. + */ class TransformableValue { + /** + * + */ infix fun transform(function: (FROM) -> TO): Unit = generated() infix fun > via(clazz: M): M = generated() diff --git a/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/Identifiers.kt b/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/Identifiers.kt index f9ae5c8c..13fcf8cd 100644 --- a/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/Identifiers.kt +++ b/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/Identifiers.kt @@ -16,8 +16,6 @@ val IDENTIFIER_MAPPED_FROM_CONSTANT = Name.identifier("mappedFromConstant") val IDENTIFIER_MAPPED_FROM_EXPRESSION = Name.identifier("mappedFromExpression") -val IDENTIFIER_RESULT = Name.identifier("result") - val IDENTIFIER_PARAMETER = Name.identifier("parameter") val IDENTIFIER_TRANFORM = Name.identifier("transform") diff --git a/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/primitives/PrimitiveBodyCollector.kt b/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/primitives/PrimitiveBodyCollector.kt index 362bc8b7..629f413f 100644 --- a/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/primitives/PrimitiveBodyCollector.kt +++ b/compiler-plugin/src/main/kotlin/io/github/mappie/resolving/primitives/PrimitiveBodyCollector.kt @@ -2,7 +2,6 @@ package io.github.mappie.resolving.primitives import io.github.mappie.BaseVisitor import io.github.mappie.resolving.IDENTIFIER_MAPPING -import io.github.mappie.resolving.IDENTIFIER_RESULT import io.github.mappie.util.irGet import org.jetbrains.kotlin.ir.backend.js.utils.valueArguments import org.jetbrains.kotlin.ir.declarations.IrFunction @@ -26,9 +25,6 @@ class PrimitiveBodyCollector( expression.valueArguments.first()?.accept(data) ?: irGet(declaration.valueParameters.first()) } - IDENTIFIER_RESULT -> { - expression.valueArguments.first()!! - } else -> { super.visitCall(expression, data) } diff --git a/testing/src/main/kotlin/testing/ListMapper.kt b/testing/src/main/kotlin/testing/ListMapper.kt index 7fbad4c8..e1e6d74a 100644 --- a/testing/src/main/kotlin/testing/ListMapper.kt +++ b/testing/src/main/kotlin/testing/ListMapper.kt @@ -15,7 +15,5 @@ object BookMapper : ObjectMapper() { } object PageMapper : ObjectMapper() { - override fun map(from: Page): String = mapping { - result(from.text) - } + override fun map(from: Page): String = from.text } \ No newline at end of file diff --git a/testing/src/main/kotlin/testing/PrimitiveMapper.kt b/testing/src/main/kotlin/testing/PrimitiveMapper.kt index b6519135..6d95491d 100644 --- a/testing/src/main/kotlin/testing/PrimitiveMapper.kt +++ b/testing/src/main/kotlin/testing/PrimitiveMapper.kt @@ -4,14 +4,10 @@ import io.github.mappie.api.ObjectMapper object IntMapper : ObjectMapper() { - override fun map(from: Int) = mapping { - result(from.toString()) - } + override fun map(from: Int) = from.toString() } object StringMapper : ObjectMapper() { - override fun map(from: String) = mapping { - result(from.toInt()) - } + override fun map(from: String) = from.toInt() } diff --git a/website/src/posts/enum-mapping/posts/overview.md b/website/src/posts/enum-mapping/posts/overview.md index 96e1adda..1fa71b7c 100644 --- a/website/src/posts/enum-mapping/posts/overview.md +++ b/website/src/posts/enum-mapping/posts/overview.md @@ -4,7 +4,7 @@ summary: "Performing enum mapping." eleventyNavigation: key: Enum Mapping Overview parent: Enum Mapping - order: 8 + order: 9 --- Mappie supports mapping an enum class to another enum class. This can be achieved by implementing a mapper object which diff --git a/website/src/posts/object-mapping/posts/configuration.md b/website/src/posts/object-mapping/posts/configuration.md new file mode 100644 index 00000000..00592f61 --- /dev/null +++ b/website/src/posts/object-mapping/posts/configuration.md @@ -0,0 +1,8 @@ +--- +title: "Object Mapping Configuration" +summary: "Object Mapping Configuration." +eleventyNavigation: + key: Object Mapping Configuration + parent: Object Mapping + order: 8 +--- diff --git a/website/src/posts/object-mapping/posts/reusing.md b/website/src/posts/object-mapping/posts/reusing.md index ac4e2f2e..902488ae 100644 --- a/website/src/posts/object-mapping/posts/reusing.md +++ b/website/src/posts/object-mapping/posts/reusing.md @@ -1,6 +1,6 @@ --- title: "Reusing Mappers" -summary: "Resolving source- and target properties." +summary: "Reusing other mappers." eleventyNavigation: key: Reusing Mappers parent: Object Mapping