Code generation for enums from code comments

# go-enum

[![Actions Status](https://github.com/abice/go-enum/actions/workflows/build_and_test.yml/badge.svg)](https://github.com/abice/go-enum/actions/workflows/build_and_test.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/abice/go-enum)](https://goreportcard.com/report/github.com/abice/go-enum)
[![Coverage Status](https://coveralls.io/repos/github/abice/go-enum/badge.svg)](https://coveralls.io/github/abice/go-enum)
[![GoDoc](https://godoc.org/github.com/abice/go-enum?status.svg)](https://godoc.org/github.com/abice/go-enum)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

An enum generator for Go that creates type-safe enumerations with useful methods from simple type declarations.

## Key Features

- 🎯 **Type-safe enums** - Generate const declarations with proper typing
- 🔄 **String conversion** - Automatic `String()` and `Parse()` methods
- 📦 **JSON marshaling** - Built-in JSON marshal/unmarshal support
- 🗄️ **SQL integration** - Database scan and value functions
- 🧪 **Custom templates** - Extend with your own code generation
- ✅ **Multiple types** - Support for `int`, `string`, and other base types
- 🏷️ **Flexible syntax** - Simple comment-based enum declarations

## Table of Contents

- [Key Features](#key-features)
- [Requirements](#requirements)
- [Quick Start](#quick-start)
- [How it works](#how-it-works)
- [String typed enums](#now-with-string-typed-enums)
- [Recent Features](#recent-features)
- [Goal](#goal)
- [Docker image](#docker-image)
- [Installation](#installation)
- [Adding it to your project](#adding-it-to-your-project)
- [Command options](#command-options)
- [Syntax](#syntax)
- [Examples](#example)

## Requirements

- Go 1.24.0 or later (recommended for new tool installation method)
- Go 1.23.0 or later (minimum for legacy installation)

## Quick Start

1. Install go-enum as a project tool (Go 1.24+):

   ```shell
   go get -tool github.com/abice/go-enum@latest
   ```

   Or for older Go versions:

   ```shell
   go install github.com/abice/go-enum@latest
   ```

2. Create a Go file with an enum declaration:

   ```go
   package main
   
   // ENUM(red, green, blue)
   type Color int
   ```

3. Generate the enum:

   ```shell
   # Go 1.24+ (recommended)
   go tool go-enum -f your_file.go
   
   # Or for older Go versions
   go-enum -f your_file.go
   ```

4. Use your generated enum:

   ```go
   color := ColorRed
   fmt.Println(color.String()) // prints "red"
   
   parsed, err := ParseColor("green")
   if err == nil {
       fmt.Println(parsed) // prints "green"
   }
   ```

## How it works

go-enum will take a commented type declaration like this:

```go
// ENUM(jpeg, jpg, png, tiff, gif)
type ImageType int
```

and generate a file with the iota definition along various optional niceties that you may need:

```go
const (
 // ImageTypeJpeg is a ImageType of type Jpeg.
 ImageTypeJpeg ImageType = iota
 // ImageTypeJpg is a ImageType of type Jpg.
 ImageTypeJpg
 // ImageTypePng is a ImageType of type Png.
 ImageTypePng
 // ImageTypeTiff is a ImageType of type Tiff.
 ImageTypeTiff
 // ImageTypeGif is a ImageType of type Gif.
 ImageTypeGif
)

// String implements the Stringer interface.
func (x ImageType) String() string

// ParseImageType attempts to convert a string to a ImageType.
func ParseImageType(name string) (ImageType, error)

// MarshalText implements the text marshaller method.
func (x ImageType) MarshalText() ([]byte, error)

// UnmarshalText implements the text unmarshaller method.
func (x *ImageType) UnmarshalText(text []byte) error
```

**Fear not the fact that the `MarshalText` and `UnmarshalText` are generated rather than JSON methods... they will still be utilized by the default JSON encoding methods.**

If you find that the options given are not adequate for your use case, there is an option to add a custom template (`-t` flag) to the processing engine so that your custom code can be created!

## Now with string typed enums

```go
// ENUM(pending, running, completed, failed)
type StrState string
```

```go
const (
 // StrStatePending is a StrState of type pending.
 StrStatePending StrState = "pending"
 // StrStateRunning is a StrState of type running.
 StrStateRunning StrState = "running"
 // StrStateCompleted is a StrState of type completed.
 StrStateCompleted StrState = "completed"
 // StrStateFailed is a StrState of type failed.
 StrStateFailed StrState = "failed"
)
```

If you would like to get integer values in sql, but strings elsewhere, you can assign an int value in the declaration
like always, and specify the `--sqlint` flag.  Those values will be then used to convey the int value to sql, while allowing you to use only strings elsewhere.
This might be helpful for things like swagger docs where you want the same type being used on the api layer, as you do in the
sql layer, and not have swagger assume that your enumerations are integers, but are in fact strings!

```go
// swagger:enum StrState
// ENUM(pending, running, completed, failed)
type StrState string
```

## Recent Features

### Custom JSON Package Support (v0.7.0+)

You can now specify a custom JSON package for imports instead of the standard `encoding/json`:

```shell
go-enum --marshal --jsonpkg="github.com/goccy/go-json" -f your_file.go
```

### Disable iota (v0.9.0+)

For cases where you don't want to use `iota` in your generated enums:

```shell
go-enum --no-iota -f your_file.go
```

### Custom Output Suffix

Change the default `_enum.go` suffix to something else:

```shell
go-enum --output-suffix="_generated" -f your_file.go  # Creates your_file_generated.go
```

## Goal

The goal of go-enum is to create an easy to use enum generator that will take a decorated type declaration like `type EnumName int` and create the associated constant values and funcs that will make life a little easier for adding new values.
It's not perfect, but I think it's useful.

I took the output of the [Stringer](https://godoc.org/golang.org/x/tools/cmd/stringer) command as the `String()` method, and added a way to parse a string value.

## Docker image

You can use the Docker image directly for running the command if you do not wish to install anything locally:

```shell
docker run -w /app -v $(pwd):/app abice/go-enum:latest
```

## Installation

### Using go get -tool (Go 1.24+, recommended)

Install go-enum as a project tool with dependency tracking in `go.mod`:

```shell
go get -tool github.com/abice/go-enum@latest
```

This will add a tool dependency to your `go.mod` file:

```mod
tool github.com/abice/go-enum
```

You can then run the tool using:

```shell
go tool go-enum [options]
```

### Using go install (older Go versions)

Install the latest version directly from source:

```shell
go install github.com/abice/go-enum@latest
```

### Using GitHub releases

You can download a pre-built binary from GitHub releases. (Thanks to [GoReleaser](https://github.com/goreleaser/goreleaser-action))

```shell
# Download the latest release for your platform
curl -fsSL "https://github.com/abice/go-enum/releases/download/v0.9.0/go-enum_$(uname -s)_$(uname -m)" -o go-enum
chmod +x go-enum

# Or use a specific version by replacing v0.9.0 with your desired version
# Example: curl -fsSL "https://github.com/abice/go-enum/releases/download/v0.8.0/go-enum_$(uname -s)_$(uname -m)" -o go-enum
```

### Using Docker

You can use the Docker image directly without installing anything locally:

```shell
# Use the latest version
docker run -w /app -v $(pwd):/app abice/go-enum:latest

# Or use a specific version
docker run -w /app -v $(pwd):/app abice/go-enum:v0.9.0
```

## Adding it to your project

### Using go generate

For Go 1.24+ with tool dependency:

1. Install the tool dependency: `go get -tool github.com/abice/go-enum@latest`
1. Add a go:generate line to your file: `//go:generate go tool go-enum --marshal`
1. Run go generate: `go generate ./...`
1. Enjoy your newly created Enumeration!

For older Go versions:

1. Add a go:generate line to your file: `//go:generate go-enum --marshal`
1. Run go generate: `go generate ./...`
1. Enjoy your newly created Enumeration!

### Using Makefile

If you prefer makefile stuff, you can always do something like this:

For Go 1.24+ with tool dependency:

```Makefile
STANDARD_ENUMS = ./example/animal_enum.go \
 ./example/color_enum.go

NULLABLE_ENUMS = ./example/sql_enum.go

$(STANDARD_ENUMS): GO_ENUM_FLAGS=--nocase --marshal --names --ptr
$(NULLABLE_ENUMS): GO_ENUM_FLAGS=--nocase --marshal --names --sqlnullint --ptr

enums: $(STANDARD_ENUMS) $(NULLABLE_ENUMS)

# The generator statement for go enum files using go tool (Go 1.24+)
%_enum.go: %.go Makefile
 go tool go-enum -f $*.go $(GO_ENUM_FLAGS)
```

For older Go versions:

```Makefile
# The generator statement for go enum files using go-enum binary
%_enum.go: %.go $(GOENUM) Makefile
 $(GOENUM) -f $*.go $(GO_ENUM_FLAGS)
```

## Command options

``` shell
go-enum --help

NAME:
   go-enum - An enum generator for go

USAGE:
   go-enum [global options]

VERSION:
   example

GLOBAL OPTIONS:
   --file value, -f value [ --file value, -f value ]          The file(s) to generate enums.  Use more than one flag for more files. [$GOFILE]
   --noprefix                                                 Prevents the constants generated from having the Enum as a prefix. (default: false)
   --lower                                                    Adds lowercase variants of the enum strings for lookup. (default: false)
   --nocase                                                   Adds case insensitive parsing to the enumeration (forces lower flag). (default: false)
   --marshal                                                  Adds text (and inherently json) marshalling functions. (default: false)
   --sql                                                      Adds SQL database scan and value functions. (default: false)
   --sqlint                                                   Tells the generator that a string typed enum should be stored in sql as an integer value. (default: false)
   --flag                                                     Adds golang flag functions. (default: false)
   --jsonpkg value                                            Custom json package for imports instead encoding/json.
   --prefix value                                             Adds a prefix with a user one. If you would like to replace the prefix, then combine this option with --noprefix.
   --names                                                    Generates a 'Names() []string' function, and adds the possible enum values in the error response during parsing (default: false)
   --values                                                   Generates a 'Values() []{{ENUM}}' function. (default: false)
   --nocamel                                                  Removes the snake_case to CamelCase name changing (default: false)
   --ptr                                                      Adds a pointer method to get a pointer from const values (default: false)
   --sqlnullint                                               Adds a Null{{ENUM}} type for marshalling a nullable int value to sql (default: false)
   --sqlnullstr                                               Adds a Null{{ENUM}} type for marshalling a nullable string value to sql.  If sqlnullint is specified too, it will be Null{{ENUM}}Str (default: false)
   --template value, -t value [ --template value, -t value ]  Additional template file(s) to generate enums.  Use more than one flag for more files. Templates will be executed in alphabetical order.
   --alias value, -a value [ --alias value, -a value ]        Adds or replaces aliases for a non alphanumeric value that needs to be accounted for. [Format should be "key:value,key2:value2", or specify multiple entries, or both!]
   --mustparse                                                Adds a Must version of the Parse that will panic on failure. (default: false)
   --forcelower                                               Forces a camel cased comment to generate lowercased names. (default: false)
   --forceupper                                               Forces a camel cased comment to generate uppercased names. (default: false)
   --nocomments                                               Removes auto generated comments.  If you add your own comments, these will still be created. (default: false)
   --buildtag value, -b value [ --buildtag value, -b value ]  Adds build tags to a generated enum file.
   --output-suffix .go                                        Changes the default filename suffix of _enum to something else.  .go will be appended to the end of the string no matter what, so that `_test.go` cases can be accommodated
   --no-iota                                                  Disables the use of iota in generated enums. (default: false)
   --help, -h                                                 show help
   --version, -v                                              print the version
```

### Syntax

The parser looks for comments on your type defs and parse the enum declarations from it.
The parser will look for `ENUM(` and continue to look for comma separated values until it finds a `)`.  You can put values on the same line, or on multiple lines.\
If you need to have a specific value jump in the enum, you can now specify that by adding `=numericValue` to the enum declaration.  Keep in mind, this resets the data for all following values.  So if you specify `50` in the middle of an enum, each value after that will be `51, 52, 53...`

[Examples can be found in the example folder](./example/)

#### Comments

You can use comments inside enum that start with `//`\
The comment must be at the end of the same line as the comment value, only then it will be added as a comment to the generated constant.

```go
// Commented is an enumeration of commented values
/*
ENUM(
value1 // Commented value 1
value2
value3 // Commented value 3
)
*/
type Commented int
```

The generated comments in code will look something like:

```go
...
const (
    // CommentedValue1 is a Commented of type Value1
    // Commented value 1
    CommentedValue1 Commented = iota
    // CommentedValue2 is a Commented of type Value2
    CommentedValue2
    // CommentedValue3 is a Commented of type Value3
    // Commented value 3
    CommentedValue3
)
...
```

#### Example

There are a few examples in the `example` [directory](./example/).
I've included one here for easy access, but can't guarantee it's up to date.

``` go
// Color is an enumeration of colors that are allowed.
/* ENUM(
Black, White, Red
Green = 33 // Green starts with 33
*/
// Blue
// grey=
// yellow
// blue-green
// red-orange
// yellow_green
// red-orange-blue
// )
type Color int32
```

The generated code will look something like:

``` go
// Code generated by go-enum DO NOT EDIT.
// Version: example
// Revision: example
// Build Date: example
// Built By: example

package example

import (
 "fmt"
 "strings"
)

const (
 // ColorBlack is a Color of type Black.
 ColorBlack Color = iota
 // ColorWhite is a Color of type White.
 ColorWhite
 // ColorRed is a Color of type Red.
 ColorRed
 // ColorGreen is a Color of type Green.
 // Green starts with 33
 ColorGreen Color = iota + 30
 // ColorBlue is a Color of type Blue.
 ColorBlue
 // ColorGrey is a Color of type Grey.
 ColorGrey
 // ColorYellow is a Color of type Yellow.
 ColorYellow
 // ColorBlueGreen is a Color of type Blue-Green.
 ColorBlueGreen
 // ColorRedOrange is a Color of type Red-Orange.
 ColorRedOrange
 // ColorYellowGreen is a Color of type Yellow_green.
 ColorYellowGreen
 // ColorRedOrangeBlue is a Color of type Red-Orange-Blue.
 ColorRedOrangeBlue
)

const _ColorName = "BlackWhiteRedGreenBluegreyyellowblue-greenred-orangeyellow_greenred-orange-blue"

var _ColorMap = map[Color]string{
 ColorBlack:         _ColorName[0:5],
 ColorWhite:         _ColorName[5:10],
 ColorRed:           _ColorName[10:13],
 ColorGreen:         _ColorName[13:18],
 ColorBlue:          _ColorName[18:22],
 ColorGrey:          _ColorName[22:26],
 ColorYellow:        _ColorName[26:32],
 ColorBlueGreen:     _ColorName[32:42],
 ColorRedOrange:     _ColorName[42:52],
 ColorYellowGreen:   _ColorName[52:64],
 ColorRedOrangeBlue: _ColorName[64:79],
}

// String implements the Stringer interface.
func (x Color) String() string {
 if str, ok := _ColorMap[x]; ok {
  return str
 }
 return fmt.Sprintf("Color(%d)", x)
}

var _ColorValue = map[string]Color{
 _ColorName[0:5]:                    ColorBlack,
 strings.ToLower(_ColorName[0:5]):   ColorBlack,
 _ColorName[5:10]:                   ColorWhite,
 strings.ToLower(_ColorName[5:10]):  ColorWhite,
 _ColorName[10:13]:                  ColorRed,
 strings.ToLower(_ColorName[10:13]): ColorRed,
 _ColorName[13:18]:                  ColorGreen,
 strings.ToLower(_ColorName[13:18]): ColorGreen,
 _ColorName[18:22]:                  ColorBlue,
 strings.ToLower(_ColorName[18:22]): ColorBlue,
 _ColorName[22:26]:                  ColorGrey,
 strings.ToLower(_ColorName[22:26]): ColorGrey,
 _ColorName[26:32]:                  ColorYellow,
 strings.ToLower(_ColorName[26:32]): ColorYellow,
 _ColorName[32:42]:                  ColorBlueGreen,
 strings.ToLower(_ColorName[32:42]): ColorBlueGreen,
 _ColorName[42:52]:                  ColorRedOrange,
 strings.ToLower(_ColorName[42:52]): ColorRedOrange,
 _ColorName[52:64]:                  ColorYellowGreen,
 strings.ToLower(_ColorName[52:64]): ColorYellowGreen,
 _ColorName[64:79]:                  ColorRedOrangeBlue,
 strings.ToLower(_ColorName[64:79]): ColorRedOrangeBlue,
}

// ParseColor attempts to convert a string to a Color
func ParseColor(name string) (Color, error) {
 if x, ok := _ColorValue[name]; ok {
  return x, nil
 }
 return Color(0), fmt.Errorf("%s is not a valid Color", name)
}

func (x Color) Ptr() *Color {
 return &x
}

// MarshalText implements the text marshaller method
func (x Color) MarshalText() ([]byte, error) {
 return []byte(x.String()), nil
}

// UnmarshalText implements the text unmarshaller method
func (x *Color) UnmarshalText(text []byte) error {
 name := string(text)
 tmp, err := ParseColor(name)
 if err != nil {
  return err
 }
 *x = tmp
 return nil
}
```


go-enum

# go-linq [![GoDoc](https://godoc.org/github.com/ahmetb/go-linq?status.svg)](https://godoc.org/github.com/ahmetb/go-linq) [![Build Status](https://github.com/ahmetb/go-linq/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/ahmetb/go-linq/actions/workflows/ci.yml) [![Coverage Status](https://coveralls.io/repos/github/ahmetb/go-linq/badge.svg?branch=master)](https://coveralls.io/github/ahmetb/go-linq?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/ahmetb/go-linq)](https://goreportcard.com/report/github.com/ahmetb/go-linq)

A powerful language integrated query (LINQ) library for Go.

* Written in vanilla Go, no dependencies!
* Complete lazy evaluation with iterator pattern
* Safe for concurrent use
* Supports generic functions to make your code cleaner and free of type assertions
* Supports arrays, slices, maps, strings, channels and custom collections

## Installation

When used with Go modules, use the following import path:

    go get github.com/ahmetb/go-linq/v4

Older versions of Go using different dependency management tools can use the
following import path to prevent breaking API changes:

    go get gopkg.in/ahmetb/go-linq.v4

## Quickstart

Usage is as easy as chaining methods like:

`From(slice)` `.Where(predicate)` `.Select(selector)` `.Union(data)`

**Example 1: Find all owners of cars manufactured after 2015**

```go
import . "github.com/ahmetb/go-linq/v4"

type Car struct {
    year int
    owner, model string
}

...


var owners []string

FromSlice(cars).Where(func(c any) bool {
	return c.(Car).year >= 2015
}).Select(func(c any) any {
	return c.(Car).owner
}).ToSlice(&owners)
```

Or, you can use generic functions, like `WhereT` and `SelectT` to simplify your code
(at a performance penalty):

```go
var owners []string

FromSlice(cars).WhereT(func(c Car) bool {
	return c.year >= 2015
}).SelectT(func(c Car) string {
	return c.owner
}).ToSlice(&owners)
```

**Example 2: Find the author who has written the most books**

```go
import . "github.com/ahmetb/go-linq/v4"

type Book struct {
	id      int
	title   string
	authors []string
}

author := FromSlice(books).SelectMany( // make a flat array of authors
	func(book any) Query {
		return From(book.(Book).authors)
	}).GroupBy( // group by author
	func(author any) any {
		return author // author as key
	}, func(author any) any {
		return author // author as value
	}).OrderByDescending( // sort groups by its length
	func(group any) any {
		return len(group.(Group).Group)
	}).Select( // get authors out of groups
	func(group any) any {
		return group.(Group).Key
	}).First() // take the first author
```

**Example 3: Implement a custom method that leaves only values greater than the specified threshold**

```go
type MyQuery Query

func (q MyQuery) GreaterThan(threshold int) Query {
    return Query{
        Iterate: func(yield func(any) bool) {
            q.Iterate(func(item any) bool {
                if item.(int) > threshold {
                    return yield(item)
                }
                return true
            })
        },
    }
}

result := MyQuery(Range(1,10)).GreaterThan(5).Results()
```

## Generic Functions

Although Go doesn't implement generics, with some reflection tricks, you can use go-linq without
typing `any`s and type assertions. This will introduce a performance penalty (5x-10x slower)
but will yield in a cleaner and more readable code.

Methods with `T` suffix (such as `WhereT`) accept functions with generic types. So instead of

    .Select(func(v any) any {...})

you can type:

    .SelectT(func(v YourType) YourOtherType {...})

This will make your code free of `any` and type assertions.

**Example 4: "MapReduce" in a slice of string sentences to list the top 5 most used words using generic functions**

```go
var results []string

FromSlice(sentences).
	// split sentences to words
	SelectManyT(func(sentence string) Query {
		return From(strings.Split(sentence, " "))
	}).
	// group the words
	GroupByT(
		func(word string) string { return word },
		func(word string) string { return word },
	).
	// order by count
	OrderByDescendingT(func(wordGroup Group) int {
		return len(wordGroup.Group)
	}).
	// order by the word
	ThenByT(func(wordGroup Group) string {
		return wordGroup.Key.(string)
	}).
	Take(5).  // take the top 5
	// project the words using the index as rank
	SelectIndexedT(func(index int, wordGroup Group) string {
		return fmt.Sprintf("Rank: #%d, Word: %s, Counts: %d", index+1, wordGroup.Key, len(wordGroup.Group))
	}).
	ToSlice(&results)
```

## Manual Iteration

Since **go-linq v4** manual iteration follows Go’s standard iterator pattern introduced with the `iter` package.
The Query type exposes an `Iterate` field of type `iter.Seq[any]`, making it easier to integrate with Go’s native
iteration style.

**Example 5: Iterate over a query using the standard `for ... range` loop**

```go
q := FromSlice([]int{1, 2, 3, 4})

for v := range q.Iterate {
	fmt.Println(v)
}
```

**More examples** can be found in the [documentation](https://godoc.org/github.com/ahmetb/go-linq).

## Data Source Constructors

Since **go-linq v4**, a new family of constructor functions provides a type-safe and efficient way to create queries from
various data sources. Each function is optimized for its specific input type, avoiding the overhead of reflection.

Available constructors:
- `FromSlice` - creates a query from a slice
- `FromMap` - creates a query from a map
- `FromChannel` - creates a query from a channel
- `FromChannelWithContext` - creates a query from a channel with `Context` support
- `FromString` - creates a query from a string (iterating over runes)
- `FromIterable` - creates a query from a custom collection implementing the `Iterable` interface

The older `From` function remains available for backward compatibility, but it relies on runtime reflection and is
significantly less efficient. For all new code, it’s recommended to use the explicit `From*` constructors.

## Release Notes

```text
v4.0.0 (2025-10-12)
* Breaking change: Migrated to standard Go iterator pattern. (thanks @kalaninja!)
* Added typed constructors: FromSlice(), FromMap(), FromChannel(),
 FromChannelWithContext(), FromString().
* Breaking change: Removed FromChannelT() in favor of FromChannel().

v3.2.0 (2020-12-29)
* Added FromChannelT().
* Added DefaultIfEmpty().

v3.1.0 (2019-07-09)
* Support for Go modules
* Added IndexOf()/IndexOfT().

v3.0.0 (2017-01-10)
* Breaking change: ToSlice() now overwrites existing slice starting
  from index 0 and grows/reslices it as needed.
* Generic methods support (thanks @cleitonmarx!)
  - Accepting parametrized functions was originally proposed in #26
  - You can now avoid type assertions and interface{}s
  - Functions with generic methods are named as "MethodNameT" and
    signature for the existing LINQ methods are unchanged.
* Added ForEach(), ForEachIndexed() and AggregateWithSeedBy().

v2.0.0 (2016-09-02)
* IMPORTANT: This release is a BREAKING CHANGE. The old version
  is archived at the 'archive/0.9' branch or the 0.9 tags.
* A COMPLETE REWRITE of go-linq with better performance and memory
  efficiency. (thanks @kalaninja!)
* API has significantly changed. Most notably:
  - linq.T removed in favor of interface{}
  - library methods no longer return errors
  - PLINQ removed for now (see channels support)
  - support for channels, custom collections and comparables

v0.9-rc4
* GroupBy()

v0.9-rc3.2
* bugfix: All() iterating over values instead of indices

v0.9-rc3.1
* bugfix: modifying result slice affects subsequent query methods

v0.9-rc3
* removed FirstOrNil, LastOrNil, ElementAtOrNil methods

v0.9-rc2.5
* slice-accepting methods accept slices of any type with reflections

v0.9-rc2
* parallel linq (plinq) implemented
* Queryable separated into Query & ParallelQuery
* fixed early termination for All

v0.9-rc1
* many linq methods are implemented
* methods have error handling support
* type assertion limitations are unresolved
* travis-ci.org build integrated
* open sourced on github, master & dev branches
```


go-linq

# goderive

[![Build Status](https://github.com/awalterschulze/goderive/actions/workflows/go.yaml/badge.svg?branch=master)](https://github.com/awalterschulze/goderive/actions)
[![Go Report Card](https://goreportcard.com/badge/github.com/awalterschulze/goderive)](https://goreportcard.com/report/github.com/awalterschulze/goderive)
[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=flat-square.svg)](https://godoc.org/github.com/awalterschulze/goderive)

`goderive` derives mundane golang functions that you do not want to maintain and keeps them up to date.

<a href="http://www.youtube.com/watch?feature=player_embedded&v=qFYByoGFIUE" target="_blank">
 <img src="https://img.youtube.com/vi/qFYByoGFIUE/maxres2.jpg" alt="Watch the video" width="480" border="10" />
</a>

It does this by parsing your go code for functions, which are not implemented, and then generates these functions for you by deriving their implementations from the input parameter types.

## Examples

In the following code the `deriveEqual` function will be spotted as a function that was not implemented (or was previously derived) and has a prefix `deriveEqual`.

```go
package main

type MyStruct struct {
	Int64 int64
	StringPtr *string
}

func (this *MyStruct) Equal(that *MyStruct) bool {
	return deriveEqual(this, that)
}
```

goderive will then generate the following code in a `derived.gen.go` file in the same package:

```go
func deriveEqual(this, that *MyStruct) bool {
	return (this == nil && that == nil) ||
		this != nil && that != nil &&
			this.Int64 == that.Int64 &&
			((this.StringPtr == nil && that.StringPtr == nil) ||
 (this.StringPtr != nil && that.StringPtr != nil && *(this.StringPtr) == *(that.StringPtr)))
}
```

Recursive Examples:

 - [Equal](https://github.com/awalterschulze/goderive/tree/master/example/plugin/equal)
 - [Compare](https://github.com/awalterschulze/goderive/tree/master/example/plugin/compare)
 - [DeepCopy](https://github.com/awalterschulze/goderive/tree/master/example/plugin/deepcopy)
 - [GoString](https://github.com/awalterschulze/goderive/tree/master/example/plugin/gostring)
 - [Hash](https://github.com/awalterschulze/goderive/tree/master/example/plugin/hash)

Set Examples:

 - [Keys](https://github.com/awalterschulze/goderive/tree/master/example/plugin/keys)
 - [Sort](https://github.com/awalterschulze/goderive/tree/master/example/plugin/sort)
 - [Unique](https://github.com/awalterschulze/goderive/tree/master/example/plugin/unique)
 - [Set](https://github.com/awalterschulze/goderive/tree/master/example/plugin/set)
 - [Min](https://github.com/awalterschulze/goderive/tree/master/example/plugin/min)
 - [Max](https://github.com/awalterschulze/goderive/tree/master/example/plugin/max)
 - [Contains](https://github.com/awalterschulze/goderive/tree/master/example/plugin/contains)
 - [Intersect](https://github.com/awalterschulze/goderive/tree/master/example/plugin/intersect)
 - [Union](https://github.com/awalterschulze/goderive/tree/master/example/plugin/union)

Functional Examples:

 - [Compose](https://github.com/awalterschulze/goderive/tree/master/example/plugin/compose)
 - [Mem](https://github.com/awalterschulze/goderive/tree/master/example/plugin/mem)
 - [Traverse](https://github.com/awalterschulze/goderive/tree/master/example/plugin/traverse)
 - [ToError](https://github.com/awalterschulze/goderive/tree/master/example/plugin/toerror)

Concurrency Examples:

 - [Pipeline](https://github.com/awalterschulze/goderive/tree/master/example/plugin/pipeline)
 - [Do](https://github.com/awalterschulze/goderive/tree/master/example/plugin/do)

## Functions

Recursive Functions:

 - [Equal](http://godoc.org/github.com/awalterschulze/goderive/plugin/equal)
 - `deriveEqual(T, T) bool`
 - `deriveEqual(T) func(T) bool`
 - [Compare](http://godoc.org/github.com/awalterschulze/goderive/plugin/compare)
 - `deriveCompare(T, T) int`
 - `deriveCompare(T) func(T) int`
 - [DeepCopy](http://godoc.org/github.com/awalterschulze/goderive/plugin/deepcopy)
 - `deriveDeepCopy(dst *T, src *T)`
 - `deriveDeepCopy(dst []T, src []T)`
 - `deriveDeepCopy(dst map[A]B, src map[A]B)`
 - [Clone](http://godoc.org/github.com/awalterschulze/goderive/plugin/clone) `deriveClone(T) T`
 - [GoString](http://godoc.org/github.com/awalterschulze/goderive/plugin/gostring) `deriveGoString(T) string`
 - [Hash](http://godoc.org/github.com/awalterschulze/goderive/plugin/hash) `deriveHash(T) uint64`

Functional Functions:

 - [Fmap](http://godoc.org/github.com/awalterschulze/goderive/plugin/fmap)
 - `deriveFmap(func(A) B, []A) []B`
 - `deriveFmap(func(rune) B, string) []B`
 - `deriveFmap(func(A) B, func() (A, error)) (B, error)`
 - `deriveFmap(func(A) (B, error), func() (A, error)) (func() (B, error), error)`
 - `deriveFmap(func(A), func() (A, error)) error`
 - `deriveFmap(func(A) (B, c, d, ...), func() (A, error)) (func() (B, c, d, ...), error)`
 - [Join](http://godoc.org/github.com/awalterschulze/goderive/plugin/join)
 - `deriveJoin([][]T) []T`
 - `deriveJoin([]string) string`
 - `deriveJoin(func() (T, error), error) func() (T, error)`
 - `deriveJoin(func() (T, ..., error), error) func() (T, ..., error)`
 - [Flip](http://godoc.org/github.com/awalterschulze/goderive/plugin/flip) `deriveFlip(f func(A, B, ...) T) func(B, A, ...) T`
 - [Curry](http://godoc.org/github.com/awalterschulze/goderive/plugin/curry) `deriveCurry(f func(A, B, ...) T) func(A) func(B, ...) T`
 - [Uncurry](http://godoc.org/github.com/awalterschulze/goderive/plugin/uncurry) `deriveUncurry(f func(A) func(B, ...) T) func(A, B, ...) T`
 - [Tuple](http://godoc.org/github.com/awalterschulze/goderive/plugin/tuple) `deriveTuple(A, B, ...) func() (A, B, ...)`
 - [Compose](http://godoc.org/github.com/awalterschulze/goderive/plugin/compose)
 - `deriveCompose(func() (A, error), func(A) (B, error)) func() (B, error)`
 - `deriveCompose(func(A) (B, error), func(B) (C, error)) func(A) (C, error)`
 - `deriveCompose(func(A...) (B..., error), func(B...) (C..., error)) func(A...) (C..., error)`
 - `deriveCompose(func(A...) (B..., error), ..., func(C...) (D..., error)) func(A...) (D..., error)`
 - [Mem](http://godoc.org/github.com/awalterschulze/goderive/plugin/mem)
 - `deriveMem(func(A...) (B...)) func(A...) (B...)`
 - [Traverse](http://godoc.org/github.com/awalterschulze/goderive/plugin/traverse)
 - `deriveTraverse(func(A) (B, error), []A) ([]B, error)`
 - [ToError](http://godoc.org/github.com/awalterschulze/goderive/plugin/toerror)
 - `deriveToError(error, func(A...) (B..., bool)) func(A...) (B..., error)`
 - `deriveToError(error, func() bool) func() error`
 - [Apply](http://godoc.org/github.com/awalterschulze/goderive/plugin/apply) `deriveApply(f func(...A, B) C, B) func(...A) C`

Concurrency Functions:
 - [Fmap](http://godoc.org/github.com/awalterschulze/goderive/plugin/fmap)
 - `deriveFmap(func(A) B, <-chan A) <-chan B`
 - [Join](http://godoc.org/github.com/awalterschulze/goderive/plugin/join)
 - `deriveJoin(<-chan <-chan T) <-chan T`
 - `deriveJoin(chan <-chan T) <-chan T`
 - `deriveJoin([]<-chan T) <-chan T`
 - `deriveJoin([]chan T) <-chan T`
 - `deriveJoin(chan T, chan T, ...) <-chan T`
 - [Pipeline](http://godoc.org/github.com/awalterschulze/goderive/plugin/pipeline)
 - `derivePipeline(func(A) <-chan B, func(B) <-chan C) func(A) <-chan C`
 - [Do](http://godoc.org/github.com/awalterschulze/goderive/plugin/do)
 - `deriveDo(func() (A, error), func (B, error)) (A, B, error)`
 - [Dup](http://godoc.org/github.com/awalterschulze/goderive/plugin/dup)
 - `deriveDup(c <-chan T) (c1, c2 <-chan T)`

Deprecated in favour of generics:

 - [Keys](http://godoc.org/github.com/awalterschulze/goderive/plugin/keys) `deriveKeys(map[K]V) []K`
 - [Sort](http://godoc.org/github.com/awalterschulze/goderive/plugin/sort) `deriveSort([]T) []T`
 - [Unique](http://godoc.org/github.com/awalterschulze/goderive/plugin/unique) `deriveUnique([]T) []T`
 - [Set](http://godoc.org/github.com/awalterschulze/goderive/plugin/set) `deriveSet([]T) map[T]struct{}`
 - [Min](http://godoc.org/github.com/awalterschulze/goderive/plugin/min)
 - `deriveMin(list []T, default T) (min T)`
 - `deriveMin(T, T) T`
 - [Max](http://godoc.org/github.com/awalterschulze/goderive/plugin/max)
 - `deriveMax(list []T, default T) (max T)`
 - `deriveMax(T, T) T`
 - [Contains](http://godoc.org/github.com/awalterschulze/goderive/plugin/contains) `deriveContains([]T, T) bool`
 - [Intersect](http://godoc.org/github.com/awalterschulze/goderive/plugin/intersect)
 - `deriveIntersect(a, b []T) []T`
 - `deriveIntersect(a, b map[T]struct{}) map[T]struct{}`
 - [Union](http://godoc.org/github.com/awalterschulze/goderive/plugin/union)
 - `deriveUnion(a, b []T) []T`
 - `deriveUnion(a, b map[T]struct{}) map[T]struct{}`
 - [Filter](http://godoc.org/github.com/awalterschulze/goderive/plugin/filter) `deriveFilter(pred func(T) bool, []T) []T`
 - [All](http://godoc.org/github.com/awalterschulze/goderive/plugin/all) `deriveAll(pred func(T) bool, []T) bool`
 - [Any](http://godoc.org/github.com/awalterschulze/goderive/plugin/any) `deriveAny(pred func(T) bool, []T) bool`
 - [TakeWhile](http://godoc.org/github.com/awalterschulze/goderive/plugin/takewhile) `deriveTakeWhile(pred func(T) bool, []T) []T`

When goderive walks over your code it is looking for a function that:
 - was not implemented (or was previously derived) and
 - has a predefined prefix.

Functions which have been previously derived will be regenerated to keep them up to date with the latest modifications to your types. This keeps these functions, which are truly mundane to write, maintainable.

For example when someone in your team adds a new field to a struct and forgets to update the CopyTo method. This problem is solved by goderive, by generating generated functions given the new types.

Function prefixes are by default `deriveCamelCaseFunctionName`, for example `deriveEqual`.
These are customizable using command line flags.

You can derive functions for different types by using different suffixes with the same prefix. For example, if you wish to derive `Equal` for types `MyStruct` and `MySecondStruct`, name the functions `deriveEqualMyStruct` and `deriveEqualMySecondStruct` and `goderive` will derive both.

Let `goderive` edit your function names in your source code, by enabling `autoname` and `dedup` using the command line flags.
These flags respectively make sure that your functions have unique names and that you don't generate multiple functions that do the same thing.

## How to run

install the latest version of goderive globally using:

`go install github.com/awalterschulze/goderive@latest`

goderive can be run from the command line:

`goderive ./...`

, using the same path semantics as the go tool.

[You can also run goderive using go generate](https://github.com/awalterschulze/goderive/blob/master/example/gogenerate/example.go)

[And you can customize specific function prefixes](https://github.com/awalterschulze/goderive/blob/master/example/pluginprefix/Makefile)

[Or you can customize all function prefixes](https://github.com/awalterschulze/goderive/blob/master/example/prefix/Makefile)

You can let goderive rename your functions using the `-autoname` and `-dedup` flags.
If these flags are not used, goderive will not touch your code and rather return an error.

## Customization

The derive package allows you to create your own code generator plugins, see all the current plugins for examples.

You can also create your own vanity binary.
Including your own generators and/or customization of function prefixes, etc.
This should be easy to figure out by looking at [main.go](https://github.com/awalterschulze/goderive/blob/master/main.go)

## Inspired By

 - Haskell's deriving
 - Robert Griesemer's talk [Prototype your design!](https://www.youtube.com/watch?v=vLxX3yZmw5Q)
 - [go/types](https://golang.org/pkg/go/types/) standard library

## Users

These projects use goderive:

 - [DC/OS](https://github.com/dcos/dcos-cli/blob/af0434c0ca80cee7152a1880770dc878501b9ac5/pkg/httpclient/derived.gen.go)
 - [katydid](https://github.com/katydid/katydid/blob/master/relapse/ast/derived.gen.go)
 - [go-geom](https://github.com/twpayne/go-geom/blob/master/derived.gen.go)
 - [gominikanren](https://github.com/awalterschulze/gominikanren/blob/master/micro/derived.gen.go)

Please let us know if you are using goderive by opening an issue or a pull request that adds your project to the list.

## Mentioned

 - [Monads for Go Programmers](https://medium.com/@awalterschulze/monads-for-go-programmers-6cda2b978cb1)
 - [Golang Weekly](https://golangweekly.com/issues/174)
 - [Reddit](https://www.reddit.com/r/programmingcirclejerk/comments/6vkkdw/this_is_what_goprogrammers_have_to_do_because/)
 - [Generating `Equal` methods for Go structs with `goderive`](https://www.jvt.me/posts/2023/03/27/go-generate-equal-goderive/)

Please let us know if you mention goderive in a blog post, talk or go experience report, so that we can add a link to our list.

## Presentations

 - 2021-12: [goderive: Code generation with Gonads](https://www.youtube.com/watch?v=qFYByoGFIUE) - Go Cape Town meetup ([code examples](https://github.com/awalterschulze/goderive/blob/master/example/talk))

goderive

Generate converters by defining an interface

<img width="300" src=".github/logo.svg" />


<h1 align="center">goverter</h1>
a "type-safe Go converter" generator

 <a href="https://github.com/jmattheis/goverter/actions/workflows/build.yml">
 <img alt="Build Status" src="https://github.com/jmattheis/goverter/actions/workflows/build.yml/badge.svg">
 </a>
 <a href="https://codecov.io/gh/jmattheis/goverter">
 <img alt="codecov" src="https://codecov.io/gh/jmattheis/goverter/branch/main/graph/badge.svg">
 </a>
 <a href="https://goreportcard.com/report/github.com/jmattheis/goverter">
 <img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/jmattheis/goverter">
 </a>
 <a href="https://pkg.go.dev/github.com/jmattheis/goverter">
 <img alt="Go Reference" src="https://pkg.go.dev/badge/github.com/jmattheis/goverter.svg">
 </a>
 <a href="https://github.com/jmattheis/goverter/releases/latest">
 <img alt="latest release" src="https://img.shields.io/github/release/jmattheis/goverter.svg">
 </a>


goverter is a tool for creating type-safe converters. All you have to
do is create an interface and execute goverter. The project is meant as
alternative to [jinzhu/copier](https://github.com/jinzhu/copier) that doesn't
use reflection.

[Getting Started](https://goverter.jmattheis.de/guide/getting-started) ᛫
[Installation](https://goverter.jmattheis.de/guide/install) ᛫
[CLI](https://goverter.jmattheis.de/reference/cli) ᛫
[Config](https://goverter.jmattheis.de/reference/settings)

## Features

- **Fast execution**: No reflection is used at runtime
- Automatically converts builtin types: slices, maps, named types, primitive
 types, pointers, structs with same fields
- [Enum support](https://goverter.jmattheis.de/guide/enum)
- [Deep copies](https://en.wikipedia.org/wiki/Object_copying#Deep_copy) per
 default and supports [shallow
 copying](https://en.wikipedia.org/wiki/Object_copying#Shallow_copy)
- **Customizable**: [You can implement custom converter methods](https://goverter.jmattheis.de/reference/extend)
- [Clear errors when generating the conversion methods](https://goverter.jmattheis.de/guide/error-early) if
 - the target struct has unmapped fields
 - types cannot be converted without losing information
- Detailed [documentation](https://goverter.jmattheis.de/) with a lot examples
- Thoroughly tested, see [our test scenarios](./scenario)

## Example

Given this converter:

```go
package example

// goverter:converter
type Converter interface {
 ConvertItems(source []Input) []Output

 // goverter:ignore Irrelevant
 // goverter:map Nested.AgeInYears Age
 Convert(source Input) Output
}

type Input struct {
 Name string
 Nested InputNested
}
type InputNested struct {
 AgeInYears int
}
type Output struct {
 Name string
 Age int
 Irrelevant bool
}
```

Goverter will generated these conversion methods:

```go
package generated

import example "goverter/example"

type ConverterImpl struct{}

func (c *ConverterImpl) Convert(source example.Input) example.Output {
 var exampleOutput example.Output
 exampleOutput.Name = source.Name
 exampleOutput.Age = source.Nested.AgeInYears
 return exampleOutput
}
func (c *ConverterImpl) ConvertItems(source []example.Input) []example.Output {
 var exampleOutputList []example.Output
 if source != nil {
 exampleOutputList = make([]example.Output, len(source))
 for i := 0; i < len(source); i++ {
 exampleOutputList[i] = c.Convert(source[i])
 }
 }
 return exampleOutputList
}
```

See [Getting Started](https://goverter.jmattheis.de/guide/getting-started).

## Versioning

goverter uses [SemVer](http://semver.org/) for versioning the cli.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE)
file for details

_Logo by [MariaLetta](https://github.com/MariaLetta)_

goverter

Code generation for enum encoding from code comments

# go-enum-encoding


 ✨ Sponsored by <a href="https://apps.apple.com/app/id6738306589">NDX AI Shopping Assistant</a>


[![Go Report Card](https://goreportcard.com/badge/github.com/nikolaydubina/go-enum-encoding)](https://goreportcard.com/report/github.com/nikolaydubina/go-enum-encoding)
[![Go Reference](https://pkg.go.dev/badge/github.com/nikolaydubina/go-enum-encoding.svg)](https://pkg.go.dev/github.com/nikolaydubina/go-enum-encoding)
[![codecov](https://codecov.io/gh/nikolaydubina/go-enum-encoding/graph/badge.svg?token=asZfIddrLV)](https://codecov.io/gh/nikolaydubina/go-enum-encoding)
[![go-recipes](https://raw.githubusercontent.com/nikolaydubina/go-recipes/main/badge.svg?raw=true)](https://github.com/nikolaydubina/go-recipes)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nikolaydubina/go-enum-encoding/badge)](https://securityscorecards.dev/viewer/?uri=github.com/nikolaydubina/go-enum-encoding)

```bash
go install github.com/nikolaydubina/go-enum-encoding@latest
```

* 200 LOC
* simple, fast, strict
* generate encoding/decoding, tests, benchmarks

```go
type Color struct{ c uint8 }

//go:generate go-enum-encoding -type=Color
var (
	UndefinedColor = Color{} 	// json:""
	Red = Color{1}	// json:"red"
	Green = Color{2}	// json:"green"
	Blue = Color{3}	// json:"blue"
)
```

`iota` is ok too

```go
type Size uint8

//go:generate go-enum-encoding -type=Size
const (
	UndefinedSize Size = iota // json:""
	Small // json:"small"
	Large // json:"large"
	XLarge // json:"xlarge"
)
```

generated benchmarks

```bash
$ go test -bench=. -benchmem . 
goos: darwin
goarch: arm64
pkg: github.com/nikolaydubina/go-enum-encoding/internal/testdata
cpu: Apple M3 Max
BenchmarkColor_UnmarshalText-16 752573839 1.374 ns/op 0 B/op 0 allocs/op
BenchmarkColor_AppendText-16 450123993 2.676 ns/op 0 B/op 0 allocs/op
BenchmarkColor_MarshalText-16 80059376 13.68 ns/op 8 B/op 1 allocs/op
BenchmarkImageSize_UnmarshalText-16 751743885 1.601 ns/op 0 B/op 0 allocs/op
BenchmarkImageSize_AppendText-16 500286883 2.402 ns/op 0 B/op 0 allocs/op
BenchmarkImageSize_MarshalText-16 81467318 16.46 ns/op 8 B/op 1 allocs/op
BenchmarkImageSize_String-16 856463289 1.330 ns/op 0 B/op 0 allocs/op
PASS
ok github.com/nikolaydubina/go-enum-encoding/internal/testdata 8.561s
```

## References

- http://github.com/zarldev/goenums - does much more advanced struct generation, generates all enum utilities besides encoding, does not generate tests, uses similar notation to trigger go:generate but with different comment directives (non-json field tags)
- http://github.com/nikolaydubina/go-enum-example

go-enum-encoding

Command line tool for generating interface definitions

# interfaces [![GoDoc](https://godoc.org/github.com/rjeczalik/interfaces?status.png)](https://godoc.org/github.com/rjeczalik/interfaces) [![Build Status](https://img.shields.io/travis/rjeczalik/interfaces/master.svg)](https://travis-ci.org/rjeczalik/interfaces "linux_amd64") [![Build status](https://img.shields.io/appveyor/ci/rjeczalik/interfaces.svg)](https://ci.appveyor.com/project/rjeczalik/interfaces "windows_amd64")
Code generation tools for Go's interfaces.

Tools available in this repository:

- [cmd/interfacer](#cmdinterfacer-)
- [cmd/structer](#cmdstructer-)

### cmd/interfacer [![GoDoc](https://godoc.org/github.com/rjeczalik/interfaces/cmd/interfacer?status.png)](https://godoc.org/github.com/rjeczalik/interfaces/cmd/interfacer)

Generates an interface for a named type.

*Installation*
```bash
~ $ go install github.com/rjeczalik/interfaces/cmd/interfacer@latest
```

*Usage*

```bash
~ $ interfacer -help
```
```
Usage of interfacer:
  -all
        Include also unexported methods.
  -as string
        Generated interface name. (default "main.Interface")
  -for string
        Type to generate an interface for.
  -o string
        Output file. (default "-")
```

*Example*
- generate by manually
```bash
~ $ interfacer -for os.File -as mock.File
```
- generate by go generate
```go
//go:generate interfacer -for os.File -as mock.File -o file_iface.go
```
```bash
~ $ go generate  ./...
```
- output
```go
// Created by interfacer; DO NOT EDIT

package mock

import (
        "os"
)

// File is an interface generated for "os".File.
type File interface {
        Chdir() error
        Chmod(os.FileMode) error
        Chown(int, int) error
        Close() error
        Fd() uintptr
        Name() string
        Read([]byte) (int, error)
        ReadAt([]byte, int64) (int, error)
        Readdir(int) ([]os.FileInfo, error)
        Readdirnames(int) ([]string, error)
        Seek(int64, int) (int64, error)
        Stat() (os.FileInfo, error)
        Sync() error
        Truncate(int64) error
        Write([]byte) (int, error)
        WriteAt([]byte, int64) (int, error)
        WriteString(string) (int, error)
}
```

### cmd/structer [![GoDoc](https://godoc.org/github.com/rjeczalik/interfaces/cmd/structer?status.png)](https://godoc.org/github.com/rjeczalik/interfaces/cmd/structer)

Generates a struct for a formatted file. Currently supported formats are:

- CSV

*Installation*
```bash
~ $ go get github.com/rjeczalik/interfaces/cmd/structer
```

*Usage*

```bash
~ $ structer -help
```
```
Usage of structer:
  -as string
        Generated struct name. (default "main.Struct")
  -f string
        Input file. (default "-")
  -o string
        Output file. (default "-")
  -tag string
        Name for a struct tag to add to each field.
  -type string
        Type of the input, overwrites inferred from file name.
```

*Example*

```bash
~ $ head -2 aws-billing.csv         # first line is a CSV header, second - first line of values
```
```
"InvoiceID","PayerAccountId","LinkedAccountId","RecordType","RecordID","BillingPeriodStartDate","BillingPeriodEndDate","InvoiceDate"
"Estimated","123456","","PayerLineItem","5433212345","2016/01/01 00:00:00","2016/01/31 23:59:59","2016/01/21 19:19:06"
```
```bash
~ $ structer -f aws-billing.csv -tag json -as billing.Record
```
```go
// Created by structer; DO NOT EDIT

package billing

import (
        "strconv"
        "time"
)

// Record is a struct generated from "aws-billing.csv" file.
type Record struct {
        InvoiceID              string    `json:"invoiceID"`
        PayerAccountID         int64     `json:"payerAccountID"`
        LinkedAccountID        string    `json:"linkedAccountID"`
        RecordType             string    `json:"recordType"`
        RecordID               int64     `json:"recordID"`
        BillingPeriodStartDate time.Time `json:"billingPeriodStartDate"`
        BillingPeriodEndDate   time.Time `json:"billingPeriodEndDate"`
        InvoiceDate            time.Time `json:"invoiceDate"`
}

// MarshalCSV encodes r as a single CSV record.
func (r *Record) MarshalCSV() ([]string, error) {
        records := []string{
                r.InvoiceID,
                strconv.FormatInt(r.PayerAccountID, 10),
                r.LinkedAccountID,
                r.RecordType,
                strconv.FormatInt(r.RecordID, 10),
                time.Parse("2006/01/02 15:04:05", r.BillingPeriodStartDate),
                time.Parse("2006/01/02 15:04:05", r.BillingPeriodEndDate),
                time.Parse("2006/01/02 15:04:05", r.InvoiceDate),
        }
        return records, nil
}

// UnmarshalCSV decodes a single CSV record into r.
func (r *Record) UnmarshalCSV(record []string) error {
        if len(record) != 8 {
                return fmt.Errorf("invalud number fields: want 8, got %d", len(record))
        }
        r.InvoiceID = record[0]
        if record[1] != "" {
                if val, err := strconv.ParseInt(record[1], 10, 64); err == nil {
                        r.PayerAccountID = val
                } else {
                        return err
                }
        }
        r.LinkedAccountID = record[2]
        r.RecordType = record[3]
        if record[4] != "" {
                if val, err := strconv.ParseInt(record[4], 10, 64); err == nil {
                        r.RecordID = val
                } else {
                        return err
                }
        }
        if record[5] != "" {
                if val, err := time.Parse("2006/01/02 15:04:05", record[5]); err == nil {
                        r.BillingPeriodStartDate = val
                } else {
                        return err
                }
        }
        if record[6] != "" {
                if val, err := time.Parse("2006/01/02 15:04:05", record[6]); err == nil {
                        r.BillingPeriodEndDate = val
                } else {
                        return err
                }
        }
        if record[7] != "" {
                if val, err := time.Parse("2006/01/02 15:04:05", record[7]); err == nil {
                        r.InvoiceDate = val
                } else {
                        return err
                }
        }
        return nil
}
```


interfaces

# a library to create type dynamically

[![Report](https://goreportcard.com/badge/github.com/xiaoxin01/typeregistry)](https://goreportcard.com/badge/github.com/xiaoxin01/typeregistry)
[![Build Status](https://travis-ci.org/xiaoxin01/typeregistry.svg?branch=master)](https://travis-ci.org/xiaoxin01/typeregistry)

## how to use

```go
// 1. define struct
type Student struct {
	Age  int
	Name string
}

// 2. add reflect type
key := AddType(new(Student))

// 3. create struct from registed key
student := Make(key)
```

## custom registed key

```go
var i interface{} = new(Student)

// use lowercase struct name as key
name := AddTypeWithKey(i, func(i interface{}) string {
	tpe := reflect.TypeOf(i).Elem()
	return strings.ToLower(tpe.Name())
})

student, ok := Create("student").(*Student)
```

## benchmark

```bash
go.exe test -benchmem -run=^$ supperxin/typeregistry -bench ^BenchmarkMake$

goos: windows
goarch: amd64
pkg: supperxin/typeregistry
BenchmarkMake-8   	 8823256	       138 ns/op	      64 B/op	       2 allocs/op
PASS
ok  	supperxin/typeregistry	1.551s
```

```bash
go.exe test -benchmem -run=^$ supperxin/typeregistry -bench ^BenchmarkCreateDirectly$

goos: windows
goarch: amd64
pkg: supperxin/typeregistry
BenchmarkCreateDirectly-8   	1000000000	         0.593 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	supperxin/typeregistry	0.857s
```


typeregistry

Feature rich type-to-type copy code generator

convergen

Generate any code based on Go types, including type-to-type converters (copy code) without reflection by default

[<img id="copygen" alt="Copygen Logo" src=".github/logo.svg" width="512"/>](https://github.com/switchupcb/copygen#copygen)

---

[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge&logo=appveyor&logo=appveyor)](https://pkg.go.dev/github.com/switchupcb/copygen)
[![License](https://img.shields.io/github/license/switchupcb/copygen.svg?style=for-the-badge)](https://github.com/switchupcb/copygen/blob/main/LICENSE)
[<img id="awesomego" alt="Mentioned in Awesome Go" src="https://awesome.re/mentioned-badge-flat.svg" height="28"/>](https://github.com/avelino/awesome-go#generators)

Copygen saves you from losing time writing repetitive code with a type-based code generator.

## What is Copygen?

Copygen is a command-line and programmatic **code generator** that generates custom type-based code, including type-to-type and field-to-field code without adding any reflection or dependencies to your project. Manual-copy code generated by Copygen is [**391x faster**](https://github.com/gotidy/copy#benchmark) than **jinzhu/copier** and adds no allocation to your program.

_Copygen supports **every** Go type including `basic`, `array`, `slice`, `map`, `chan`, `interface`, and `func` types._

## Table of Contents

| Topic | Categories |
| :------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
| [Usage](#how-do-you-use-copygen) | [Types](#step-1-define-go-types), [Setup](#step-2-configure-the-setup-files), [Command Line](#step-3-use-the-command-line), [Output](#output) |
| [Customization](#customization) | [Custom Objects](#custom-objects), [Templates](#templates) |
| [Matcher](#matcher) | [Automatch](#automatch), [Manual](#manual), [Depth](#depth) |
| [Usecases](#usecase) | [When to Use](#when-to-use-copygen), [Custom Generation](#custom-generation) |
| [License](#what-is-the-license) | [What can I do?](#what-can-you-do-with-this-license), [License Exception](#what-is-a-license-exception) |

## How do you use Copygen?

Each example has a **README**.

| Example | Description |
| :------------------------------- | :--------------------------------------- |
| main | The default example. |
| [basic](examples/basic/) | Matches a `basic` type to a field. |
| [automatch](examples/automatch/) | Uses the automatch matcher with depth. |
| [map](examples/map/) | Uses the manual map matcher. |
| [tag](examples/tag/) | Uses the manual tag matcher. |
| [cast](examples/cast/) | Uses the cast modifier. |
| deepcopy _(Roadmap)_ | Uses the deepcopy option. |
| [error](examples/error/) | Uses `.go` templates to return an error. |
| [tmpl](examples/tmpl/) | Uses `.tmpl` templates. |
| [program](examples/program/) | Uses Copygen programmatically. |

_*[`multi`](examples/_tests/multi/setup/setup.go) tests every type._

This [example](examples/main/) uses three type-structs to generate the `ModelsToDomain()` function using a Command Line Interface.

### Step 1. Define Go Types

Go types are defined in a file.

`./domain/domain.go`

```go
// Package domain contains business logic models.
package domain

// Account represents a user account.
type Account struct {
	ID int
	UserID string
	Name string
	Other string // The other field is not used.
}
```

`./models/model.go`

```go
// Package models contains data storage models (i.e database).
package models

// Account represents the data model for account.
type Account struct {
	ID int
	Name string
	Password string
	Email string
}

// A User represents the data model for a user.
type User struct {
	UserID int
	Name string
	UserData string
}
```

The `models.Account` and `models.User` fields will be copied to `domain.Account` fields.

### Step 2. Configure the setup files

You set up Copygen with a `YML` and `GO` file.

#### setup.yml

```yml
# Define where the code is generated.
generated:
 setup: ./setup.go
 output: ../copygen.go

 # Define the optional custom templates used to generate the file (.go, .tmpl supported).
 # template: ./generate.go

# Define custom options (which are passed to generator options) for customization.
custom:
 option: The possibilities are endless.
```

#### setup.go

Define a `type Copygen interface` in the specified setup file.

In each function, specify _the types you want to copy from_ as parameters, and _the types you want to copy to_ as return values.

_This interface is inspired by **goverter**._

```go
/* Specify the name of the generated file's package. */
package copygen

/* Copygen defines the functions that are generated. */
type Copygen interface {
 // custom see table below for options
 ModelsToDomain(*models.Account, *models.User) *domain.Account
}
```

_Copygen uses no allocation **with pointers** because Go is pass-by-value. So, using a pointer results in the object's fields being assigned directly as opposed to a copy of the object's fields._

#### options

Use comments to specify options for Copygen functions: Do **NOT** add empty lines between comments that pertain to one function.

**Options are evaluated in order of declaration.**

| Option | Use | Description | Example |
| :------------------ | :--------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |
| `automatch field` | Use the automatcher selectively or with `map` and `tag` options. | Using `map` or `tag` disables the default automatcher. Enable it again using `automatch` with _regex_. | `automatch package.Type.Field` `automatch models.User.*` |
| `map from to` | Map fields manually. | `map` fields to and from each other. Regex is supported for from-fields. | `map .* package.Type.Field` `map models.Account.ID domain.Account.ID` |
| `tag field key` | Map fields manually using struct tags. | Use `tag` with _regex_ and a tag key. | `tag package.Type.Field key` `tag .* api` _(all fields)_ |
| `depth field level` | Use a specific field depth. | Copygen uses full-field [depth](#depth) by default. Override this using `depth` with _regex_ and a [depth-level](#depth) integer. | `depth .* 2` `depth models.Account.* 1` |
| `deepcopy field` | Deepcopy from-fields. | Copygen shallow copies fields by default. Override this using `deepcopy` with _regex_. For more info, view [Shallow Copy vs. Deep Copy](#shallow-copy-vs-deep-copy). | `deepcopy package.Type.Field` `deepcopy .*` _(all fields)_ |
| `custom option` | Specify custom function options. | Use custom options with [templates](#templates). Returns `map[string][]string` _(trim-spaced)_. | `ignore true` `swap false` |

_[View a reference on Regex.](https://cheatography.com/davechild/cheat-sheets/regular-expressions/)_

A matching option _(e.g. `map`, `automatch`, `tag`)_ determines whether the field is matched to another field, but a modifying option _(e.g. `convert`, `cast`)_ is only applied when a field is matched.

#### Convert

Use the `convert function field` option to control how a type or field is copied within a function when the field is matched.


```go
/* Define the function and field this converter is applied to using regex. */
// convert .* models.User.UserID
// Itoa converts an integer to an ascii value.
func Itoa(i int) string {
	return c.Itoa(i)
}
```

_This example converts the `models.User.UserID` value using `Itoa` within all functions (`.*`) when the `models.User.UserID` field is matched._

#### Cast

Use the `setup.yml` `matcher: cast` generator option to enable automatic casting when a field is matched.

Use the `setup.go` `cast from to modifier` option to perform direct type assertion, conversion, expressions, function usage, and property usage with a matched field. 

For more information, read the [`cast` example](/examples/cast/).

### Step 3. Use the Command Line

Install the command line utility: Copygen.

```
go install github.com/switchupcb/copygen@latest
```

Install a specific version by specifying a branch.
```
go install github.com/switchupcb/copygen@main
```

Install a specific version by specifying a tag.
```
go install github.com/switchupcb/copygen@v0.4.1
```

Run the executable with given options.

```bash
copygen -yml path/to/yml
```

_The path to the YML file must be specified in reference to the current working directory._

### Output

This example outputs a `copygen.go` file with the specified imports and functions.

```go
// Code generated by github.com/switchupcb/copygen
// DO NOT EDIT.

// Package copygen contains the setup information for copygen generated code.
package copygen

import (
	c "strconv"

	"github.com/switchupcb/copygen/examples/main/domain"
	"github.com/switchupcb/copygen/examples/main/models"
)

// Itoa converts an integer to an ascii value.
func Itoa(i int) string {
	return c.Itoa(i)
}

// ModelsToDomain copies a *models.Account, *models.User to a *domain.Account.
func ModelsToDomain(tA *domain.Account, fA *models.Account, fU *models.User) {
	// *domain.Account fields
	tA.ID = fA.ID
	tA.UserID = Itoa(fU.UserID)
	tA.Name = fA.Name
}
```

## Customization

Copygen's method of input and output lets you generate code that isn't limited to copying fields.

### Custom Objects

Custom types external to your application can be defined in the setup file (`.go`): When an output file is generated, all types _(structs, interfaces, funcs)_ defined in the setup file (`.go`) are copied **EXCEPT** the `type Copygen interface`.

```go
type DataTransferObject struct {
 // ...
}

type Model interface {
 // ...
}

func New() {
 // ...
}
```

### Shallow Copy vs. Deep Copy

The library generates [shallow copy](https://en.m.wikipedia.org/wiki/Object_copying#Shallow_copy) functions by default. 

Do you need to deepcopy instead? Use `new()` within a `convert` or `cast` function **or** use a customized generator template.

### Templates

Copygen supports three methods of code generation: `.go`, `.tmpl`, and `programmatic`. 

You can view the [models.Generator](cli/models/generator.go) type for context on the parameters passed to each function.
- Generator options are parsed from the YML configuration file.
- Function options are parsed from `custom` options.
- Any other option represents a `FieldOption`.

#### .go

Use `.go` files to customize the code generation algorithm: The `copygen` generator uses the [`package template Generate(*models.Generator) (string, error)`](cli/generator/template/generate.go) to generate code. So, **this function is required** for your `.go` templates to work. 

The [error example](examples/error/) modifies the configuration file (`.yml`) to use **custom `.go` template functions** that `return error`. The [`template/generate.go`](/cli//generator/template/generate.go) file provides the default code generation algorithm for generating code.

_Use of non-extracted Go Module Imports in [`generate.go` template files](cli/generator/template/generate.go) are unsupported at the current time._

#### .tmpl

Use `.tmpl` _([`text/templates`](https://pkg.go.dev/text/template))_ to customize the code generation algorithm. The [template example](examples/tmpl/) uses a [`.tmpl`](/examples/tmpl/template/generate.tmpl) file to generate code.

#### programmatic

Use `copygen` as a third-party module in your application. For more information, read the [program example](/examples/program/README.md).

## Matcher

Copygen provides two methods of field-matching: `automatch` and `manual`.

_You can disable the matcher using the `matcher: skip: true` option in the setup file._

### Automatch

Copygen automatically matches the function's fields by field name and definition when a [matching option _(`automatch`,`map`,`tag`)_](#options) isn't specified on a function.
- Automatch matches one from-field to many to-fields
- **Automatch supports field-depth** (when fields contain fields) **and recursive types** (when the field contains itself).
- Automatch loads types from Go modules _(in the `GOPATH`)_: Confirm your Go modules are up-to-date using `go get -u <insert/module/import/path>`.

### Manual

Using the `map` or `tag` option disables the automatcher, which lets you manually match fields. In order to re-enable the automatcher, use the `automatch` option. 

Options are evaluated in order of declaration, so using `automatch .*` **after** declaring `map` and `tag` options is an easy way to re-enable the _automatcher_ for remaining fields.

#### Depth

The automatcher uses a field-based depth system where a field with a depth-level of 0 only matches itself. This system lets you specify the depth-level for specific types and fields. Increasing the depth-level lets the field's sub-fields at a specified depth-level be matched.

```go
// Depth-level in relation to the first-level field (0).
type Account
 // 1
 ID int
 Name string
 Email string
 Basic domain.T // int
 User domain.DomainUser
 // 2
 UserID string
 Name string
 UserData map[string]interface{}
 // 1
 Log log.Logger
 // 2
 mu sync.Mutex
 // 3
 state int32
 sema uint32
 // 2
 prefix string
 flag int
 out io.Writer
 // 3
 Write func(p []byte) (n int, err error)
 buf []byte
```

## Usecase

### When to Use Copygen

Copygen's default purpose is to save you time by generating code to map objects together.

### Why would you do that?

You generate code to map objects together when your program contains multiple models types (e.g., `domain`, `database`), which improves feature development speed without affecting performance.

_Here is an example._

Suppose a program maintains two types of models for feature development.
- The **domain model** is a human-optimized definition of the business logic, and is used by a human to develop business logic. For example, an `account` model which is defined for use by a human.
- The **data model** is a machine-optimized definition of the business logic, and is used by a machine to execute business logic efficiently. For example, a database model of an `account` which defines `username`, `profile_picture`, and other account related data in separate models for database efficiency.
 
These models are created because the ideal method of data storage is not the ideal domain model. However, you must map these models together to exchange information from your data model to your domain model and vice-versa.

_Here is an example of how Copygen uses this development pattern._
- The [domain models of Copygen](cli/models/) focus on field relations and manipulation as understood by a human.
- The [data models of Copygen](cli/config/models.go) are located in its configuration loader and Go type `ast` structs.
- The "business logic" of Copygen is defined in the `parser`, `matcher`, and `generator`, which use the `domain` models of Copygen to generate code instead of underlying `ast` data structs.

### Custom Generation

Copygen's customizability with templates lets you generate any code **based on types** _(and their respective fields, tags, etc)_. 

| Example | Description |
| :------ | :-------------------------------------------------------------------------------------- |
| Repogen | Generate a Business-Logic Repository package based on a Data Access Object (DAO) model. |
| Wrapper | Generate functions for requests using an API resource and request object model. |

_Check out more usecases in real-world examples using [Copygen Usecases](https://github.com/switchupcb/copygen/discussions/categories/usecases)._

## What is the License?

Copygen uses a [AGPLv3 License](https://www.gnu.org/licenses/agpl-3.0.en.html).

An exception is provided for template and example files, which are licensed under the [MIT License](cli/generator/template/LICENSE.md).

### What can you do with this license?

**Code generated by Copygen can be used without restriction (including proprietary and commercial usage)** since generated code is not considered a derivative work. However, **modifications** to the _Copygen Software Source Code_ or implementing Copygen in a larger work **programmatically** requires you to [adhere to the AGPLv3 License](https://www.gnu.org/licenses/gpl-faq.html). 

_These restrictions do **NOT** apply to template or example files, as long as those files don't generate Copygen itself._

### What is a license exception?

A license exception lets you modify and use Copygen programmatically **without restriction**. 

You can receive a license exception for Copygen by contacting SwitchUpCB using the [Copygen License Exception Inquiry Form](https://switchupcb.com/copygen-license-exception/).

## Contributing

You can contribute to this repository by viewing the [Project Structure, Code Specifications, CI/CD, and Roadmap](CONTRIBUTING.md).

copygen

Code generation tool providing generics, free-form macros, conditional compilation and HTML templating

![](https://github.com/senselogic/GENERIS/blob/master/LOGO/generis.png)

# Generis

Versatile Go code generator.

## Description

Generis is a lightweight code preprocessor adding the following features to the Go language :

* Generics.
* Free-form macros.
* Conditional compilation.
* HTML templating.
* Allman style conversion.

## Sample

```go
package main;

// -- IMPORTS

import (
 "html"
 "io"
 "log"
 "net/http"
 "net/url"
 "strconv"
 );

// -- DEFINITIONS

#define DebugMode
#as true

// ~~

#define HttpPort
#as 8080

// ~~

#define WriteLine( {{text}} )
#as log.Println( {{text}} )

// ~~

#define local {{variable}} : {{type}};
#as var {{variable}} {{type}};

// ~~

#define DeclareStack( {{type}}, {{name}} )
#as
 // -- TYPES

 type {{name}}Stack struct
 {
 ElementArray []{{type}};
 }

 // -- INQUIRIES

 func ( stack * {{name}}Stack ) IsEmpty(
 ) bool
 {
 return len( stack.ElementArray ) == 0;
 }

 // -- OPERATIONS

 func ( stack * {{name}}Stack ) Push(
 element {{type}}
 )
 {
 stack.ElementArray = append( stack.ElementArray, element );
 }

 // ~~

 func ( stack * {{name}}Stack ) Pop(
 ) {{type}}
 {
 local
 element : {{type}};

 element = stack.ElementArray[ len( stack.ElementArray ) - 1 ];

 stack.ElementArray = stack.ElementArray[ : len( stack.ElementArray ) - 1 ];

 return element;
 }
#end

// ~~

#define DeclareStack( {{type}} )
#as DeclareStack( {{type}}, {{type:PascalCase}} )

// -- TYPES

DeclareStack( string )
DeclareStack( int32 )

// -- FUNCTIONS

func HandleRootPage(
 response_writer http.ResponseWriter,
 request * http.Request
 )
{
 local
 boolean : bool;
 local
 natural : uint;
 local
 integer : int;
 local
 real : float64;
 local
 escaped_html_text,
 escaped_url_text,
 text : string;
 local
 integer_stack : Int32Stack;

 boolean = true;
 natural = 10;
 integer = 20;
 real = 30.0;
 text = "text";
 escaped_url_text = "&escaped text?";
 escaped_html_text = "<escaped text/>";

 integer_stack.Push( 10 );
 integer_stack.Push( 20 );
 integer_stack.Push( 30 );

 #write response_writer
 <!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <title><%= request.URL.Path %></title>
 </head>
 <body>
 <% if ( boolean ) { %>
 <%= "URL : " + request.URL.Path %>
 
 <%@ natural %>
 <%# integer %>
 <%& real %>
 
 <%~ text %>
 <%^ escaped_url_text %>
 <%= escaped_html_text %>
 <%= "<%% ignored %%>" %>
 <%% ignored %%>
 <% } %>
 
 Stack :
 
 <% for !integer_stack.IsEmpty() { %>
 <%# integer_stack.Pop() %>
 <% } %>
 </body>
 </html>
 #end
}

// ~~

func main()
{
 http.HandleFunc( "/", HandleRootPage );

 #if DebugMode
 WriteLine( "Listening on http://localhost:HttpPort" );
 #end

 log.Fatal(
 http.ListenAndServe( ":HttpPort", nil )
 );
}
```

## Syntax

### #define directive

Constants and generic code can be defined with the following syntax :

```go
#define old code
#as new code

#define old code
#as
 new
 code
#end

#define
 old
 code
#as new code

#define
 old
 code
#as
 new
 code
#end
```

#### #define parameter

The `#define` directive can contain one or several parameters :

```go
{{variable name}} : hierarchical code (with properly matching brackets and parentheses)
{{variable name#}} : statement code (hierarchical code without semicolon)
{{variable name$}} : plain code
{{variable name:boolean expression}} : conditional hierarchical code
{{variable name#:boolean expression}} : conditional statement code
{{variable name$:boolean expression}} : conditional plain code
```

They can have a boolean expression to require they match specific conditions :

```go
HasText text
HasPrefix prefix
HasSuffix suffix
HasIdentifier text
false
true
!expression
expression && expression
expression || expression
( expression )
```

The `#define` directive must not start or end with a parameter.

#### #as parameter

The `#as` directive can use the value of the `#define` parameters :

```go
{{variable name}}
{{variable name:filter function}}
{{variable name:filter function:filter function:...}}
```

Their value can be changed through one or several filter functions :

```go
LowerCase
UpperCase
MinorCase
MajorCase
SnakeCase
PascalCase
CamelCase
RemoveComments
RemoveBlanks
PackStrings
PackIdentifiers
ReplacePrefix old_prefix new_prefix
ReplaceSuffix old_suffix new_suffix
ReplaceText old_text new_text
ReplaceIdentifier old_identifier new_identifier
AddPrefix prefix
AddSuffix suffix
RemovePrefix prefix
RemoveSuffix suffix
RemoveText text
RemoveIdentifier identifier
```

### #if directive

Conditional code can be defined with the following syntax :

```go
#if boolean expression
 #if boolean expression
 ...
 #else
 ...
 #end
#else
 #if boolean expression
 ...
 #else
 ...
 #end
#end
```

The boolean expression can use the following operators :

```go
false
true
!expression
expression && expression
expression || expression
( expression )
```

### #write directive

Templated HTML code can be sent to a stream writer using the following syntax :

```html
#write writer expression
 <% code %>
 <%@ natural expression %>
 <%# integer expression %>
 <%& real expression %>
 <%~ text expression %>
 <%= escaped text expression %>
 <%! removed content %>
 <%% ignored tags %%>
#end
```

## Limitations

* There is no operator precedence in boolean expressions.
* The `--join` option requires to end the statements with a semicolon.
* The `#writer` directive is only available for the Go language.

## Installation

Install the [DMD 2 compiler](https://dlang.org/download.html) (using the MinGW setup option on Windows).

Build the executable with the following command line :

```bash
dmd -m64 generis.d
```

## Command line

```
generis [options]
```

### Options

```
--prefix # : set the command prefix
--parse INPUT_FOLDER/ : parse the definitions of the Generis files in the input folder
--process INPUT_FOLDER/ OUTPUT_FOLDER/ : reads the Generis files in the input folder and writes the processed files in the output folder
--trim : trim the HTML templates
--join : join the split statements
--create : create the output folders if needed
--watch : watch the Generis files for modifications
--pause 500 : time to wait before checking the Generis files again
--tabulation 4 : set the tabulation space count
--extension .go : generate files with this extension
```

### Examples

```bash
generis --process GS/ GO/
```

Reads the Generis files in the `GS/` folder and writes Go files in the `GO/` folder.

```bash
generis --process GS/ GO/ --create
```

Reads the Generis files in the `GS/` folder and writes Go files in the `GO/` folder,
creating the output folders if needed.

```bash
generis --process GS/ GO/ --create --watch
```

Reads the Generis files in the `GS/` folder and writes Go files in the `GO/` folder,
creating the output folders if needed and watching the Generis files for modifications.

```bash
generis --process GS/ GO/ --trim --join --create --watch
```

Reads the Generis files in the `GS/` folder and writes Go files in the `GO/` folder,
trimming the HTML templates, joining the split statements, creating the output folders if needed
and watching the Generis files for modifications.

## Version

2.0

## Author

Eric Pelzer (ecstatic.coder@gmail.com).

## License

This project is licensed under the GNU General Public License version 3.

See the [LICENSE.md](LICENSE.md) file for details.

generis

Generate OpenAPI 3.1 specs from Go source code via static analysis with automatic framework detection

# go-apispec: Generate OpenAPI from Go code

[![CI](https://github.com/antst/go-apispec/actions/workflows/ci.yml/badge.svg)](https://github.com/antst/go-apispec/actions/workflows/ci.yml)
[![Release](https://github.com/antst/go-apispec/actions/workflows/release.yml/badge.svg)](https://github.com/antst/go-apispec/actions/workflows/release.yml)
![Coverage](https://img.shields.io/badge/coverage-95.7%25-brightgreen.svg)
[![Go Version](https://img.shields.io/badge/go-1.25+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/antst/go-apispec/blob/main/LICENSE)
[![Go Reference](https://pkg.go.dev/badge/github.com/antst/go-apispec.svg)](https://pkg.go.dev/github.com/antst/go-apispec)

**go-apispec** analyzes your Go source code and generates an OpenAPI 3.1 spec (YAML or JSON). Point it at your module — it detects the framework, follows the call graph from routes to handlers, and infers request/response types from real code.

## Quick Start

```bash
# Install
go install github.com/antst/go-apispec/cmd/apispec@latest

# Generate (auto-detects framework)
apispec --dir ./your-project --output openapi.yaml
```

That's it. The tool detects your framework, finds all routes, resolves handler types, and writes the spec.

## Features

### Framework Support

| Framework | Routes | Params | Request Body | Responses | Mounting/Groups |
|-----------|--------|--------|-------------|-----------|-----------------|
| **Chi** | Full | `chi.URLParam`, render pkg | `json.Decode`, `render.DecodeJSON` | `json.Encode`, `render.JSON`, `w.Write` | `Mount`, `Group` |
| **Gin** | Full | `c.Param`, `c.Query` | `ShouldBindJSON`, `BindJSON` | `c.JSON`, `c.String`, `c.Data` | `Group` |
| **Echo** | Full | `c.Param`, `c.QueryParam` | `c.Bind` | `c.JSON`, `c.String`, `c.Blob` | `Group` |
| **Fiber** | Full | `c.Params`, `c.Query` | `c.BodyParser` | `c.JSON`, `c.Status().JSON` | `Mount`, `Group` |
| **Gorilla Mux** | Full | Path template `{id}` | `json.Decode` | `json.Encode`, `w.Write` | `PathPrefix`, `Subrouter` |
| **net/http** | Basic | Path template | `json.Decode` | `json.Encode`, `w.Write`, `http.Error` | Nested `ServeMux` |

Projects using **multiple frameworks** simultaneously are fully supported — all routes from all detected frameworks appear in the spec.

All frameworks also detect `fmt.Fprintf`, `io.Copy`, and `io.WriteString` as response writes.

### Analysis Capabilities

**Response Detection**
- Content-Type inference from `w.Header().Set("Content-Type", "image/png")`
- `WriteHeader(201)` + `json.Encode(user)` merged into a single 201 response with schema
- Status code variable resolution: `status := http.StatusCreated; w.WriteHeader(status)` → 201
- Cross-function status codes: `w.WriteHeader(getStatus())` where `getStatus()` returns a constant
- Multiple response types for the same status code → `oneOf` schema
- `[]byte` responses → `type: string, format: binary`
- Bodyless status codes (1xx, 204, 304) never get body schemas (per RFC 7231)
- Implicit 200 for handlers that write a body without explicit `WriteHeader`

**Type Resolution**
- Generic struct instantiation: `APIResponse[User]` → schema with `Data: $ref User`
- Interface resolution: handlers registered via interface → concrete implementation schemas
- Conditional HTTP methods via CFG: `switch r.Method { case "GET": ... case "POST": ... }` → separate operations
- Route path variables: `path := "/users"; r.GET(path, h)` → resolves variable to literal path
- Decode receiver tracing: `json.NewDecoder(file).Decode(&cfg)` not misclassified as request body
- io.Copy source tracing: `io.Copy(w, strings.NewReader(...))` → `type: string`; `io.Copy(w, file)` → `format: binary`

**Schema Inference**
- Required fields from `json:",omitempty"` absence and `binding:"required"` tags
- Validator `dive` tag: `validate:"dive,email"` on `[]string` → items schema has `format: email`
- `Mux.Vars()` map index expressions → path parameter names
- Type mappings for `time.Time`, `uuid.UUID`, and custom types

**Output Quality**
- Deterministic YAML/JSON — sorted map keys, identical output across runs, safe for CI diffing
- Short names by default — `DocumentHandler.GetContent` instead of `github.com/org/.../http.Deps.DocumentHandler.GetContent`
- Config merging — `--config` extends auto-detected framework defaults instead of replacing them

### Call Graph Visualization

Interactive Cytoscape.js diagrams with:
- Hierarchical tree layout with zoom, pan, and click-to-highlight
- CFG branch coloring: green (if-then), red dashed (if-else), purple (switch-case)
- Branch labels showing case values (e.g., "GET", "POST")
- Paginated mode for large graphs (1000+ edges)
- PNG/SVG export

```bash
apispec --dir ./my-project --output openapi.yaml --diagram diagram.html
```

## Usage

```bash
# Basic generation
apispec --dir ./my-project --output openapi.yaml

# With custom config
apispec --dir ./my-project --config apispec.yaml --output openapi.yaml

# Legacy naming (fully-qualified operationIds and schema names)
apispec --dir ./my-project --output openapi.yaml --short-names=false

# With call graph diagram
apispec --dir ./my-project --output openapi.yaml --diagram diagram.html

# Skip CGO packages
apispec --dir ./my-project --output openapi.yaml --skip-cgo

# Tune limits for large codebases
apispec --dir ./my-project --output openapi.yaml --max-nodes 100000 --max-recursion-depth 15

# Performance profiling
apispec --dir ./my-project --output openapi.yaml --cpu-profile --mem-profile
```

### Key Flags

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--output` | `-o` | `openapi.json` | Output file (`.yaml`/`.json`) |
| `--dir` | `-d` | `.` | Project directory |
| `--config` | `-c` | — | Custom YAML config |
| `--short-names` | — | `true` | Strip module paths from names |
| `--diagram` | `-g` | — | Save call graph as HTML |
| `--title` | `-t` | `Generated API` | API title |
| `--api-version` | `-v` | `1.0.0` | API version |
| `--skip-cgo` | — | `true` | Skip CGO packages |
| `--max-nodes` | `-mn` | `50000` | Max call graph nodes |
| `--max-recursion-depth` | `-mrd` | `10` | Max recursion depth |
| `--verbose` | `-vb` | `false` | Verbose output |

Full flag list: `apispec --help`

## Programmatic Usage

```go
import (
    "os"
    "github.com/antst/go-apispec/generator"
    "github.com/antst/go-apispec/spec"
    "gopkg.in/yaml.v3"
)

func main() {
    cfg := spec.DefaultChiConfig() // or DefaultGinConfig, DefaultEchoConfig, etc.
    gen := generator.NewGenerator(cfg)
    openapi, err := gen.GenerateFromDirectory("./your-project")
    if err != nil { panic(err) }
    data, _ := yaml.Marshal(openapi)
    os.WriteFile("openapi.yaml", data, 0644)
}
```

## Configuration

Auto-detection works for most projects. For custom behavior, create `apispec.yaml`:

```yaml
info:
  title: My API
  version: 2.0.0

shortNames: true  # false for legacy fully-qualified names

framework:
  routePatterns:
    - callRegex: ^(?i)(GET|POST|PUT|DELETE|PATCH)$
      recvTypeRegex: ^github\.com/gin-gonic/gin\.\*(Engine|RouterGroup)$
      handlerArgIndex: 1
      methodFromCall: true
      pathFromArg: true
      handlerFromArg: true

typeMapping:
  - goType: time.Time
    openapiType: { type: string, format: date-time }
  - goType: uuid.UUID
    openapiType: { type: string, format: uuid }

externalTypes:
  - name: github.com/gin-gonic/gin.H
    openapiType: { type: object, additionalProperties: true }
```

Full configuration examples for each framework: see the `Default*Config()` functions in `internal/spec/config.go` for the built-in patterns.

## How It Works

```
Go source → Package loading & type-checking → Framework detection
  → AST traversal → Call graph + CFG construction → Pattern matching
  → OpenAPI mapping → YAML/JSON output
```

1. Loads and type-checks all Go packages in the module
2. Detects web frameworks from imports (supports multiple frameworks simultaneously)
3. Builds a call graph from router registrations to handlers
4. Builds a control-flow graph (CFG) via `golang.org/x/tools/go/cfg` for branch analysis
5. Matches route, request, response, and parameter patterns against the call graph
6. Resolves conditional methods, generic types, and interface implementations using CFG and type analysis
7. Maps Go types to OpenAPI schemas (structs, enums, aliases, generics, validators)
8. Serializes with sorted keys for deterministic output

## Known Limitations

These are inherent to static analysis — analyzing code without executing it:

| Limitation | Example | What Happens |
|-----------|---------|-------------|
| **Reflection-based routing** | Routes registered via `reflect.Value.Call` | Not visible in static analysis |
| **Computed paths** | `r.GET("/api/" + version, handler)` | String concatenation not evaluated; only literal and variable-assigned paths resolved |
| **Complex cross-function values** | `func compute() int { return a + b }; WriteHeader(compute())` | Only functions with a single constant return are resolved; computed values are not traced |

## Interactive Diagram Server

```bash
# Build and start
go build -o apidiag ./cmd/apidiag
./apidiag --dir ./my-project --port 8080
# Open http://localhost:8080
```

Provides a web UI for exploring call graphs with filtering, pagination, and export. See [cmd/apidiag/README.md](cmd/apidiag/README.md).

## Development

```bash
# Build
make build

# Test
make test

# Lint
make lint

# Coverage
make coverage

# Update golden files after intentional output changes
# (generates to temp, shows diff, requires confirmation)
go test ./internal/engine/ -run TestUpdateGolden -v
```

### Project Structure

```
go-apispec/
├── cmd/apispec/          CLI entry point
├── cmd/apidiag/          Interactive diagram server
├── generator/            High-level generator API
├── spec/                 Public types (re-exports from internal/spec)
├── internal/
│   ├── core/             Framework detection
│   ├── engine/           Generation engine
│   ├── metadata/         AST analysis and metadata extraction
│   └── spec/             OpenAPI mapping, patterns, schemas
├── pkg/patterns/         Gitignore-style pattern matching
└── testdata/             Framework fixtures + golden files
```

### Golden File Tests

Every `testdata/` directory has `expected_openapi.json` (short names) and `expected_openapi_legacy.json` (fully-qualified). Golden files use relative paths only — no machine-specific absolute paths.

**One code path**: `generateGoldenSpec()` is the single function used by both comparison and generation. Tests never overwrite golden files.

```bash
# Compare (runs in CI — fails on mismatch):
go test ./internal/engine/ -run TestGolden -v

# Update after intentional changes (explicit, never automatic):
go test ./internal/engine/ -run TestUpdateGolden -v
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). In short:

1. Fork, branch, make changes
2. Add tests (`make test`)
3. Run lint (`make lint`)
4. Open a PR

## License

Apache License 2.0 — see [LICENSE](LICENSE).

Originally forked from [apispec](https://github.com/ehabterra/apispec) by Ehab Terra.


go-apispec

Generate decorators for Go interfaces using simple templates

# GoWrap
[![License](https://img.shields.io/badge/license-mit-green.svg)](https://github.com/hexdigest/gowrap/blob/master/LICENSE)
[![Build](https://github.com/hexdigest/gowrap/actions/workflows/go.yml/badge.svg)](https://github.com/hexdigest/gowrap/actions/workflows/go.yml)
[![Coverage Status](https://coveralls.io/repos/github/hexdigest/gowrap/badge.svg?branch=master)](https://coveralls.io/github/hexdigest/gowrap?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/hexdigest/gowrap?dropcache)](https://goreportcard.com/report/github.com/hexdigest/gowrap)
[![GoDoc](https://godoc.org/github.com/hexdigest/gowrap?status.svg)](http://godoc.org/github.com/hexdigest/gowrap)
[![Awesome](https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg)](https://github.com/avelino/awesome-go#generation-and-generics)
[![Release](https://img.shields.io/github/release/hexdigest/gowrap.svg)](https://github.com/hexdigest/gowrap/releases/latest)

GoWrap is a command line tool that generates decorators for Go interface types using simple templates.
With GoWrap you can easily add metrics, tracing, fallbacks, pools, and many other features into your existing code in a few seconds.


## Demo

![demo](https://github.com/hexdigest/gowrap/blob/master/gowrap.gif)

## Installation
### CLI
```
go install github.com/hexdigest/gowrap/cmd/gowrap@latest
```
### As module
```
go get -u github.com/hexdigest/gowrap/cmd/gowrap
```

## Usage of gowrap

```
Usage: gowrap gen -p package -i interfaceName -t template -o output_file.go
  -g	don't put //go:generate instruction into the generated code
  -i string
    	the source interface name, i.e. "Reader"
  -o string
    	the output file name
  -p string
    	the source package import path, i.e. "io", "github.com/hexdigest/gowrap" or
    	a relative import path like "./generator"
  -t template
    	the template to use, it can be an HTTPS URL a local file or a
    	reference to one of the templates in the gowrap repository
  -v value
    	a key-value pair to parametrize the template,
    	arguments without an equal sign are treated as a bool values,
    	i.e. -v DecoratorName=MyDecorator -v disableChecks
```

This will generate an implementation of the io.Reader interface wrapped with prometheus metrics

```
  $ gowrap gen -p io -i Reader -t prometheus -o reader_with_metrics.go
```

This will generate a fallback decorator for the Connector interface that can be found in the ./connector subpackage:

```
  $ gowrap gen -p ./connector -i Connector -t fallback -o ./connector/with_metrics.go
```

Run `gowrap help` for more options

## Hosted templates

When you specify a template with the "-t" flag, gowrap will first search for and use the local file with this name.
If the file is not found, gowrap will look for the template [here](https://github.com/hexdigest/gowrap/tree/master/templates) and use it if found.

List of available templates:
  - [circuitbreaker](https://github.com/hexdigest/gowrap/tree/master/templates/circuitbreaker) stops executing methods of the wrapped interface after the specified number of consecutive errors and resumes execution after the specified delay
  - [fallback](https://github.com/hexdigest/gowrap/tree/master/templates/fallback) takes several implementations of the source interface and concurrently runs each implementation if the previous attempt didn't return the result in a specified period of time, it returns the first non-error result
  - [log](https://github.com/hexdigest/gowrap/tree/master/templates/log) instruments the source interface with logging using standard logger from the "log" package
  - [logrus](https://github.com/hexdigest/gowrap/tree/master/templates/logrus) instruments the source interface with logging using popular [sirupsen/logrus](https://github.com/sirupsen/logrus) logger
  - [opencensus](https://github.com/hexdigest/gowrap/tree/master/templates/opencensus) instruments the source interface with opencensus spans
  - [opentelemetry](https://github.com/hexdigest/gowrap/tree/master/templates/opentelemetry) instruments the source interface with opentelemetry spans
  - [opentracing](https://github.com/hexdigest/gowrap/tree/master/templates/opentracing) instruments the source interface with opentracing spans
  - [prometheus](https://github.com/hexdigest/gowrap/tree/master/templates/prometheus) instruments the source interface with prometheus metrics
  - [ratelimit](https://github.com/hexdigest/gowrap/tree/master/templates/ratelimit) instruments the source interface with RPS limit and concurrent calls limit
  - [retry](https://github.com/hexdigest/gowrap/tree/master/templates/retry) instruments the source interface with retries
  - [robinpool](https://github.com/hexdigest/gowrap/tree/master/templates/robinpool) puts several implementations of the source interface to the slice and for every method call it picks one implementation from the slice using the Round-robin algorithm
  - [syncpool](https://github.com/hexdigest/gowrap/tree/master/templates/syncpool) puts several implementations of the source interface to the sync.Pool and for every method call it gets one implementation from the pool and puts it back once finished
  - [timeout](https://github.com/hexdigest/gowrap/tree/master/templates/timeout) instruments each method that accepts context with configurable timeout
  - [validate](https://github.com/hexdigest/gowrap/tree/master/templates/validate) runs `func Validate() error` method on each argument if it's present
  - [twirp\_error](https://github.com/hexdigest/gowrap/tree/master/templates/twirp_error) inject request data into twirp.Error as metadata
  - [twirp\_validate](https://github.com/hexdigest/gowrap/tree/master/templates/twirp_validate) runs `func Validate() error` method on each argument if it's present and wraps returned error with twirp.Malformed error
  - [grpc\_validate](https://github.com/hexdigest/gowrap/tree/master/templates/grpc_validate) runs `func Validate() error` method on each argument if it's present and returns [InvalidArgument](https://github.com/grpc/grpc-go/blob/9d8d97a245af2d4bc743585418e1b4aebada0637/codes/codes.go#L49) error in case when validation failed
  - [elastic apm](https://github.com/hexdigest/gowrap/tree/master/templates/elasticapm) instruments the source interface with elastic apm spans

By default GoWrap places the `//go:generate` instruction into the generated code. 
This allows you to regenerate decorators' code just by typing `go generate ./...` when you change the source interface type declaration.
However if you used a remote template, the `//go:generate` instruction will contain the HTTPS URL of the template and therefore
you will need to have internet connection in order to regenerate decorators. In order to avoid this, you can copy templates from the GoWrap repository 
to local files and add them to your version control system:
```
$ gowrap template copy fallback templates/fallback
```

The above command will fetch the fallback template and copy it to the templates/fallback local file.
After template is copied, you can generate decorators using this local template:

```
$ gowrap gen -p io -i Reader -t templates/fallback reader_with_fallback.go
```

## Custom templates

You can always write your own template that will provide the desired functionality to your interfaces.
If you think that your template might be useful to others, please consider adding it to our [template repository](https://github.com/hexdigest/gowrap/tree/master/templates).

The structure of information passed to templates is documented with the [TemplateInputs](https://godoc.org/github.com/hexdigest/gowrap/generator#TemplateInputs) struct.

### Template Functions

In the templates, all functions provided by the [sprig](http://masterminds.github.io/sprig/) template library are available.

Additionally `gowrap` includes the following template functions:

- `up`: returns the input with all Unicode letters mapped to their upper case.
- `down`: returns the input with all Unicode letters mapped to their lower case.
- `upFirst`: returns the input with the first Unicode letter mapped to their upper case.
- `downFirst`: returns the input with the first Unicode letter mapped to their lower case.
- `replace`: returns the input with all occurences of the first argument replaced with the second argument.
- `snake`: returns the input in snake case representation.

## Become a patron

Here's my [Patreon page](https://www.patreon.com/hexdigest). Thank you!


GoWrap

Generate arbitrary Go code without templates

jennifer

This package contains a set of utilities for generating Go boilerplate code for services based on OpenAPI 3.0 API definitions

oapi-codegen

Generate HTTP server and client from protobuf

# protoc-gen-httpgo

![workflow](https://github.com/MUlt1mate/protoc-gen-httpgo/actions/workflows/go.yml/badge.svg)
![go-report](https://goreportcard.com/badge/github.com/MUlt1mate/protoc-gen-httpgo)
[![Go Reference](https://pkg.go.dev/badge/github.com/MUlt1mate/protoc-gen-httpgo.svg)](https://pkg.go.dev/github.com/MUlt1mate/protoc-gen-httpgo)

**httpgo** is a protoc plugin that generates native HTTP server and client code from your proto files. 
It is a lightweight, high-performance alternative to [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway).

Choose httpgo if you want to:

- **Eliminate Proxy Overhead**: Serve HTTP directly from your application without a transcoding layer.
- **Dual-Stack Support**: Use HTTP and gRPC simultaneously with minimal performance impact.
- **Protobuf-First Design**: Define your API in Protobuf while leveraging the full flexibility of the HTTP ecosystem.

## Performance

Check [benchmark](./benchmark/README.md)

- 30% faster than grpc-gateway + grpc
- 95% reduction in memory overhead

## Features

- Generation of both server and client code
 - Supports [gin](https://github.com/gin-gonic/gin) (server only)
 - Supports [fiber](https://github.com/gofiber/fiber) (server only)
 - Supports [fasthttp](https://github.com/valyala/fasthttp)
 - Supports [net/http](https://pkg.go.dev/net/http)
- Provides multiple options for Marshaling/Unmarshaling:
 - Uses the native `encoding/json` by default
 - Optional usage of [protojson](https://pkg.go.dev/google.golang.org/protobuf/encoding/protojson) for better
 protocol buffer support
- Uses standard
 [google.api.http](https://cloud.google.com/service-infrastructure/docs/service-management/reference/rpc/google.api#httprule)
 definitions for path mapping
 - supports all HttpRule fields
- Supports automatic URI generation
- Supports a wide range of data types in path parameters
- Supports middlewares
- Supports multipart form with files
- Zero additional dependencies in generated code

## Usage

### Installation

```bash
 go install github.com/MUlt1mate/protoc-gen-httpgo@latest
 ```

### Definition

Use proto with RPC to define methods

```protobuf
import "google/api/annotations.proto";

service TestService {
 rpc TestMethod (TestMessage) returns (TestMessage) {
 option (google.api.http) = {
 get: "/v1/test/{field1}"
 };
 }
}

message TestMessage {
 string field1 = 1;
 string field2 = 2;
}
```

### Generation

```bash 
protoc -I=. --httpgo_out=paths=source_relative:. example/proto/example.proto
``` 

#### Parameters

| Name | Values | Description |
|-----------------|-------------------------------|------------------------------------------------------------------------------------------------------------------|
| paths | source_relative, import | Inherited from protogen, see [docs](https://protobuf.dev/reference/go/go-generated/#invocation) for more details |
| marshaller | json, protojson | Specifies the data marshaling/unmarshaling package. Uses `encoding/json` by default. |
| only | server, client | Use to generate either the server or client code exclusively |
| autoURI | false, true | Create method URI if annotation is missing. |
| bodylessMethods | GET;DELETE | List of semicolon separated http methods that should not have a body. |
| library | gin, fiber, fasthttp, nethttp | Server library |

Example of parameters usage:

```bash
protoc -I=. --httpgo_out=paths=source_relative,only=server,autoURI=true,library=fasthttp:. example/proto/example.proto
```

The plugin will create an example.httpgo.go file with the following:

- `Register{ServiceName}HTTPGoServer` - function to register server handlers
- `{ServiceName}HTTPGoService` - interface with all client methods
- `Get{ServiceName}HTTPGoClient` - client constructor that implements the above interface

### Implementation

#### Server

```go
package main

import (
	"context"

	"github.com/MUlt1mate/protoc-gen-httpgo/example/implementation"
	"github.com/MUlt1mate/protoc-gen-httpgo/example/proto"
	"github.com/fasthttp/router"
	"github.com/valyala/fasthttp"
)

func serverExample(ctx context.Context) (err error) {
	var (
		handler proto.TestServiceHTTPGoService = &implementation.Handler{}
		r = router.New()
	)
	if err = proto.RegisterTestServiceHTTPGoServer(ctx, r, handler, serverMiddlewares); err != nil {
		return err
	}
	go func() { _ = fasthttp.ListenAndServe(":8080", r.Handler) }()
	return nil
}

```

#### Client

```go
package main

import (
	"context"

	"github.com/MUlt1mate/protoc-gen-httpgo/example/proto"
	"github.com/valyala/fasthttp"
)

func clientExample(ctx context.Context) (err error) {
	var (
		client *proto.TestServiceHTTPGoClient
		httpClient = &fasthttp.Client{}
		host = "http://localhost:8080"
	)
	if client, err = proto.GetTestServiceHTTPGoClient(ctx, httpClient, host, clientMiddlewares); err != nil {
		return err
	}
	// sending our request
	_, _ = client.TestMethod(context.Background(), &proto.TestMessage{Field1: "value", Field2: "rand"})
	return nil
}

```

#### Middlewares

You can define custom middlewares with specific arguments and return values.
Pass a slice of middlewares to the constructor, and they will be invoked in the specified order.
There are ready-to-use examples with 9 server middlewares (monitoring, timeout, recovery, response, headers,
tracing, auth, logging, validation) across all four implementations:
[fasthttp](example/implementation/fasthttp/README.md),
[fiber](example/implementation/fiber/README.md),
[gin](example/implementation/gin/README.md),
[nethttp](example/implementation/nethttp/README.md).
Additionally, 5 client middlewares (monitoring, tracing, logging, error handling, timeout) are included in the
[fasthttp](example/implementation/fasthttp/README.md) and [nethttp](example/implementation/nethttp/README.md) examples;
the fiber and gin examples are server-only.

```go
package fasthttp

import (
	"context"
	"log"

	"github.com/valyala/fasthttp"
)

var ServerMiddlewares = []func(ctx context.Context, arg any, handler func(ctx context.Context, arg any) (resp any, err error)) (resp any, err error){
	LoggerServerMiddleware,
}
var ClientMiddlewares = []func(ctx context.Context, req *fasthttp.Request, handler func(ctx context.Context, req *fasthttp.Request) (resp *fasthttp.Response, err error)) (resp *fasthttp.Response, err error){
	LoggerClientMiddleware,
}

func LoggerServerMiddleware(
	ctx context.Context, arg any,
	next func(ctx context.Context, arg any) (resp any, err error),
) (resp any, err error) {
	log.Println("server request", arg)
	resp, err = next(ctx, arg)
	log.Println("server response", resp)
	return resp, err
}

func LoggerClientMiddleware(
	ctx context.Context,
	req *fasthttp.Request,
	next func(ctx context.Context, req *fasthttp.Request) (resp *fasthttp.Response, err error),
) (resp *fasthttp.Response, err error) {
	log.Println("client request", string(req.URL.String()))
	resp, err = next(ctx, req)
	log.Println("client response", string(resp.Body()))
	return resp, err
}

```

See [example](https://github.com/MUlt1mate/protoc-gen-httpgo/tree/main/example) for more details.

#### Conventions

Golang protobuf generator can produce fields with different case:

```protobuf
message InputMsgName {
 int64 value = 1;
}
```

```go
package main

import "google.golang.org/protobuf/runtime/protoimpl"

type InputMsgName struct {
	state protoimpl.MessageState
	sizeCache protoimpl.SizeCache
	unknownFields protoimpl.UnknownFields

	Value int64 `protobuf:"varint,1,opt,name=value,proto3" json:"value,omitempty"`
}

```

We defined **v**alue and got **V**alue. This works just fine, but keep in mind that server will only check for arguments
with proto names.

* /v1/test?value=1 - correct
* /v1/test?Value=1 - incorrect

#### Files

To send and receive files you need to define file field as a message with the following fields.
The message name can be anything — the plugin identifies file fields by their structure, not by name.

```protobuf
message Request {
 FileMsg document = 1;
 FileMsg anotherDocument = 2;
}

message FileMsg {
 bytes file = 1;
 string name = 2;
 map<string, string> headers = 3;
}
```

## TODO

- implement more web servers
- buf
- streaming
- optionally ignore unknown query parameters

The Best Go Libraries For Generators (15)