docs: wip

docs/.vitepress/config.mts

@@ -79,6 +79,7 @@ export default defineConfig({
               { text: "converter", link: "/reference/converter" },
               { text: "extend", link: "/reference/extend" },
               { text: "name", link: "/reference/name" },
+              { text: "enum", link: "/reference/enum" },
               { text: "output", link: "/reference/output" },
               { text: "struct", link: "/reference/struct" },
             ],

docs/reference/enum.md

@@ -0,0 +1,160 @@
+# Setting: enum
+
+### Definition
+
+The Go language doesn't explicit define enums. In the context of Goverter an
+enum type is defined as a named type with an
+[underlying type](https://go.dev/ref/spec#Underlying_types) of (`float`,
+`string`, or `integer`) _and_ with at least one constant defined in the same
+package.
+
+These examples would qualify as enums:
+
+::: code-group
+<<< @../../example/enum/default/input/enum.go [iota.go]
+<<< @../../example/enum/default/output/enum.go [string.go]
+:::
+
+## enum:default ACTION
+
+`enum:default ACTION` can be defined as [method
+comment](./define-settings.md#method). No default value.
+
+Define what happens on an invalid or unexpected enum value.
+
+`enum:default @error` returns an error in the default case of the switch
+statement.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/default/error/input.go
+<<< @../../example/enum/default/input/enum.go [input/enum.go]
+<<< @../../example/enum/default/output/enum.go [output/enum.go]
+<<< @../../example/enum/default/error/generated/generated.go [generated/generated.go]
+:::
+
+`enum:default @ignore` does nothing in the default case of the switch
+statement.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/default/ignore/input.go
+<<< @../../example/enum/default/input/enum.go [input/enum.go]
+<<< @../../example/enum/default/output/enum.go [output/enum.go]
+<<< @../../example/enum/default/ignore/generated/generated.go [generated/generated.go]
+:::
+
+`enum:default @panic` panics in the default case of the switch statement.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/default/panic/input.go
+<<< @../../example/enum/default/input/enum.go [input/enum.go]
+<<< @../../example/enum/default/output/enum.go [output/enum.go]
+<<< @../../example/enum/default/panic/generated/generated.go [generated/generated.go]
+:::
+
+## enum:detect
+
+`enum:detect [yes|no]` can be defined as [CLI
+argument](./define-settings.md#cli) or [converter
+comment](./define-settings.md#converter).
+
+`enum:detect` enables enum detection as per [Definition](#definition) and
+enables the enum conversion generation when the `source` and `target` types are
+enum types.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/default/panic/input.go
+<<< @../../example/enum/default/input/enum.go [input/enum.go]
+<<< @../../example/enum/default/output/enum.go [output/enum.go]
+<<< @../../example/enum/default/panic/generated/generated.go [generated/generated.go]
+:::
+
+## enum:exclude
+
+`enum:exclude [PACKAGE:]NAME` can be defined as [CLI
+argument](./define-settings.md#cli) or [converter
+comment](./define-settings.md#converter).
+
+You can exclude falsely detected enums with exclude. This is useful when a type
+[qualifies as enum](#definition) but isn't one. If `PACKAGE` is unset, goverter
+will use the package of the converter interface.
+
+Both `PACKAGE` and `NAME` can be regular expressions.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/exclude/input.go
+<<< @../../example/enum/exclude/generated/generated.go [generated/generated.go]
+:::
+
+## enum:map SOURCE TARGET
+
+`enum:map SOURCE TARGET` can be defined as [method
+comment](./define-settings.md#method).
+
+`enum:map` can be used to map an enum key of the source enum type to the target
+type. In this example we have two spellings of Gray|Grey.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/map/input.go
+<<< @../../example/enum/map/input/enum.go [input/enum.go]
+<<< @../../example/enum/map/output/enum.go [output/enum.go]
+<<< @../../example/enum/map/generated/generated.go [generated/generated.go]
+:::
+
+You can also use any of the `@actions` from
+[`enum:default`](#enumdefault-action). E.g.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/map-panic/input.go
+<<< @../../example/enum/map-panic/input/enum.go [input/enum.go]
+<<< @../../example/enum/map-panic/output/enum.go [output/enum.go]
+<<< @../../example/enum/map-panic/generated/generated.go [generated/generated.go]
+:::
+
+## enum:transform ID [CONFIG]
+
+
+`enum:transform ID [CONFIG]` can be defined as [method
+comment](./define-settings.md#method).
+
+`enum:transform` allows you to transform multiple enum keys to the target keys.
+There are 5 builtin transformers and you can define transformers yourself.
+
+### enum:transform (trim|add)-prefix PREFIX
+
+With `trim-prefix` you can trim the prefix of the source enum keys and with
+`add-prefix` you can add a prefix to the source enum keys.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/transform-prefix/input.go
+<<< @../../example/enum/transform-prefix/generated/generated.go [generated/generated.go]
+:::
+
+### enum:transform (trim|add)-suffix SUFFIX
+
+With `trim-suffix` you can trim the suffix of the source enum keys and with
+`add-suffix` you can add a suffix to the source enum keys.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/transform-suffix/input.go
+<<< @../../example/enum/transform-suffix/generated/generated.go [generated/generated.go]
+:::
+
+
+### enum:transform regex SEARCH REPLACE
+
+With `regex` you can do a regex replace of the enum keys.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/enum/transform-regex/input.go
+<<< @../../example/enum/transform-regex/generated/generated.go [generated/generated.go]
+::

docs/reference/settings.md

@@ -10,6 +10,8 @@ These settings can only be defined as [CLI argument](./define-settings.md#cli) o
 [converter comment](./define-settings.md#converter).
 
 - [`converter` marker comment for conversion interfaces](./converter.md)
+- [`enum:detect [yes|no]` enable enum detection](./enum.md#enum-detect)
+- [`enum:exclude [PACKAGE:]NAME` exclude wrongly detected enums](./enum.md#enum-exclude)
 - [`extend [PACKAGE:]TYPE...` add custom methods for conversions](./extend.md)
 - [`name NAME` rename generated struct](./name.md)
 - [`output:file FILE` set the output directory for a converter](./output.md#outputfile)
@@ -22,6 +24,8 @@ These settings can only be defined as [method comment](./define-settings.md#meth
 
 - [`autoMap PATH` automatically match fields from a sub struct to the target struct](./autoMap.md)
 - [`default [PACKAGE:]TYPE` define default target value](./default.md)
+- [`enum:map SOURCE TARGET` define an enum value mapping](./enum.md#enum-map-source-target)
+- [`enum:transform ID CONFIG` use an enum value transformer](./enum.md#enum-transform-id-config)
 - [`ignore FIELD...` ignore fields for a struct](./ignore.md)
 - [`map [SOURCE-PATH] TARGET [| METHOD]` struct mappings](./map.md)
   - [`map SOURCE-FIELD TARGET` define a field mapping](./map.md#map-source-field-target)
@@ -42,6 +46,7 @@ These settings can be defined as [CLI argument](./define-settings.md#cli),
 - [`ignoreUnexported [yes,no]` ignore unexported struct fields](./ignoreUnexported.md)
 - [`matchIgnoreCase [yes,no]` case-insensitive field matching](./matchIgnoreCase.md)
 - [`skipCopySameType [yes,no]` skip copying types when the source and target type are the same](./skipCopySameType.md)
+- [`enum:default ACTION` handle unexpected enum values](./enum.md#enum-default-action)
 - [`useUnderlyingTypeMethods [yes|no]` use underlying types when looking for existing methods](./useUnderlyingTypeMethods.md)
 - [`useZeroValueOnPointerInconsistency [yes|no]` Use zero values for `*S` to `T` conversions](./useZeroValueOnPointerInconsistency.md)
 - [`wrapErrors [yes,no]` wrap errors with extra information](./wrapErrors.md)

example/enum/default/error/input.go

@@ -0,0 +1,13 @@
+package example
+
+import (
+	"github.com/jmattheis/goverter/example/enum/default/input"
+	"github.com/jmattheis/goverter/example/enum/default/output"
+)
+
+// goverter:converter
+// goverter:enum:detect
+// goverter:enum:default @error
+type Converter interface {
+	Convert(input.Color) (output.Color, error)
+}

example/enum/default/ignore/input.go

@@ -0,0 +1,13 @@
+package example
+
+import (
+	"github.com/jmattheis/goverter/example/enum/default/input"
+	"github.com/jmattheis/goverter/example/enum/default/output"
+)
+
+// goverter:converter
+// goverter:enum:detect
+// goverter:enum:default @ignore
+type Converter interface {
+	Convert(input.Color) output.Color
+}

example/enum/default/input/enum.go

@@ -0,0 +1,8 @@
+package input
+
+type Color int
+const (
+    Green Color = iota
+    Blue
+    Red
+)

example/enum/default/output/enum.go

@@ -0,0 +1,8 @@
+package output
+
+type Color string
+const (
+    Green Color = "green"
+    Blue  Color = "blue"
+    Red   Color = "red"
+)

example/enum/default/panic/input.go

@@ -0,0 +1,13 @@
+package example
+
+import (
+	"github.com/jmattheis/goverter/example/enum/default/input"
+	"github.com/jmattheis/goverter/example/enum/default/output"
+)
+
+// goverter:converter
+// goverter:enum:detect
+// goverter:enum:default @panic
+type Converter interface {
+	Convert(input.Color) output.Color
+}

example/enum/exclude/input.go

@@ -0,0 +1,21 @@
+package example
+
+import (
+	"time"
+)
+
+// goverter:converter
+// goverter:enum:detect
+// goverter:enum:default @panic
+// goverter:enum:exclude MyDuration
+// goverter:enum:exclude time:Duration
+type Converter interface {
+	Convert(MyDuration) time.Duration
+}
+
+type MyDuration int64
+
+const (
+	Nanoseconds  MyDuration = 1
+	Microseconds MyDuration = 1000 * Nanoseconds
+)