docs: input/output formats

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" },
             ],
           },
           {

docs/changelog.md

@@ -8,6 +8,15 @@ import GH from './GH.vue';
 
 - tbd
 
+## v1.5.0
+
+- 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
 
 - Error when the settings [`enum`](reference/enum.md) and

docs/guide/format.md

@@ -0,0 +1,77 @@
+# 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.
+
+[[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
+:::

docs/reference/converter.md

@@ -1,7 +1,7 @@
 # Setting: converter
 
-`converter` accepts no arguments and can be defined as [converter
-comment](./define-settings.md#converter).
+`converter` accepts no arguments and can be defined as [conversion
+comment](./define-settings.md#conversion).
 
 `converter` instructs goverter to generate an implementation for the given
 interface. You can have multiple converters in one package.

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 you 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 you 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 you 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

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.
@@ -25,8 +25,8 @@ default.
 
 
 `enum:unknown ACTION|KEY` can be defined as [CLI
-argument](./define-settings.md#cli), [converter
-comment](./define-settings.md#converter) or [method
+argument](./define-settings.md#cli), [conversion
+comment](./define-settings.md#conversion) or [method
 comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 
@@ -77,8 +77,8 @@ statement.
 ## enum:exclude
 
 `enum:exclude [PACKAGE:]NAME` can be defined as [CLI
-argument](./define-settings.md#cli) or [converter
-comment](./define-settings.md#converter).
+argument](./define-settings.md#cli) or [conversion
+comment](./define-settings.md#conversion).
 
 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

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,

docs/reference/ignoreMissing.md

@@ -1,8 +1,8 @@
 # Setting: ignoreMissing
 
 `ignoreMissing [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 [method
+can be defined as [CLI argument](./define-settings.md#cli), [conversion
+comment](./define-settings.md#conversion) or [method
 comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 

docs/reference/ignoreUnexported.md

@@ -1,8 +1,8 @@
 # Setting: ignoreUnexported
 
 `ignoreUnexported [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 [method
+and can be defined as [CLI argument](./define-settings.md#cli), [conversion
+comment](./define-settings.md#conversion) or [method
 comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 

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).
 

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.

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

docs/reference/settings.md

@@ -4,21 +4,23 @@ 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)
 - [`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)
-- [`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)
+- [`output:file FILE` set the output directory for a converter](./output.md#output-file)
+- [`output:format FORMAT` set the output format](./output.md#output-format)
+- [`output:package [PACKAGE:]NAME` set the output package for a converter](./output.md#output-package)
+- [`struct:comment COMMENT` add comments to generated struct](./struct.md#struct-comment-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 +40,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).
 

docs/reference/skipCopySameType.md

@@ -1,8 +1,8 @@
 # Setting: skipCopySameType
 
 `skipCopySameType [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 [method
+and can be defined as [CLI argument](./define-settings.md#cli), [conversion
+comment](./define-settings.md#conversion) or [method
 comment](./define-settings.md#method). This setting is
 [inheritable](./define-settings.md#inheritance).
 

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