docs: input/output formats

jmattheis · Jun 23, 2024 · b213461 · b213461
1 parent c286948
commit b213461
Show file tree

Hide file tree

Showing 23 changed files with 475 additions and 21 deletions.
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -42,12 +42,13 @@ export default defineConfig({
     sidebar: [
       { text: "Intro", link: "/" },
       { text: "Use-Cases", link: "/use-case" },
+      { text: "Error early", link: "/guide/error-early" },
       {
         text: "Guides",
         items: [
           { text: "Getting Started", link: "/guide/getting-started" },
           { text: "Installation", link: "/guide/install" },
-          { text: "Error early", link: "/guide/error-early" },
+          { text: "Input/Output formats", link: "/guide/format" },
           { text: "Convert Enums", link: "/guide/enum" },
           {
             text: "Output into same package",
@@ -77,14 +78,15 @@ export default defineConfig({
           { text: "Settings Overview", link: "/reference/settings" },
           { text: "Enums", link: "/reference/enum" },
           {
-            text: "Converter",
+            text: "Conversion",
             collapsed: true,
             items: [
               { text: "converter", link: "/reference/converter" },
               { text: "extend", link: "/reference/extend" },
               { text: "name", link: "/reference/name" },
               { text: "output", link: "/reference/output" },
               { text: "struct", link: "/reference/struct" },
+              { text: "variables", link: "/reference/variables" },
             ],
           },
           {

diff --git a/docs/changelog.md b/docs/changelog.md
@@ -6,7 +6,12 @@ import GH from './GH.vue';
 
 ## unreleased
 
-- tbd
+- Add two input-output formats. See
+  [Guide: Input/Output formats](guide/format.md) for help to choose a format.
+  The new formats allow you to call top level functions without the need to
+  instantiate a struct to call methods on it. <GH issue="77" pr="149"/>
+  - Add [`variables`](reference/variables.md) setting
+  - Add [`output:format`](reference/output.md#output-format) setting
 
 ## v1.4.1
 

diff --git a/docs/guide/format.md b/docs/guide/format.md
@@ -0,0 +1,78 @@
+# Input and output formats
+
+Goverter supports three different input output format combinations. This guide
+is for you to decide the formats you want to use. All examples have this in
+common.
+
+[[toc]]
+
+## interface to struct
+
+This is the default when using
+[`goverter:converter`](../reference/converter.md).
+
+**Pros**:
+
+- All goverter features are supported
+- The interface is usable before goverter generated the implementation.
+  - reduces the occurence of compile errors because of missing or outdated
+  generated implementation.
+  - allows using generated methods in custom methods
+
+**Cons**:
+
+- You need to initialize the implementation.
+- You need to call methods on the struct to execute conversions
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/format/interfacetostruct/input.go
+<<< @../../example/format/common/common.go
+<<< @../../example/format/interfacetostruct/generated/generated.go [generated/generated.go]
+:::
+
+## variables to assign-variable
+
+This is the default when using
+[`goverter:variables`](../reference/converter.md).
+
+**Pros**:
+
+- All goverter features are supported.
+- The variables are usable before goverter generated the implementation.
+  - reduces the occurence of compile errors because of missing or outdated
+    generated implementation.
+  - allows using generated functions in custom methods
+- You can execute conversions directly without having to initializing a struct
+
+**Cons**:
+
+- Possible runtime overhead when Go cannot optimizen variables the same as
+  functions. Benchmark your use-case, if speed is really important to you.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/format/assignvariables/input.go
+<<< @../../example/format/common/common.go
+<<< @../../example/format/assignvariables/input.gen.go
+:::
+
+## interface to functions
+
+**Pros**:
+
+- You can execute conversions directly without having to initializing a struct
+
+**Cons**:
+
+- The interface is only used for defining the conversions and is otherwise not
+  usable
+- The use-case [`map` method with converter](../reference/map.md#method-with-converter) is
+  unsupported without replacement.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/format/interfacefunction/input.go
+<<< @../../example/format/common/common.go
+<<< @../../example/format/interfacefunction/generated/generated.go
+:::
diff --git a/docs/reference/define-settings.md b/docs/reference/define-settings.md
@@ -28,9 +28,10 @@ type Converter interface {
 
 the resolved settings would be the same as with the example below for Converter.
 
-## Converter
+## Conversion
 
-You can define settings on the converter interface by prefixing them with `goverter:`.
+When using [`goverter:converter`](converter.md), then can define settings on the
+converter interface by prefixing them with `goverter:`.
 
 ```go
 // goverter:converter
@@ -41,9 +42,22 @@ type Converter interface {
 }
 ```
 
+When using [`goverter:variables`](variables.md), then can define settings on the
+`var`-block by prefixing them with `goverter:`.
+
+```go
+// goverter:variables
+// goverter:setting yes
+// goverter:setting2 no
+var (
+    Convert func(source Input) Output
+)
+```
+
 ## Method
 
-You can define settings on the converter methods by prefixing them with `goverter:`.
+When using [`goverter:converter`](converter.md), then you can define settings
+on the converter methods by prefixing them with `goverter:`.
 
 ```go
 // goverter:converter
@@ -54,6 +68,18 @@ type Converter interface {
 }
 ```
 
+When using [`goverter:variables`](variables.md), then can define settings on the
+function variables by prefixing them with `goverter:`.
+
+```go
+// goverter:variables
+var (
+    // goverter:setting yes
+    // goverter:setting2 no
+    Convert func(source Input) Output
+)
+```
+
 ### Inheritance
 
 Method settings can be inherited for all methods if they are defined on the CLI

diff --git a/docs/reference/enum.md b/docs/reference/enum.md
@@ -10,7 +10,7 @@ type](https://go.dev/ref/spec#Underlying_types) of (`float`, `string`, or
 ## enum
 
 `enum [yes|no]` can be defined as [CLI argument](./define-settings.md#cli) or
-[converter comment](./define-settings.md#converter). `enum` is enabled per
+[conversion comment](./define-settings.md#conversion). `enum` is enabled per
 default.
 
 `enum` allows you to disable enum support in goverter.

diff --git a/docs/reference/extend.md b/docs/reference/extend.md
@@ -1,7 +1,7 @@
 # Setting: extend
 
 `extend [PACKAGE:]TYPE...` can be defined as [CLI argument](./define-settings.md#cli) or
-[converter comment](./define-settings.md#converter).
+[conversion comment](./define-settings.md#conversion).
 
 If a type cannot be converted automatically, you can manually define an
 implementation with `:extend` for the missing mapping. Keep in mind,

diff --git a/docs/reference/matchIgnoreCase.md b/docs/reference/matchIgnoreCase.md
@@ -3,7 +3,7 @@
 `matchIgnoreCase [yes,no]` is a
 [boolean setting](./define-settings.md#boolean) and can be defined as
 [CLI argument](./define-settings.md#cli),
-[converter comment](./define-settings.md#converter) or
+[conversion comment](./define-settings.md#conversion) or
 [method comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 

diff --git a/docs/reference/name.md b/docs/reference/name.md
@@ -1,7 +1,7 @@
 # Setting: name
 
 `name NAME` can be defined as [CLI argument](./define-settings.md#cli) or
-[converter comment](./define-settings.md#converter).
+[conversion comment](./define-settings.md#conversion).
 
 `name` instructs goverter to use the given *name* for the generated struct. By
 default goverter will use the interface name and append `Impl` at the end.

diff --git a/docs/reference/output.md b/docs/reference/output.md
@@ -1,9 +1,11 @@
 # Setting: output
 
+[[toc]]
+
 ## output:file
 
 `output:file FILE` can be defined as [CLI argument](./define-settings.md#cli) or
-[converter comment](./define-settings.md#converter). Default is
+[conversion comment](./define-settings.md#conversion). Default is
 `./generated/generated.go`.
 
 `output:file` sets the generated output file of a converter interface. The file
@@ -28,10 +30,50 @@ the same. See this more complex example:
 <<< @../../example/output-multiple-files/b/generated.go [b/generated.go]
 :::
 
+## output:format
+
+`output:format FORMAT` can be defined as [CLI argument](./define-settings.md#cli) or
+[conversion comment](./define-settings.md#conversion). Default `struct`
+
+Specify the output FORMAT for the conversion methods. See [Guide: Input/Output formats](../guide/format.md)
+
+### output:format struct
+
+Output an implementation of the conversion interface by creating a struct with methods.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/format/interfacetostruct/input.go
+<<< @../../example/format/common/common.go
+<<< @../../example/format/interfacetostruct/generated/generated.go [generated/generated.go]
+:::
+
+### output:format assign-variable
+
+Output an init function assiging an implementation for all function variables.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/format/assignvariables/input.go
+<<< @../../example/format/common/common.go
+<<< @../../example/format/assignvariables/input.gen.go
+:::
+
+### output:format function
+
+Output a function for each method in the conversion interface.
+
+::: details Example (click me)
+::: code-group
+<<< @../../example/format/interfacefunction/input.go
+<<< @../../example/format/common/common.go
+<<< @../../example/format/interfacefunction/generated/generated.go [generated/generated.go]
+:::
+
 ## output:package
 
 `output:package [PACKAGE][:NAME]` can be defined as
-[CLI argument](./define-settings.md#cli) or [converter comment](./define-settings.md#converter).
+[CLI argument](./define-settings.md#cli) or [conversion comment](./define-settings.md#conversion).
 Default is `:generated`.
 
 ### output:package PACKAGE

diff --git a/docs/reference/settings.md b/docs/reference/settings.md
@@ -4,10 +4,10 @@ Before configuring settings here it is useful to understand how [converter
 generation works](../explanation/generation.md) and how to [configure nested
 settings](../guide/configure-nested.md).
 
-## Converter
+## Conversion
 
 These settings can only be defined as [CLI argument](./define-settings.md#cli) or
-[converter comment](./define-settings.md#converter).
+[conversion comment](./define-settings.md#conversion).
 
 - [`converter` marker comment for conversion interfaces](./converter.md)
 - [`enum [yes|no]` enable / disable enum support](./enum.md#enum-detect)
@@ -17,8 +17,9 @@ These settings can only be defined as [CLI argument](./define-settings.md#cli) o
 - [`output:file FILE` set the output directory for a converter](./output.md#outputfile)
 - [`output:package [PACKAGE:]NAME` set the output package for a converter](./output.md#outputpackage)
 - [`struct:comment COMMENT` add comments to generated struct](./struct.md#structcomment-comment)
+- [`variables` marker comment for variable blocks](./variables.md)
 
-## Method:
+## Method
 
 These settings can only be defined as [method comment](./define-settings.md#method).
 
@@ -38,7 +39,7 @@ These settings can only be defined as [method comment](./define-settings.md#meth
 ### Method (inheritable)
 
 These settings can be defined as [CLI argument](./define-settings.md#cli),
-[converter comment](./define-settings.md#converter) or
+[conversion comment](./define-settings.md#conversion) or
 [method comment](./define-settings.md#method) and are
 [inheritable](./define-settings.md#inheritance).
 

diff --git a/docs/reference/struct.md b/docs/reference/struct.md
@@ -3,7 +3,7 @@
 ## struct:comment COMMENT
 
 `struct:comment COMMENT` can be defined as [CLI argument](./define-settings.md#cli)
-or [converter comment](./define-settings.md#converter).
+or [conversion comment](./define-settings.md#conversion).
 
 `struct:comment` instructs goverter to add a comment line to the generated
 struct. It can be configured multiple times to add multiline comments. Prefix

diff --git a/docs/reference/useUnderlyingTypeMethods.md b/docs/reference/useUnderlyingTypeMethods.md
@@ -3,7 +3,7 @@
 `useUnderlyingTypeMethods [yes,no]` is a
 [boolean setting](./define-settings.md#boolean) and can be defined as
 [CLI argument](./define-settings.md#cli),
-[converter comment](./define-settings.md#converter) or
+[conversion comment](./define-settings.md#conversion) or
 [method comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 

diff --git a/docs/reference/useZeroValueOnPointerInconsistency.md b/docs/reference/useZeroValueOnPointerInconsistency.md
@@ -3,7 +3,7 @@
 `useZeroValueOnPointerInconsistency [yes,no]` is a
 [boolean setting](./define-settings.md#boolean) and can be defined as
 [CLI argument](./define-settings.md#cli),
-[converter comment](./define-settings.md#converter) or
+[conversion comment](./define-settings.md#conversion) or
 [method comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 

diff --git a/docs/reference/variables.md b/docs/reference/variables.md
@@ -0,0 +1,16 @@
+# Setting: converter
+
+`variables` accepts no arguments and can be defined as [converter
+comment](./define-settings.md#converter).
+
+`variables` instructs goverter to generate an implementation for the given
+variables. You can have multiple variables blocks in one package.
+
+See [output](./output.md) to control the output location/package of the
+generated converter.
+
+::: code-group
+<<< @../../example/format/assignvariables/input.go
+<<< @../../example/format/common/common.go
+<<< @../../example/format/assignvariables/input.gen.go
+:::
diff --git a/docs/reference/wrapErrors.md b/docs/reference/wrapErrors.md
@@ -3,7 +3,7 @@
 `wrapErrors [yes,no]` is a
 [boolean setting](./define-settings.md#boolean) and can be defined as
 [CLI argument](./define-settings.md#cli),
-[converter comment](./define-settings.md#converter) or
+[conversion comment](./define-settings.md#conversion) or
 [method comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 

diff --git a/docs/reference/wrapErrorsUsing.md b/docs/reference/wrapErrorsUsing.md
@@ -2,7 +2,7 @@
 
 `wrapErrorsUsing [PACKAGE]` is a [boolean setting](./define-settings.md#boolean)
 and can be defined as [CLI argument](./define-settings.md#cli),
-[converter comment](./define-settings.md#converter) or
+[conversion comment](./define-settings.md#conversion) or
 [method comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).