diff --git a/website/src/_data/navigation.json b/website/src/_data/navigation.json index 5356382b..37322a7f 100644 --- a/website/src/_data/navigation.json +++ b/website/src/_data/navigation.json @@ -32,13 +32,33 @@ "items": [ { "caption": "Object Mapping", - "url": "/usage/object-mapping/", + "url": "/object-mapping/overview/", "external": false }, { "caption": "Enum Mapping", - "url": "/usage/enum-mapping/", + "url": "/enum-mapping/overview/", "external": false + }, + { + "caption": "Primitive Mapping", + "url": "/primitive-mapping/overview/", + "external": false + } + ] + }, + { + "title": "Contact", + "items": [ + { + "caption": "Submit a Bug or Feature Request", + "url": "https://github.com/Mr-Mappie/mappie/issues/new/choose", + "external": true + }, + { + "caption": "Start a Discussion", + "url": "https://github.com/Mr-Mappie/mappie/discussions/new/choose", + "external": true } ] } diff --git a/website/src/_includes/layouts/front-page.html b/website/src/_includes/layouts/front-page.html index 26cf3b87..731a59ef 100644 --- a/website/src/_includes/layouts/front-page.html +++ b/website/src/_includes/layouts/front-page.html @@ -37,7 +37,7 @@

{{ faq.title }}

{% endif %}

Acknowledgements

-

This documentation page is based on the template of Cone.

+

This documentation page is based on the template by Cone.

{% endblock %} diff --git a/website/src/img/icon/note.svg b/website/src/img/icon/note.svg new file mode 100644 index 00000000..52273257 --- /dev/null +++ b/website/src/img/icon/note.svg @@ -0,0 +1,13 @@ + + + + + + + + \ No newline at end of file diff --git a/website/src/index.md b/website/src/index.md index 43e53eb5..1071e287 100644 --- a/website/src/index.md +++ b/website/src/index.md @@ -18,4 +18,16 @@ overview: title: "Getting Started" url: "/getting-started/" description: "Start here and get to know Mappie." +- + title: "Object Mapping" + url: "/object-mapping/" + description: "Learn how to use Mappie for object mapping." +- + title: "Enum Mapping" + url: "/enum-mapping/" + description: "Learn how to use Mappie for enum mapping." +- + title: "Primitive Mapping" + url: "/primitive-mapping/" + description: "Learn how to use Mappie for primitive mapping." --- \ No newline at end of file diff --git a/website/src/posts/enum-mapping/enum-mapping.md b/website/src/posts/enum-mapping/enum-mapping.md new file mode 100644 index 00000000..09ad2109 --- /dev/null +++ b/website/src/posts/enum-mapping/enum-mapping.md @@ -0,0 +1,6 @@ +--- +title: "Enum Mapping" +eleventyNavigation: + key: Enum Mapping + order: 3 +--- diff --git a/website/src/posts/enum-mapping/posts/configuration.md b/website/src/posts/enum-mapping/posts/configuration.md new file mode 100644 index 00000000..9fe4f25b --- /dev/null +++ b/website/src/posts/enum-mapping/posts/configuration.md @@ -0,0 +1,21 @@ +--- +title: "Enum Mapping Configuration" +summary: "Enum mapping configuration." +eleventyNavigation: + key: Enum Mapping Configuration + parent: Enum Mapping + order: 10 +--- + +By default, all enum sources must have a defined target. This can be disabled by adding the following +configuration to the `build.gradle.kts` file + +```kotlin +mappie { + strictness { + enums = false // Disable validating that all enum sources have a corresponding target + } +} +``` + +Note that this might result in a [NoWhenBranchMatchedException](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-no-when-branch-matched-exception/) exception being thrown at runtime. \ No newline at end of file diff --git a/website/src/posts/enum-mapping/posts/entry-mapping.md b/website/src/posts/enum-mapping/posts/entry-mapping.md new file mode 100644 index 00000000..68cf2e48 --- /dev/null +++ b/website/src/posts/enum-mapping/posts/entry-mapping.md @@ -0,0 +1,28 @@ +--- +title: "Entry Mapping" +summary: "Mapping enum entry values." +eleventyNavigation: + key: Entry Mapping + parent: Enum Mapping + order: 9 +--- + +Not all enums classes that one wants to map have identical entries. If this is the case, +Mappie cannot determine which source must map to which target. + +Suppose `Color` has an extra entry `Color.ORANGE`, whilst `Colour` does +not have `Colour.ORANGE`, but does have `Colour.OTHER`. In other words +```kotlin +enum class Color { RED, GREEN, BLUE, ORANGE; } + +enum class Colour { RED, GREEN, BLUE, OTHER; } +``` + +We can generate a complete mapper by mapping `Colour.ORANGE` to `Colour.OTHER` via `mappedFromEnumEntry` +```kotlin +object ColorMapper : EnumMapper() { + override fun map(from: Color): Colour = mapping { + Colour.OTHER mappedFromEnumEntry Color.ORANGE + } +} +``` \ No newline at end of file diff --git a/website/src/posts/enum-mapping/posts/overview.md b/website/src/posts/enum-mapping/posts/overview.md new file mode 100644 index 00000000..96e1adda --- /dev/null +++ b/website/src/posts/enum-mapping/posts/overview.md @@ -0,0 +1,29 @@ +--- +title: "Enum Mapping Overview" +summary: "Performing enum mapping." +eleventyNavigation: + key: Enum Mapping Overview + parent: Enum Mapping + order: 8 +--- + +Mappie supports mapping an enum class to another enum class. This can be achieved by implementing a mapper object which +extends from `EnumMapper`. + +The mappings of the enum entries are resolved by name. For example, when constructing a mapper for the enum +classes `Color` +```kotlin +enum class Color { RED, GREEN, BLUE; } +``` +and `Colour` +```kotlin +enum class Colour { RED, GREEN, BLUE; } +``` +Mappie will resolve all mappings automatically, as the enum classes have identical entries. + +This can be achieved by writing the following enum mapper +```kotlin +object ColorMapper : EnumMapper() { + override fun map(from: Color): Colour = mapping() +} +``` \ No newline at end of file diff --git a/website/src/posts/enum-mapping/posts/posts.json b/website/src/posts/enum-mapping/posts/posts.json new file mode 100644 index 00000000..654ad627 --- /dev/null +++ b/website/src/posts/enum-mapping/posts/posts.json @@ -0,0 +1,4 @@ +{ + "layout": "layouts/post.html", + "permalink": "/enum-mapping/{{ title | slug }}/index.html" +} diff --git a/website/src/posts/usage/posts/object-mapping.md b/website/src/posts/object-mapping/object-mapping.md similarity index 52% rename from website/src/posts/usage/posts/object-mapping.md rename to website/src/posts/object-mapping/object-mapping.md index ac85c083..ed2ffa69 100644 --- a/website/src/posts/usage/posts/object-mapping.md +++ b/website/src/posts/object-mapping/object-mapping.md @@ -1,9 +1,6 @@ --- title: "Object Mapping" -summary: "Performing object mapping." eleventyNavigation: key: Object Mapping - parent: Usage - order: 3 + order: 2 --- - diff --git a/website/src/posts/object-mapping/posts/collections.md b/website/src/posts/object-mapping/posts/collections.md new file mode 100644 index 00000000..fd852d9b --- /dev/null +++ b/website/src/posts/object-mapping/posts/collections.md @@ -0,0 +1,8 @@ +--- +title: "Lists, Sets & More" +summary: "Resolving source- and target properties." +eleventyNavigation: + key: Lists, Sets & More + parent: Object Mapping + order: 7 +--- diff --git a/website/src/posts/object-mapping/posts/overview.md b/website/src/posts/object-mapping/posts/overview.md new file mode 100644 index 00000000..3e1b8e41 --- /dev/null +++ b/website/src/posts/object-mapping/posts/overview.md @@ -0,0 +1,64 @@ +--- +title: "Object Mapping Overview" +summary: "Performing object mapping." +eleventyNavigation: + key: Object Mapping Overview + parent: Object Mapping + order: 3 +--- + +Mappie supports creating data object mappers via the base class `DataClassMapper`. + +Suppose we have a data class `Person` +```kotlin +data class Person(val name: String, val age: Int) +``` +and a data class `PersonDto` +```kotlin +data class PersonDto(val name: String, val age: Int) +``` +The fields of `Person` match those of `PersonDto`, and as such, not mappings have to be defined, for example +```kotlin +object PersonMapper : DataClassMapper() { + override fun map(from: Person): PersonDto = mapping() +} +``` + +## Unresolved properties +Not all data classes you want to map are equivalent. Suppose the target class `PersonDto` has the property `description`, which is not defined in `Person` +```kotlin +data class PersonDto( + val name: String, + val age: Int, + val description: String, +) +``` + +Mappie will throw an error stating that the target `description` has no source defined. + +This can be addressed in multiple ways. + +### Explicit property mapping via another property +A possibility is to map `description` from another property, e.g. via `name` + +```kotlin +object PersonMapper : DataClassMapper() { + override fun map(from: Person): PersonDto = mapping { + PersonDto::description mappedFromProperty Person::name + } +} +``` + +### Explicit property mapping via an expression +A possibility is to map `description` from an expression, e.g. setting it to the constant `"unknown"` + +```kotlin +object PersonMapper : DataClassMapper() { + override fun map(from: Person): PersonDto = mapping { + PersonDto::description mappedFromExpression { source -> "unknown" } + } +} +``` +the parameter of the lambda `source` is equal to `from`. It does not have to be named. + +## Configuration diff --git a/website/src/posts/object-mapping/posts/posts.json b/website/src/posts/object-mapping/posts/posts.json new file mode 100644 index 00000000..d3617054 --- /dev/null +++ b/website/src/posts/object-mapping/posts/posts.json @@ -0,0 +1,4 @@ +{ + "layout": "layouts/post.html", + "permalink": "/object-mapping/{{ title | slug }}/index.html" +} diff --git a/website/src/posts/object-mapping/posts/resolving.md b/website/src/posts/object-mapping/posts/resolving.md new file mode 100644 index 00000000..e49f0f7a --- /dev/null +++ b/website/src/posts/object-mapping/posts/resolving.md @@ -0,0 +1,8 @@ +--- +title: "Resolving" +summary: "Resolving source- and target properties." +eleventyNavigation: + key: Resolving + parent: Object Mapping + order: 4 +--- diff --git a/website/src/posts/object-mapping/posts/reusing.md b/website/src/posts/object-mapping/posts/reusing.md new file mode 100644 index 00000000..ac4e2f2e --- /dev/null +++ b/website/src/posts/object-mapping/posts/reusing.md @@ -0,0 +1,8 @@ +--- +title: "Reusing Mappers" +summary: "Resolving source- and target properties." +eleventyNavigation: + key: Reusing Mappers + parent: Object Mapping + order: 5 +--- diff --git a/website/src/posts/object-mapping/posts/transforming.md b/website/src/posts/object-mapping/posts/transforming.md new file mode 100644 index 00000000..8c0f9b57 --- /dev/null +++ b/website/src/posts/object-mapping/posts/transforming.md @@ -0,0 +1,8 @@ +--- +title: "Transforming" +summary: "Transforming source properties." +eleventyNavigation: + key: Transforming + parent: Object Mapping + order: 6 +--- diff --git a/website/src/posts/primitive-mapping/posts/overview.md b/website/src/posts/primitive-mapping/posts/overview.md new file mode 100644 index 00000000..214fb3b1 --- /dev/null +++ b/website/src/posts/primitive-mapping/posts/overview.md @@ -0,0 +1,9 @@ +--- +title: "Primitive Mapping Overview" +summary: "Performing primitive mapping." +eleventyNavigation: + key: Primitive Mapping Overview + parent: Primitive Mapping + order: 11 +--- + diff --git a/website/src/posts/primitive-mapping/posts/posts.json b/website/src/posts/primitive-mapping/posts/posts.json new file mode 100644 index 00000000..a654e33e --- /dev/null +++ b/website/src/posts/primitive-mapping/posts/posts.json @@ -0,0 +1,4 @@ +{ + "layout": "layouts/post.html", + "permalink": "/primitive-mapping/{{ title | slug }}/index.html" +} diff --git a/website/src/posts/primitive-mapping/primitive-mapping.md b/website/src/posts/primitive-mapping/primitive-mapping.md new file mode 100644 index 00000000..ec0e7b13 --- /dev/null +++ b/website/src/posts/primitive-mapping/primitive-mapping.md @@ -0,0 +1,6 @@ +--- +title: "Primitive Mapping" +eleventyNavigation: + key: Primitive Mapping + order: 4 +--- diff --git a/website/src/posts/usage/posts/enum-mapping.md b/website/src/posts/usage/posts/enum-mapping.md deleted file mode 100644 index a60ddd81..00000000 --- a/website/src/posts/usage/posts/enum-mapping.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Enum Mapping" -summary: "Performing enum mapping." -eleventyNavigation: - key: Enum Mapping - parent: Usage - order: 4 ---- - -# Summary -Mappie supports creating enum mappers via the base class `EnumMapper`. - -Suppose we have an enum class `Color` -```kotlin -enum class Color { RED, GREEN, BLUE; } -``` -and an enum class `Colour` -```kotlin -enum class Colour { RED, GREEN, GLUE; } -``` -The entries of both are identical, so we do not have to declare any mapping explicitly -```kotlin -object ColorMapper : EnumMapper() { - override fun map(from: Color): Colour = mapping() -} -``` - -Now suppose `Color` has an extra entry: `Color.ORANGE`, whilst `Colour` does -not have `Colour.ORANGE`, but does have `Colour.OTHER`. We can map `Colour.ORANGE` to `Colour.OTHER` via - -```kotlin -object ColorMapper : EnumMapper() { - override fun map(from: Color): Colour = mapping { - Colour.OTHER mappedFromEnumEntry Color.ORANGE - } -} -``` - -# Configuration options - diff --git a/website/src/posts/usage/posts/posts.json b/website/src/posts/usage/posts/posts.json deleted file mode 100644 index 3753edae..00000000 --- a/website/src/posts/usage/posts/posts.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "layout": "layouts/post.html", - "permalink": "/usage/{{ title | slug }}/index.html" -} diff --git a/website/src/posts/usage/usage.md b/website/src/posts/usage/usage.md deleted file mode 100644 index c07d652b..00000000 --- a/website/src/posts/usage/usage.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: "Usage" -eleventyNavigation: - key: Usage - order: 2 ----