 generate documentation for environment variables from Go source files.

# envdoc

envdoc is a tool for generating documentation for environment variables in Go structs.
It takes comments associated with `env` tags in Go structs and creates a Markdown, plaintext or HTML
file with detailed documentation.


 

[![CI](https://github.com/g4s8/envdoc/actions/workflows/go.yml/badge.svg)](https://github.com/g4s8/envdoc/actions/workflows/go.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/g4s8/envdoc.svg)](https://pkg.go.dev/github.com/g4s8/envdoc)
[![codecov](https://codecov.io/gh/g4s8/envdoc/graph/badge.svg?token=sqXWNR755O)](https://codecov.io/gh/g4s8/envdoc)
[![Go Report Card](https://goreportcard.com/badge/github.com/g4s8/envdoc)](https://goreportcard.com/report/github.com/g4s8/envdoc)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 

## Installation

Run it with `go run` in source file:
```go
//go:generate go run github.com/g4s8/envdoc@latest -output environments.md -type Config
type Config struct {
 // ...
}
```

Or download binary to run it:
```bash
go install github.com/g4s8/envdoc@latest
```

And use it in code:

```go
//go:generate envdoc -output environments.md
type Config struct {
 // ...
}
```

## Usage

```go
//go:generate envdoc -output <output_file_name>
```

 * `-dir` (path string, *optional*) - Specify the directory to search for files. Default is the file dir with `go:generate` command.
 * `-files` (glob string, *optional*) - File glob pattern to specify file names to process. Default is the single file with `go:generate`.
 * `-types` (glob string, *optional*) - Type glob pattern for type names to process. If not specified, the next type after `go:generate` is used.
 * `-output` (path string, **required**) - Output file name for generated documentation.
 * `-format` (`enum(markdown, plaintext, html, dotenv)` string, *optional*) - Output format for documentation. Default is `markdown`.
 * `-no-styles` (`bool`, *optional*) - If true, CSS styles will not be included for `html` format.
 * `-env-prefix` (`string`, *optional*) - Sets additional global prefix for all environment variables.
 * `-field-names` (`bool`, *optional*) - Use field names as env names if `env:` tag is not specified.
 * `-debug` (`bool`, *optional*) - Enable debug output.

These params are deprecated and will be removed in the next major release:
 * `-type` - Specify one type to process.
 * `-all` - Process all types in a file.

Both parameters could be replaced with `-types` param:
 - Use `-types=Foo` instead of `-type=Foo`.
 - Use `-types='*'` instead of `-all`.

## Example

Suppose you have the following Go file `config.go`:

```go
package foo

//go:generate envdoc --output env-doc.md
type Config struct {
 // Port to listen for incoming connections
 Port int `env:"PORT,required"`
 // Address to serve
 Address string `env:"ADDRESS" envDefault:"localhost"`
}
```

And the `go:generate` line above creates documentation in `env-doc.md` file:

```md
# Environment Variables

- `PORT` (**required**) - Port to listen for incoming connections
- `ADDRESS` (default: `localhost`) - Address to serve
```

See [_examples](./_examples/) dir for more details.

## Compatibility

This tool is compatible with
- full compatibility: [caarlos0/env](https://github.com/caarlos0/env)
- partial compatibility: [sethvargo/go-envconfig](https://github.com/sethvargo/go-envconfig)
- partial compatibility: [joeshaw/envdecode](https://github.com/joeshaw/envdecode)

*Let me know about any new lib to check compatibility.*


## Contributing

If you find any issues or have suggestions for improvement, feel free to open an issue or submit a pull request.

## License

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

envdoc

# Generic
[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/usk81/generic)
[![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://github.com/usk81/generic/blob/master/LICENSE)
![](https://github.com/usk81/generic/workflows/preliminary%20review/badge.svg)
[![codecov](https://codecov.io/gh/usk81/generic/branch/master/graph/badge.svg)](https://codecov.io/gh/usk81/generic)
[![Go Report Card](https://goreportcard.com/badge/github.com/usk81/generic)](https://goreportcard.com/report/github.com/usk81/generic)

flexible data type for Go

support: Go 1.12+

## Install

standard `go get`:

```
go get -u github.com/usk81/generic/v2
```

## Usage

encode/decode:

```go
package main

import (
	"encoding/json"
	"github.com/usk81/generic/v2"
)

type User struct {
	Name String      `json:"name"`
	Age  generic.Int `json:"age"`
}

var user1 User
u1 := []byte(`{"name":"Daryl Dixon","age":"40"}`)
json.Unmarshal([]byte(u1), &user1)
b, _ := json.Marshal(user1)
Println(string(b))
// {"name":"Daryl Dixon","age":40}

var user2 User
u2 := []byte(`{"name":"Rick Grimes"}`)
json.Unmarshal([]byte(u2), &user2)
b, _ := json.Marshal(user2)
Println(string(b))
// {"name":"Rick Grimes","age":null}
```

set:

```go
package main

import (
	"fmt"
	"github.com/usk81/generic"
)

func main() {
	v := 1.0

	var tb generic.Bool
	tb.Set(v)
	vb := tb.Weak()
	fmt.Printf("%v, (%T)\n", vb, vb)
	// true, (bool)

	var tf generic.Float
	tf.Set(v)
	vf := tf.Weak()
	fmt.Printf("%v, (%T)\n", vf, vf)
	// 1, (float64)

	var ti generic.Int
	ti.Set(v)
	vi := ti.Weak()
	fmt.Printf("%v, (%T)\n", vi, vi)
	// 1, (int64)

	var ts generic.String
	ts.Set(v)
	vs := ts.Weak()
	fmt.Printf("%v, (%T)\n", vs, vs)
	// 1, (string)

	var tt generic.Time
	tt.Set(v)
	vt := tt.Weak()
	fmt.Printf("%v, (%T)\n", vt.UTC(), vt)
	// 1970-01-01 09:00:01 +0900 JST, (time.Time)

	var tu generic.Uint
	tu.Set(v)
	vu := tu.Weak()
	fmt.Printf("%v, (%T)\n", vu, vu)
	// 1, (uint64)
}
```

## Benchmarks

### Marshal

#### Bool

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 5000000 | 240 ns | 185 | 3 |
| 2.0.0  | 200000000 | 6.69 ns | 0 | 0 |

#### Float

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 3000000 | 425 ns | 192 | 3 |
| 2.0.0  | 5000000 | 260 ns | 64 | 3 |

#### Int

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 5000000 | 265 ns | 192 | 3 |
| 2.0.0  | 20000000 | 70.5 ns | 16 | 2 |

#### String (small)

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 3000000 | 382 ns | 200 | 3 |
| 2.0.0  | 20000000 | 89.0 ns | 128 | 2 |

#### String (Large)

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 1000000 | 1056 ns | 776 | 4 |
| 2.0.0  | 5000000 | 237 ns | 896 | 2 |

#### Time

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 1000000 | 1122 ns | 360 | 5 |
| 2.0.0  | 3000000 | 401 ns | 48 | 1 |

#### TimestampMS

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 20000000 | 97.9 ns | 32 | 2 |
| 2.0.0  | 20000000 | 91.2 ns | 32 | 2 |

#### TimestampNano

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 10000000 | 114 ns | 64 | 2 |
| 2.0.0  | 10000000 | 112 ns | 64 | 2 |

#### Timestamp

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 20000000 | 88.4 ns | 32 | 2 |
| 2.0.0  | 20000000 | 86.7 ns | 32 | 2 |

#### Uint

| version | requests | /op | B/op | allocs/op |
|---|---|---|---|---|
| 1.0.0  | 5000000 | 277 ns | 192 | 3 |
| 2.0.0  | 20000000 | 64.2 ns | 16 | 2 |

## Licence

[MIT](https://github.com/usk81/generic/blob/master/LICENSE)

## Author

[Yusuke Komatsu](https://github.com/usk81)


generic

# genny - Generics for Go

[![Build Status](https://travis-ci.org/cheekybits/genny.svg?branch=master)](https://travis-ci.org/cheekybits/genny) [![GoDoc](https://godoc.org/github.com/cheekybits/genny/parse?status.png)](http://godoc.org/github.com/cheekybits/genny/parse)

Install:

```
go get github.com/cheekybits/genny
```

=====

(pron. Jenny) by Mat Ryer ([@matryer](https://twitter.com/matryer)) and Tyler Bunnell ([@TylerJBunnell](https://twitter.com/TylerJBunnell)).

Until the Go core team include support for [generics in Go](http://golang.org/doc/faq#generics), `genny` is a code-generation generics solution. It allows you write normal buildable and testable Go code which, when processed by the `genny gen` tool, will replace the generics with specific types.

 * Generic code is valid Go code
 * Generic code compiles and can be tested
 * Use `stdin` and `stdout` or specify in and out files
 * Supports Go 1.4's [go generate](http://tip.golang.org/doc/go1.4#gogenerate)
 * Multiple specific types will generate every permutation
 * Use `BUILTINS` and `NUMBERS` wildtype to generate specific code for all built-in (and number) Go types
 * Function names and comments also get updated

## Library

We have started building a [library of common things](https://github.com/cheekybits/gennylib), and you can use `genny get` to generate the specific versions you need.

For example: `genny get maps/concurrentmap.go "KeyType=BUILTINS ValueType=BUILTINS"` will print out generated code for all types for a concurrent map. Any file in the library may be generated locally in this way using all the same options given to `genny gen`.

## Usage

```
genny [{flags}] gen "{types}"

gen - generates type specific code from generic code.
get <package/file> - fetch a generic template from the online library and gen it.

{flags} - (optional) Command line flags (see below)
{types} - (required) Specific types for each generic type in the source
{types} format: {generic}={specific}[,another][ {generic2}={specific2}]

Examples:
 Generic=Specific
 Generic1=Specific1 Generic2=Specific2
 Generic1=Specific1,Specific2 Generic2=Specific3,Specific4

Flags:
 -in="": file to parse instead of stdin
 -out="": file to save output to instead of stdout
 -pkg="": package name for generated files
 -tag="": build tag that is stripped from output
```

 * Comma separated type lists will generate code for each type

### Flags

 * `-in` - specify the input file (rather than using stdin)
 * `-out` - specify the output file (rather than using stdout)

### go generate

To use Go 1.4's `go generate` capability, insert the following comment in your source code file:

```
//go:generate genny -in=$GOFILE -out=gen-$GOFILE gen "KeyType=string,int ValueType=string,int"
```

 * Start the line with `//go:generate `
 * Use the `-in` and `-out` flags to specify the files to work on
 * Use the `genny` command as usual after the flags

Now, running `go generate` (in a shell) for the package will cause the generic versions of the files to be generated.

 * The output file will be overwritten, so it's safe to call `go generate` many times
 * Use `$GOFILE` to refer to the current file
 * The `//go:generate` line will be removed from the output

To see a real example of how to use `genny` with `go generate`, look in the [example/go-generate directory](https://github.com/cheekybits/genny/tree/master/examples/go-generate).

## How it works

Define your generic types using the special `generic.Type` placeholder type:

```go
type KeyType generic.Type
type ValueType generic.Type
```

 * You can use as many as you like
 * Give them meaningful names

Then write the generic code referencing the types as your normally would:

```go
func SetValueTypeForKeyType(key KeyType, value ValueType) { /* ... */ }
```

 * Generic type names will also be replaced in comments and function names (see Real example below)

Since `generic.Type` is a real Go type, your code will compile, and you can even write unit tests against your generic code.

#### Generating specific versions

Pass the file through the `genny gen` tool with the specific types as the argument:

```
cat generic.go | genny gen "KeyType=string ValueType=interface{}"
```

The output will be the complete Go source file with the generic types replaced with the types specified in the arguments.

## Real example

Given [this generic Go code](https://github.com/cheekybits/genny/tree/master/examples/queue) which compiles and is tested:

```go
package queue

import "github.com/cheekybits/genny/generic"

// NOTE: this is how easy it is to define a generic type
type Something generic.Type

// SomethingQueue is a queue of Somethings.
type SomethingQueue struct {
 items []Something
}

func NewSomethingQueue() *SomethingQueue {
 return &SomethingQueue{items: make([]Something, 0)}
}
func (q *SomethingQueue) Push(item Something) {
 q.items = append(q.items, item)
}
func (q *SomethingQueue) Pop() Something {
 item := q.items[0]
 q.items = q.items[1:]
 return item
}
```

When `genny gen` is invoked like this:

```
cat source.go | genny gen "Something=string"
```

It outputs:

```go
// This file was automatically generated by genny.
// Any changes will be lost if this file is regenerated.
// see https://github.com/cheekybits/genny

package queue

// StringQueue is a queue of Strings.
type StringQueue struct {
 items []string
}

func NewStringQueue() *StringQueue {
 return &StringQueue{items: make([]string, 0)}
}
func (q *StringQueue) Push(item string) {
 q.items = append(q.items, item)
}
func (q *StringQueue) Pop() string {
 item := q.items[0]
 q.items = q.items[1:]
 return item
}
```

To get a _something_ for every built-in Go type plus one of your own types, you could run:

```
cat source.go | genny gen "Something=BUILTINS,*MyType"
```

#### More examples

Check out the [test code files](https://github.com/cheekybits/genny/tree/master/parse/test) for more real examples.

## Writing test code

Once you have defined a generic type with some code worth testing:

```go
package slice

import (
 "log"
 "reflect"

 "github.com/stretchr/gogen/generic"
)

type MyType generic.Type

func EnsureMyTypeSlice(objectOrSlice interface{}) []MyType {
 log.Printf("%v", reflect.TypeOf(objectOrSlice))
 switch obj := objectOrSlice.(type) {
 case []MyType:
 log.Println(" returning it untouched")
 return obj
 case MyType:
 log.Println(" wrapping in slice")
 return []MyType{obj}
 default:
 panic("ensure slice needs MyType or []MyType")
 }
}
```

You can treat it like any normal Go type in your test code:

```go
func TestEnsureMyTypeSlice(t *testing.T) {

 myType := new(MyType)
 slice := EnsureMyTypeSlice(myType)
 if assert.NotNil(t, slice) {
 assert.Equal(t, slice[0], myType)
 }

 slice = EnsureMyTypeSlice(slice)
 log.Printf("%#v", slice[0])
 if assert.NotNil(t, slice) {
 assert.Equal(t, slice[0], myType)
 }

}
```

### Understanding what `generic.Type` is

Because `generic.Type` is an empty interface type (literally `interface{}`) every other type will be considered to be a `generic.Type` if you are switching on the type of an object. Of course, once the specific versions are generated, this issue goes away but it's worth knowing when you are writing your tests against generic code.

### Contributions

 * See the [API documentation for the parse package](http://godoc.org/github.com/cheekybits/genny/parse)
 * Please do TDD
 * All input welcome

genny

brings design-by-contract to Go by synchronizing the code with the documentation.

gocontracts
===========
![build status](https://travis-ci.com/Parquery/gocontracts.svg?branch=master)
[![Coverage Status](https://coveralls.io/repos/github/Parquery/gocontracts/badge.svg?branch=master)](https://coveralls.io/github/Parquery/gocontracts?branch=master)
[![Go Report Card](https://goreportcard.com/badge/github.com/Parquery/gocontracts)](https://goreportcard.com/report/github.com/Parquery/gocontracts)
[![godoc](https://img.shields.io/badge/godoc-reference-5272B4.svg)](https://godoc.org/github.com/Parquery/gocontracts/gocontracts)

gocontracts is a tool for
[design-by-contract](https://en.wikipedia.org/wiki/Design_by_contract) in Go.

It generates pre- and post-condition checks from the function descriptions so
that the contracts are included in the documentation and automatically
reflected in the code.

(If you need invariants, please let us know by commenting on this issue: https://github.com/Parquery/gocontracts/issues/25.)

Workflow
--------
You invoke gocontracts on an individual Go file. Gocontracts will parse the file
and examine the descriptions of all the functions for contracts. The existing
contract checks will be overwritten to match the contracts in the description.

A usual workflow includes defining the contracts in the function
description and invoking gocontracts to automatically update them in the code.

Each contract is defined as a one-line item in a bulleted list. Gocontracts
does not validate the correctness of the conditions (_e.g._ undefined variables,
syntax errors _etc._). The code is simply inserted as-is in the header of the
function body.

Since contracts are logical conditions of the function, failing a contract
causes a `panic()`. If you need to validate the input, rather than check
logical pre- and post-conditions of the function, return an `error` and do
not abuse the contracts.

Related Projects
================
At the time of this writing (2018-08-19), we found only a library that
implemented design-by-contract as functions (https://github.com/lpabon/godbc) and
a draft implementation based on decorators (https://github.com/ligurio/go-contracts).

None of them allowed us to synchronize the documentation with the code.

Examples
========
Simple Example
--------------

Given a function with contracts defined in the description, but no checks
previously written in code:

```go
package somepackage

// SomeFunc does something.
//
// SomeFunc requires:
// * x >= 0
// * x < 100
//
// SomeFunc ensures:
// * !strings.HasSuffix(result, "smth")
func SomeFunc(x int) (result string) {
	// ...
}
```

, gocontracts will generate the following code:

```go
package somepackage

// SomeFunc does something.
//
// SomeFunc requires:
// * x >= 0
// * x < 100
//
// SomeFunc ensures:
// * !strings.HasSuffix(result, "smth")
func SomeFunc(x int) (result string) {
	// Pre-conditions
	switch {
	case !(x >= 0):
		panic("Violated: x >= 0")
	case !(x < 100):
		panic("Violated: x < 100")
	default:
		// Pass
	}

	// Post-condition
	defer func() {
		if strings.HasSuffix(result, "smth") {
			panic("Violated: !strings.HasSuffix(result, \"smth\")")
		}
	}()

	// ...
}
```

Note that you have to manually import the `strings` package since goconracts
is not smart enough to do that for you.

Additionally, if you want to use `go doc`, you have to indent conditions
with a space in the function description so that `go doc` renders them
correctly as bullet points.

Condition Labels
----------------
Certain conditions can be hard to understand when the formal definition lacks
a textual description. Gocontracts therefore allows you to introduce 
condition labels to clarify the intent:

```go
package somepkg

// SomeFunc does something.
//
// SomeFunc requires:
// * positive: x > 0
// * not too large: x < 100
func SomeFunc(x int, y int) (result string, err error) {
	// Pre-conditions
	switch {
	case !(x > 0):
		panic("Violated: positive: x > 0")
	case !(x < 100):
		panic("Violated: not too large: x < 100")
	default:
		// Pass
	}
	
	// ...
}
```

Since we need to distinguish the condition labels from the condition
code, we had to restrict the labels to strings of characters 
`[a-zA-Z0-9_;.\-=' ]`. Otherwise, if we allowed a full character set,
there would be ambiguities between the label and the code.

(We decided against clutter in the documentation such as Go string literals.
It is our hope that restricted character set should suit 
99% use cases out there. Please let us know if this is not the case.
See also 
https://github.com/golang/go/issues/16666 .)

Condition Initialization
------------------------
Go allows you to initialize a condition and execute a simple statement before
 the check. For example, the initialization is common when checking if an
 item belongs to a map:
 
```go
if _, ok := someMap[3]; ok {
	...
}
```

Following Go, Gocontracts also allows you to include the initialization in
the condition. The following code snippet shows you how to document 
the initialization and what Gocontracts generates:

```go
// SomeFunc does something.
//
// SomeFunc requires:
// * _, ok := someMap[3]; ok
func SomeFunc(someMap map[string]bool) {
	// Pre-condition
	if _, ok := someMap[3]; !ok {
		panic("Violated: _, ok := someMap[3]; ok")
	}

	// ...
}
``` 

Conditioning on a Variable
--------------------------
Usually, functions either return an error if something went wrong or
valid results otherwise. To ensure the contracts conditioned on the error,
use implication and write:

```go
// Range returns a range of the timestamps available in the database.
//
// Range ensures:
// * err != nil || (empty || first < last)
func (t *Txn) Range() (first int64, last int64, empty bool, err error) {
	// ...
}
```

. Gocontracts will generate the following code:

```go
// Range returns a range of the timestamps available in the database.
//
// Range ensures:
// * err != nil || (empty || first <= last)
func (t *Txn) Range() (first int64, last int64, empty bool, err error) {
	// Post-condition
	defer func() {
	 if !(err != nil || (empty || first < last)) {
	 	panic("Violated: err != nil || (empty || first < last)")
	 }	
	}()
	
	// ...
}
```

Note that conditioning can be seen as logical implication
(`A ⇒ B` can be written as `¬A ∨ B`). In the above example, we chained
multiple implications as
`err == nil ⇒ (¬ empty ⇒ first ≤ last)`.

State Transitions
-----------------
When you want to formally define contracts on state transitions you need 
to capture the state _before_ and _after_ the function execution. However,
Gocontract's conventional post-conditions allow you only to access the state
_afer_ the execution.

In order to capture the state _before_ the execution, you need to write a
_preamble_. The preamble is a code snippet written in your documentation
and automatically synced with the function body by gocontracts. The snippet
must follow the Godoc convetion and be indented with a whitespace (or a tab).

The preamble is executed just after the pre-condition(s) have been verified.

Here is a brief (and admittedly a bit constructed) example 
with the generated code already included: 

```go
package somepackage

// increaseFirst increases the first element of the array.
//
// increaseFirst requires:
// * len(a) > 0
//
// increaseFirst preamble:
// oldFirst := a[0]
//
// increaseFirst ensures:
// * a[0] == oldFirst + 1
func increaseFirst(a []int) {
	// Pre-condition
	if !(len(a) > 0) {
		panic("Violated: len(a) > 0")
	}

	// Preamble starts.
	oldFirst := a[0]
	// Preamble ends.

	// Post-condition
	defer func() {
		if !(a[0] == oldFirst + 1) {
			panic("Violated: a[0] == oldFirst + 1")
		}
	}()

	// Implementation
	a[0]++
}
```


Toggling Contracts
------------------
When developing a library, it is important to give your users a possibility to toggle families of contracts so that they can adapt _your_ contracts to _their_ use case. For example, some contracts of your library should be verified in testing and in production, some should be verified only in testing of _their_ modules and others should be verified only in _your_ unit tests, but not in _theirs_.

To that end, you can use build tags to allow toggling of contracts at compile time (https://golang.org/pkg/go/build/#hdr-Build_Constraints). Define for each of the contract family a separate file which is built dependening on the build tag. In each of these files, define constant booleans (_e.g._, `InTest`, `InUTest`). Depending on the scenario, set these variables appropriately: in production scenario, `InTest = false` and `InUTest = false`, in the test scenario for others `InTest = true` and `InUTest = false`, while in the scenario of _your_ unit tests `InTest = true` and `InUTest = true`.

The examples of the three files follow.

`contracts_prod.go`:
```go
// +build prod,!test,!utest

package somepackage

const InTest = false
const InUTest = false
```

`contracts_testing.go`:
```go
// +build !prod,test,!utest

package somepackage

const InTest = true
const InUTest = false
```

`contracts_utest.go`:
```go
// +build !prod,!test,utest

package somepackage

const InTest = true
const InUTest = true
```

Include each of these boolean constants in your contract conditions and `&&`
with the condition.
For example, this is how you extend the postcondition of the function `Range`
written in the previous section to be verified only in _yours_ and _theirs_
tests, but not in production:

```go
// Range returns a range of the timestamps available in the database.
//
// Range ensures:
// * !InTest || (err != nil || (empty || first <= last))
func (t *Txn) Range() (first int64, last int64, empty bool, err error) {
	...
}
```

Since constant booleans are placed first in the conjunction,
the rest of the condition will not be evaluated incurring thus no
computational overhead in the production at runtime.

Usage
=====
Gocontracts reads the Go file and outputs the modified source code to standard
output:

```bash
gocontracts /path/to/some/file.go
```

You can modify the file in-place by supplying the `-w` argument:

```bash
gocontracts -w /path/to/some/file.go
```

If you want to remove the contract checks from the code, supply the
`-r` argument:

```bash
gocontracts -w -r /path/to/some/file.go
```

The remove argument is particularly useful when you have a build system
in place and you want to distinguish between the debug code and the
release (production) code.

Before building the release code, run the gocontracts with `-r` to remove
the checks from the code.

Installation
============
We provide x86 Linux binaries in the "Releases" section.

To compile from code, run:

```bash
go get -u github.com/Parquery/gocontracts
```

Development
===========
* Fork the repository to your user on Github.

* Get the original repository:
	```bash
	go get github.com/Parquery/gocontracts
	```

* Indicate that the local repository is a fork:
	```bash
	cd gocontracts
	git remote add fork https://github.com/YOUR-GITHUB-USERNAME/gocontracts.git
	```

* Make your changes.

* Push the changes from the local repository to your remote fork:
	 ```bash
	 git push fork
	 ```

* Create a pull request on Github and send it for review.

Versioning
==========
We follow [Semantic Versioning](http://semver.org/spec/v1.0.0.html).
The version X.Y.Z indicates:

* X is the major version (backward-incompatible),
* Y is the minor version (backward-compatible), and
* Z is the patch version (backward-compatible bug fix).

gocontracts

Generate orm models corresponding to golang by specifying sql ddl file, which can be used by gorm.

[![GoDoc](https://godoc.org/github.com/mafulong/godal?status.svg)](https://pkg.go.dev/github.com/mafulong/godal)
[![Codecov.io](https://codecov.io/github/mafulong/godal/coverage.svg?branch=main)](https://codecov.io/github/mafulong/godal?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/mafulong/godal)](https://goreportcard.com/report/github.com/mafulong/godal)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)

godal
===

[English](README.md) | [中文](README_CN.md) 

godal provides the ability to generate specific golang code. The goal is to enable developers to write fast code in an
expressive way.

Functions:

1. Generate orm model corresponding to golang by specifying sql ddl file, which can be used by gorm.
2. Update later

godal has been added to [awesome-go](https://awesome-go.com/), [MR link](https://github.com/avelino/awesome-go/pull/3857/)
## Usage Documentation

## Installation

Using this package requires a working Go
environment. [See the install instructions for Go](http://golang.org/doc/install.html).

Go Modules are required when using this
package. [See the go blog guide on using Go Modules](https://blog.golang.org/using-go-modules).

How to install godal?

```shell
git clone git@github.com:mafulong/godal.git
cd godal
go install
```

Make sure that you can have result when call commend`which godal`

## SQL to golang model

```shell
godal gen model --database {your databaseName} {your sqlFile}
```

### Example

You can enter the test directory in this repo.

```shell
godal gen model --database testdb gen_model.sql
```

[What you can get?](https://github.com/mafulong/godal/test/model/)

example file1:

```go
package testdb

import "time"

type TestTb1 struct {
	TestId         int       `gorm:"Column:test_id" json:"test_id"`
	TestTitle      string    `gorm:"Column:test_title" json:"test_title"`
	TestAuthor     string    `gorm:"Column:test_author" json:"test_author"`
	SubmissionDate time.Time `gorm:"Column:submission_date" json:"submission_date"`
}

func (TestTb1) TableName() string {
	return "test_tb1"
}

```

## License

The MIT License (MIT). Please see [License File](LICENSE) for more information.


godal

# Gonerics

This is the code that powers gonerics.io. More information at [http://bouk.co/blog/idiomatic-generics-in-go/](http://bouk.co/blog/idiomatic-generics-in-go/).


gonerics

# gotests [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/cweill/gotests/blob/master/LICENSE) [![godoc](https://img.shields.io/badge/go-documentation-blue.svg)](https://godoc.org/github.com/cweill/gotests) [![Build Status](https://github.com/cweill/gotests/workflows/Go/badge.svg)](https://github.com/cweill/gotests/actions) [![Coverage Status](https://coveralls.io/repos/github/cweill/gotests/badge.svg?branch=master)](https://coveralls.io/github/cweill/gotests?branch=master) [![codebeat badge](https://codebeat.co/badges/7ef052e3-35ff-4cab-88f9-e13393c8ab35)](https://codebeat.co/projects/github-com-cweill-gotests) [![Go Report Card](https://goreportcard.com/badge/github.com/cweill/gotests)](https://goreportcard.com/report/github.com/cweill/gotests)

`gotests` makes writing Go tests easy. It's a Golang commandline tool that generates [table driven tests](https://github.com/golang/go/wiki/TableDrivenTests) based on its target source files' function and method signatures. Any new dependencies in the test files are automatically imported.

## Demo

The following shows `gotests` in action using the [official Sublime Text 3 plugin](https://github.com/cweill/GoTests-Sublime). Plugins also exist for [Emacs](https://github.com/damienlevin/GoTests-Emacs), also [Emacs](https://github.com/s-kostyaev/go-gen-test), [Vim](https://github.com/buoto/gotests-vim), [Atom Editor](https://atom.io/packages/gotests), [Visual Studio Code](https://github.com/Microsoft/vscode-go), and [IntelliJ Goland](https://www.jetbrains.com/help/go/run-debug-configuration-for-go-test.html).

![demo](https://github.com/cweill/GoTests-Sublime/blob/master/gotests.gif)

## Installation

__Minimum Go version:__ Go 1.6

Use [`go get`](https://golang.org/cmd/go/#hdr-Download_and_install_packages_and_dependencies) to install and update:

```sh
$ go get -u github.com/cweill/gotests/...
```

## Usage

From the commandline, `gotests` can generate Go tests for specific source files or an entire directory. By default, it prints its output to `stdout`.

```sh
$ gotests [options] PATH ...
```

Available options:

```
  -all                  generate tests for all functions and methods

  -excl                 regexp. generate tests for functions and methods that don't
                         match. Takes precedence over -only, -exported, and -all

  -exported             generate tests for exported functions and methods. Takes
                         precedence over -only and -all

  -i                    print test inputs in error messages

  -only                 regexp. generate tests for functions and methods that match only.
                         Takes precedence over -all

  -nosubtests           disable subtest generation when >= Go 1.7

  -parallel             enable parallel subtest generation when >= Go 1.7.

  -w                    write output to (test) files instead of stdout

  -template_dir         Path to a directory containing custom test code templates. Takes
                         precedence over -template. This can also be set via environment
                         variable GOTESTS_TEMPLATE_DIR

  -template             Specify custom test code templates, e.g. testify. This can also
                         be set via environment variable GOTESTS_TEMPLATE

  -template_params_file read external parameters to template by json with file

  -template_params      read external parameters to template by json with stdin
```

## Contributions

Contributing guidelines are in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

`gotests` is released under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).


gotests

Generate Go tests using your own templates.

# GoUnit [![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://github.com/hexdigest/gounit/blob/master/LICENSE) [![Build Status](https://travis-ci.org/hexdigest/gounit.svg?branch=master)](https://travis-ci.org/hexdigest/gounit) [![Coverage Status](https://coveralls.io/repos/github/hexdigest/gounit/badge.svg?branch=master)](https://coveralls.io/github/hexdigest/gounit?branch=master) [![Go Report Card](https://goreportcard.com/badge/github.com/hexdigest/gounit)](https://goreportcard.com/report/github.com/hexdigest/gounit) [![GoDoc](https://godoc.org/github.com/hexdigest/gounit?status.svg)](http://godoc.org/github.com/hexdigest/gounit)

GoUnit is a commandline tool that generates tests stubs based on source function or method signature.

There are plugins for
* [Vim](https://github.com/hexdigest/gounit-vim)
* [Emacs](https://github.com/hexdigest/GoUnit-Emacs)
* [Atom](https://github.com/hexdigest/atom-gounit)
* [Sublime](https://github.com/hexdigest/gounit-sublime)

## Demo

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

## Installation

```
go get -u github.com/hexdigest/gounit/cmd/gounit
```

## Usage of GoUnit

This will generate test stubs for all functions and methods in file.go

```
  $ gounit gen -i file.go 
```

Run `gounit help` for more options

## Custom test templates

If you're not satisfied with the code produced by the default GoUnit test template you can always write your own!
You can use [minimock template](https://github.com/hexdigest/gounit/blob/master/templates/minimock) as an example.
Here is how to add and switch to the custom template:

```
  $ curl https://raw.githubusercontent.com/hexdigest/gounit/master/templates/minimock > minimock
  $ gounit template add minimock
  $ gounit template list

    gounit templates installed

       * default
         minimock

  $ gounit template use minimock
```

Minimock template produces test stubs that are aware of the mocks generated by the [minimock](https://github.com/gojuno/minimock) mock generator. 
By using both of these tools you can automate the process of writing tests and focus on your test cases rather than routine operations.

## Integration with editors and IDEs

To ease an integration of GoUnit with IDEs "gen" subcommand has a "-json" flag.
When -json flag is passed GoUnit reads [JSON requests](https://github.com/hexdigest/gounit/blob/master/client.go#L5) from Stdin in a loop and produces [JSON responses](https://github.com/hexdigest/gounit/blob/master/client.go#L16) with generated test(s) that are written to Stdout.
Using this mode you can generate as many tests as you want by running GoUnit executable only once.


gounit

Generate Haskell inspired functions for your slices.

# Hasgo [![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) [![Build Status](https://travis-ci.com/DylanMeeus/hasgo.svg?branch=master)](https://travis-ci.com/DylanMeeus/hasgo) 
* Coverage status: [gocover.io](https://gocover.io/github.com/DylanMeeus/hasgo/types)
* Our report card: [![Go Report Card](https://goreportcard.com/badge/github.com/DylanMeeus/hasgo)](https://goreportcard.com/report/github.com/DylanMeeus/hasgo)

Hasgo is a code generator with functions influenced by Haskell. 
It comes with some types out-of-the-box so you can start using it without running the generator.
Specifically you can start using Hasgo's `Strings` and `Ints` types. 

We want to focus on being:
* Immutable 
* Strongly-Typed (no `interface{}`)
* Nil-safe


## Pie

The inspiration for Hasgo, as well as some ideas around implementation come from the lovely [Pie
library](https://github.com/elliotchance/pie), made by [Elliot Chance](https://github.com/elliotchance). 
It's safe to say that Hasgo would not exist without Pie. However, the way Pie and Hasgo work is not
the same and neither is the focus of the project. If you don't find a function in Hasgo, check out
Pie! :smiley:

## Example

```go
import . "github.com/DylanMeeus/hasgo/types"
func EpicFunction() {
	// create a range of -10 -> 10. Take the absolute values, keep only even numbers, and sum them.
	result := IntRange(-10,10).
		Abs().
		Filter(func(i int64) bool {
			return i % 2 == 0
		}).
		Sum()
	// result = 60 
}
```

You can find more [examples here](https://github.com/DylanMeeus/hasgo/tree/master/examples). 

## Installation

```bash
go get -u github.com/DylanMeeus/hasgo
```

Or add hasgo to your `go.mod` file.

`require github.com/DylanMeeus/hasgo/v1.0.2`

## Types 
* `Ints` ([]int64)
* `Strings` ([]string)

## Functions

These are the function currently available with Hasgo.
It shows you which type of data they operate on as well as the Haskell type definition. 
The first symbol of the signature is actually the method receiver in Go terms. 

Alternatively, you can consult the [godoc](https://godoc.org/github.com/DylanMeeus/hasgo/types)

### Generic functions
These functions can be generated for every type.

| Function     | Signature                        | String | Number | Struct | Description |
|------------  | -------------------------------  | :----: | :----: | :----: | ----------- |
| `Abs`        | `[a] -> [a]`                     |        |   ✓    |        | Return a slice containing the absolute values|
| `All`        | `[a] -> (a -> bool) -> bool`     |   ✓    |   ✓    |    ✓   | Returns true if the predicate applies to all elements in the slice|
| `Any`        | `[a] -> (a -> bool) -> bool`     |   ✓    |   ✓    |    ✓   | Returns true if one or more elements satisfy the predicate|
| `Average`    | `[a] -> a`                       |        |   ✓    |        | Returns the average of all elements|
| `Break`      | `(a -> bool) -> [a] -> ([a], [a])`|  ✓    |   ✓    |    ✓   | Returns a tuple of all elements until the first one that matches the predicate, followed by the remaining elements. |
| `Delete`     | `[a] -> a -> [a]`                |   ✓    |   ✓    |    ✓   | Returns the slice with the first occurance of the element deleted.|
| `Drop`       | `Int -> [a] -> [a]`              |   ✓    |   ✓    |    ✓   | Returns the suffix of xs after the first n elements. |
| `DropWhile`  | `(a -> bool) -> [a] -> [a]`      |   ✓    |   ✓    |    ✓   | Returns the suffix of xs after the predicate's first failure. |
| `Elem`       | `[a] -> a -> bool`               |   ✓    |   ✓    |    ✓   | Returns true if the slice contains the element.|
| `Filter`     | `[a] -> (a -> bool) -> [a]`      |   ✓    |   ✓    |    ✓   | Filter the slice based on a predicate|
| `Foldl`      | `[a] -> a -> (a -> a -> a) -> a` |   ✓    |   ✓    |    ✓   | Left fold over the slice to reduce it to one element with starting value.|
| `Foldl1`     | `[a] -> (a -> a -> a) -> a`      |   ✓    |   ✓    |    ✓   | Left fold over the slice to reduce it to one element.|
| `Foldr`      | `[a] -> b -> (a -> b -> b) -> b` |   ✓    |   ✓    |    ✓   | Right fold over the slice to reduce it to one element with a starting value. |
| `Foldr1`     | `[a] -> (a -> a -> a) -> a`      |   ✓    |   ✓    |    ✓   | Right fold over the slice to reduce it to one element. |
| `Group`      | `[a] -> [[a]]`                   |   ✓    |   ✓    |    ✓   | Returns a list of lists where each list contains grouped values from the input list.|
| `Head`       | `[a] -> a`                       |   ✓    |   ✓    |    ✓   | Return the first element|
| `Init`       | `[a] -> [a]`                     |   ✓    |   ✓    |    ✓   | Returns all elements minus the last|
| `Inits`      | `[a] -> [[a]]`                   |   ✓    |   ✓    |    ✓   | Returns all initial segments of the slice, shortest first. |
| `Intercalate`| `[a] -> [[a]] -> [a]`            |   ✓    |   ✓    |    ✓   | Intersperses the slice in between the provided 2d-slice |
| `Intersperse`| `[a] -> a -> [a]`                |   ✓    |   ✓    |    ✓   | Intersperses the value in between all elements of the provided slice|  
| `IsPrefixOf` | `[a] -> [a] -> bool`             |   ✓    |   ✓    |    ✓   | Returns true if the current slice is a prefix of the provided slice|  
| `Last`       | `[a] -> a`                       |   ✓    |   ✓    |    ✓   | Returns the last element|
| `Length`     | `[a] -> int`                     |   ✓    |   ✓    |    ✓   | Returns the length of the slice|
| `Map`        | `[a] -> (a -> a) -> [a]`         |   ✓    |   ✓    |    ✓   | Returns a slice with the function applied to each element of the input|
| `Maximum`    | `[a] -> a`                       |        |   ✓    |        | Returns the largest element|
| `MaximumBy`  | `[a] -> (a -> a) -> a -> a`      |   ✓    |   ✓    |    ✓   | Returns the maximum element according to comparator|
| `Minimum`    | `[a] -> a`                       |        |   ✓    |        | Returns the lowest element|
| `Modes`      | `[a] -> [a]`                     |   ✓    |   ✓    |    ✓   | Returns the elements with the highest frequency |
| `Nub`        | `[a] -> [a]`                     |   ✓    |   ✓    |    ✓   | Returns a Slice containing one of each of the input elements |
| `Null`       | `[a] -> bool`                    |   ✓    |   ✓    |    ✓   | Returns true if the slice is empty, false otherwise|
| `Product`    | `[a] -> a`                       |   ✓    |        |        | Returns the product of all elements in the slice.|
| `Reverse`    | `[a] -> [a]`                     |   ✓    |   ✓    |    ✓   | Returns a slice with the elements reversed|
| `Scanl`      | `[a] -> b -> (a -> b -> a) -> [b]`|  ✓    |   ✓    |    ✓   | Left fold over the slice to reduce it to one element with a starting value and return every iteration in a slice. |
| `Sort`       | `[a] -> [a]`                     |   ✓    |   ✓    |        | Returns a sorted slice (original remains unsorted)|
| `Span`       | `(a -> bool) -> [a] -> ([a], [a])`|  ✓    |   ✓    |    ✓   | Returns a tuple of all elements until the first one that does not match the predicate, followed by the remaining elements. |
| `SplitAt`    | `Int -> [a] -> ([a], [a])`       |   ✓    |   ✓    |    ✓   | Returns a tuple with all elements up until the specified index, followed by the elements after the index. |
| `Sum`        | `[a] -> a`                       |   ✓    |   ✓    |    ✓   | The sum of elements in the slice|
| `Tail`       | `[a] -> [a]`                     |   ✓    |   ✓    |    ✓   | Returns all elements minus the first|
| `Tails`      | `[a] -> [[a]]`                   |   ✓    |   ✓    |    ✓   | Returns all final segments of the slice, longest first. |
| `Take`       | `[a] -> uint64 -> [a]`           |   ✓    |   ✓    |    ✓   | Take N elements from the slice, or all if N exceeds the length.|
| `TakeWhile`  | `[a] -> (a -> bool) -> [a]`      |   ✓    |   ✓    |    ✓   | Take all elements until the first one that does not match the predicate.|
| `Uncons`     | `[a] -> (a, [a])`                |   ✓    |   ✓    |    ✓   | Returns a tuple of the head and tail of the slice|
| `Unlines`    | `[a] -> string`                  |   ✓    |   ✓    |    ✓   | Returns a newline separated string of all elements in the slice| 
| `Unwords`    | `[a] -> string`                  |   ✓    |   ✓    |    ✓   | Returns a space-separated string of all elements in the slice| 


### Hardcoded functions

The built-in types (Strings, Ints, Bools) have some functions defined on them that are not generated.
Mostly because we could not create them in a generic way. 


| Type     | Function         | Signature                     | Description  |
|--------- |---------------   |-------------------------------|--------------| 
| `Ints`   | `Equals`         | \*`Ints -> Ints -> bool`      | Returns true if both slices contain the same elements| 
| `Ints`   | `EqualsOrdered`  | \*`Ints -> Ints -> bool`      | Returns true if both slices contain the same elements, in the same position| 
| `Ints`   | `IntRange`       | `int64 -> int64 -> Ints`      | Return an integer range from [start,stop]|
| `Ints`   | `IntReplicate`   | `uint64 -> int64 -> Ints`     | Return a slice with the input element repeated n times|
| `Strings`| `Equals`         | \*`Strings -> Strings -> bool`| Returns true if both slices contain the same elements| 
| `Strings`| `EqualsOrdered`  | \*`Strings -> Strings -> bool`| Returns true if both slices contain the same elements, in the same position| 
| `Strings`| `Lines`          | `string -> Strings`           | Returns Strings separated by a newline.|
| `Strings`| `StringReplicate`| `uint64 -> string -> Strings` | Return a slice with the input element repeated n times|
| `Strings`| `Words`          | `string -> Strings`           | Returns Strings separated by a space.|
| `Bools`  | `And`            | `Bools -> bool`               | Returns true if all bools are true.|
| `Bools`  | `Or`             | `Bools -> bool   `            | Returns true if any bool is true.|

\* (Functions prefixed by a star are functions added to the type itself, where first element in the
signature is the method receiver. So for examples, the Equals method is `Ints{1,2}.Equals(Ints{1})`.
But, the IntRange function looks like `hasgo.IntRange(0,10)`.


## Contributing

You can help out Hasgo in a variety of ways! 
Here are some ideas:

* Use Hasgo! :smiley:
* Spread the word (Write a blog, tweet, talk about..)
* Suggest features (Create an issue to make a suggestion)
* Report bugs (Similarly, create an issue)
* Contribute code. (Create a PR, we'll gladly take a look and help you get it merged!)
	* We have separate [contribution guidelines](CONTRIBUTING.md)
	
## What's in a name?
The name Hasgo is a portmanteau of "Haskell" and "Go". I'm a big fan of both languages, though they
are quite different. It's impossible to write real Haskell-like code in Go. There are some obvious
differences between the languages in terms of syntax. I hope the functions in this library stay as
close as possible to their Haskell implementations. There might be extra functions in here that are
not in Haskell, and there _will_ be functions in Haskell that you won't find here.

The inspiration mainly shows in the naming of functions. If the functions were named after Java
lambdas, it'd be called "Jago". Sorry if you expected more Haskell goodness (I'm open to suggestions
of how more haskell in Hasgo!)

## Real Generics?

Currently I have an experimental implementation of hasgo [here as hasgo2](https://www.github.com/DylanMeeus/hasgo2). It does require a development version of Go installed from source to function correctly at this stage. 



hasgo

Functional options described by Dave Cheney's post "Functional options for friendly APIs".

# options-gen

[![Go Reference](https://pkg.go.dev/badge/github.com/kazhuravlev/options-gen.svg)](https://pkg.go.dev/github.com/kazhuravlev/options-gen)
[![License](https://img.shields.io/github/license/kazhuravlev/options-gen?color=blue)](https://github.com/kazhuravlev/options-gen/blob/master/LICENSE)
[![Build Status](https://github.com/kazhuravlev/options-gen/actions/workflows/go.yml/badge.svg?branch=master)](https://github.com/kazhuravlev/options-gen/actions/workflows/go.yml?query=branch%3Amaster)
[![Go Report Card](https://goreportcard.com/badge/github.com/kazhuravlev/options-gen)](https://goreportcard.com/report/github.com/kazhuravlev/options-gen)
[![CodeCov](https://codecov.io/gh/kazhuravlev/options-gen/branch/master/graph/badge.svg?token=tNKcOjlxLo)](https://codecov.io/gh/kazhuravlev/options-gen)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#go-generate-tools)

Code-generator that allows you to create a functional options like
[Dave Cheney's post](https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis).

Generate the options for your service/client/etc. All that you need is to define a
struct with fields, that can be applied as Option then embed this struct into
yours.

## Installation

```bash
go install github.com/kazhuravlev/options-gen/cmd/options-gen@latest
```

## Usage

```go
package mypkg

import (
	"io"
	"log"
)

//go:generate options-gen -out-filename=options_generated.go -from-struct=Options
type Options struct {
	logger log.Logger `option:"mandatory"`
	listenAddr string `option:"mandatory" validate:"required,hostname_port"`
	closer io.Closer `validate:"required"`
}
```

```bash
go generate ./...
```

This will generate `out-filename` file with options constructor. Like this:

```go
// options_generated.go
package mypkg

import (
	"log"
)

func NewOptions(
	// mandatory options. you cannot ignore or forget them because they are arguments.
	logger log.Logger,
	listenAddr string,
	// optional: you can leave them empty or not.
	other ...Option,
) {
	// ...
}

// Validate will check that all options are in desired state
func (o *Options) Validate() error {
	// ...
}
```

And you can use generated options as follows:

```go
package mypkg

import "fmt"

type Component struct {
	opts Options // struct that you define as struct with options 
}

func New(opts Options) (*Component, error) { // constructor of your service/client/component
	if err := opts.Validate(); err != nil { // always add only these lines for all your constructors
		return nil, fmt.Errorf("cannot validate options: %w", err)
	}

	return &Component{opts: opts}, nil // embed options into your component
}
```

And after that you can use new constructor in (for ex.) `main.go`:

```go
package main

func main() {
	c, err := mypkg.New(mypkg.NewOptions( /* ... */))
	if err != nil {
		panic(err)
	}
}
```

## Usage with Generics

```go
package mypkg

//go:generate options-gen -from-struct=Options
type Options[T any] struct {
	addr string `option:"mandatory" validate:"required,hostname_port"`
	ch <-chan T `option:"mandatory"`
}
```

And just `go generate ./...`.

## Examples

See an [examples](./examples) to get real-world examples.

## Configuration

To configure this tool you should know two things: how to work with cli tool
and how to define options in your `Options` struct.

### CLI tool

All the tool needs is the information about source and target files and packages.
Tool can be invoked by `options-gen` (after [Installation](#Installation)) and
it will have the following arguments:

- `filename` - is a source filename that contains `Options` struct relative
 to the current dir. For example `./pkg/github-client/options.go`.
 Default: `$GOFILE` (file where you placed `//go:generate`).
- `pkg` - name of output filename package. In most cases we can just use
 the same package as the `filename` file. For example `githubclient`.
 Default: `$GOPACKAGE`. Package name same as file where you placed `//go:generate`.
- `from-struct` - name of structure that contains our options. For
 example `Options`.
- `out-filename` - specifies an output filename. This filename will be rewritten
 with options-gen specific content. For
 example `./pkg/github-client/options_generated.go`.

See an [Examples](#Examples).

### Option tag

You can control two important things. The first is about the options constructor

- how `options-gen` will generate `NewOptions` constructor. The second is about
 how to validate data, that has been passed as value for this field.

#### Control the constructor

`options-gen` can generate a constructor that can receive all option fields as
separate arguments. It will force the user to pass each (or someone) option
field to the constructor. Like this:

```go
// Mark Field1 as mandatory
type Options struct {
	field1 string `option:"mandatory"`
}

// options-gen will generate constructor like this
func NewOptions(field1 string, otherOptions ...option)...
```

But, if we do not want to force the user to pass each argument - we can remove
the `option:"mandatory"` feature for this field and get something like this:

```go
// Do not mark Field1 as mandatory
type Options struct {
	field1 string
}

// options-gen will generate constructor like this
func NewOptions(otherOptions ...option)...
```

So, this allows setting only those options fields that user is want to set.

#### Validate field data

After we define the fields, we want to restrict the values of these fields. To
do that we can use a well-known library [validator](https://github.com/go-playground/validator)

Just read the docs for `validator` library and add tag to fields like this:

```go
type Options struct {
	maxDbConn int `validate:"required,min=1,max=16"`
}
```

#### Default values

`options-gen` provide several ways to define defaults for options. You can
choose which mechanism you need by providing a flag `-defaults-from`. By
default, this flag is set to `tag=default`.

- `tag[=TagName]`. This mechanism will try to find a tag `TagName` in field
 tags. By default `TagName` is equal to `default`
- `var[=VariableName]`. This mechanism will copy variable `VariableName` fields
 to your `Options` instance. By default `VariableName` is equal
 to `default<StructName>`. This variable should contain `Options` struct.
- `func[=FunctionName]`. The same as `var`, but for the function name.
 Function `FunctionName` will be called once per `NewOptions` constructor. This
 function should return an `Options` struct.
- `none` to disable defaults.

##### Using tag

For numbers, strings, and `time.Duration` you can set the default value:

```go
// simple example
//go:generate options-gen -from-struct=Options
type Options struct {
	pingPeriod time.Duration `default:"3s" validate:"min=100ms,max=30s"`
	name string `default:"unknown" validate:"required"`
	maxAttempts int `default:"10" validate:"min=1,max=10"`
	eps float32 `default:"0.0001" validate:"gt=0"`
}
```

```go
// custom default tag
//go:generate options-gen -from-struct=Options --default-from=tag=mydefaulttag
type Options struct {
	pingPeriod time.Duration `mydefaulttag:"3s" validate:"min=100ms,max=30s"`
	name string `mydefaulttag:"unknown" validate:"required"`
	maxAttempts int `mydefaulttag:"10" validate:"min=1,max=10"`
	eps float32 `mydefaulttag:"0.0001" validate:"gt=0"`
}
```

It would be relevant if the field were not filled either explicitly or through
functional option.

The default value must be valid for the field type and must satisfy validation
rules.

##### Using variable

Tags allow you to define defaults for simple types like `string`, `number`
, `time.Duration`. When you want to define a variable with prefilled values -
you can do this like that:

```go
// simple example
//go:generate options-gen -from-struct=Options -defaults-from=var
type Options struct {
	httpClient *http.Client
}

var defaultOptions = Options{
	httpClient: &http.Client{},
}
```

```go
// custom variable name
//go:generate options-gen -from-struct=Options -defaults-from=var=myDefaults
type Options struct {
	httpClient *http.Client
}

var myDefaults = Options{
	httpClient: &http.Client{},
}
```

##### Using function

The same as variable. See an examples:

```go
// simple example
//go:generate options-gen -from-struct=Options -defaults-from=func
type Options struct {
	httpClient *http.Client
}

func getDefaultOptions() Options {
	return Options{
		httpClient: &http.Client{},
	}
}
```

```go
// custom function name
//go:generate options-gen -from-struct=Options -defaults-from=func=myDefaults
type Options struct {
	httpClient *http.Client
}

func myDefaults() Options {
	return Options{
		httpClient: &http.Client{},
	}
}
```

##### Disable defaults

If you want to be sure that defaults will not be parsed - you can specify
the `none` for `-defaults-from` flag.

```go
// defaults will now be parsed at all
//go:generate options-gen -from-struct=Options -defaults-from=none
type Options struct {
	name string `default:"joe"`
}
```

#### Which fields are set?

`options-gen` can produce additional code that allows you to check which fields were set. To do this, simply add
the `-with-isset` flag to `options-gen`.

For example, this code with the specified option...

```go
package app

//go:generate options-gen -from-struct=Options -with-isset
type Options struct {
	name string
}
```

...will produce function `func (o *Options) IsSet(field optField) bool{...}`. 

### Custom validator

You can override `options-gen` validator for specific struct by implementing
the `Validator()` method:

```go
import "github.com/mycoolmodule/internal/validator"

// ...

func (Options) Validator() *validator.Validate {
return validator.Validator
}
```

Or you can override `options-gen` validator globally:

```go
package validator

import (
	goplvalidator "github.com/go-playground/validator/v10"
	optsValidator "github.com/kazhuravlev/options-gen/pkg/validator"
)

var Validator = goplvalidator.New()

func init() {
	must(Validator.RegisterValidation( /* ... */))
	must(Validator.RegisterAlias( /* ... */))

	optsValidator.Set(Validator)
}
```

## Contributing

The development process is pretty simple:

- [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repo
 on GitHub
- [Clone](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository)
 your copy of the repo
- [Create a new branch](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
 for your goals
- Install the [Task](https://taskfile.dev/installation/). It's like `Make`, but
 simple
- Check that your working copy is ready to start development by
 running `task check` in repo workdir
- Reach your goals!
- Check that all is ok by `task check`
- [Create](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
 a Pull Request

options-gen

Generate gorm, xorm, sqlx, bun, sql code from SQL file or DSN.

# sqlgen

English | [中文](README_cn.md)

[![Go](https://github.com/anqiansong/sqlgen/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/anqiansong/sqlgen/actions/workflows/go.yml)
[![codecov](https://codecov.io/gh/anqiansong/sqlgen/branch/main/graph/badge.svg?token=8mLCFUqD2l)](https://codecov.io/gh/anqiansong/sqlgen)
[![Go Reference](https://pkg.go.dev/badge/github.com/anqiansong/sqlgen.svg)](https://pkg.go.dev/github.com/anqiansong/sqlgen)
[![Go Report Card](https://goreportcard.com/badge/github.com/anqiansong/sqlgen)](https://goreportcard.com/report/github.com/anqiansong/sqlgen)
[![Release](https://img.shields.io/github/v/release/anqiansong/sqlgen.svg?style=flat-square)](https://github.com/anqiansong/sqlgen)
[![GitHub license](https://img.shields.io/github/license/anqiansong/sqlgen?style=flat-square)](https://github.com/anqiansong/sqlgen/blob/main/LICENSE)

sqlgen is a tool to generate **bun**, **gorm**, **sql**, **sqlx** and **xorm** sql code from SQL
file which is inspired by

- [go-zero](https://github.com/zeromicro/go-zero)
- [goctl](https://github.com/zeromicro/go-zero/tree/master/tools/goctl)
- [sqlc](https://github.com/kyleconroy/sqlc).

# Installation

```bash
go install github.com/anqiansong/sqlgen@latest
```

# Example

See [example](https://github.com/anqiansong/sqlgen/tree/main/example)

# Queries rule

## 1. Function Name

You can define a function via `fn` keyword in line comment, for example:

```sql
-- fn: my_func
SELECT *
FROM user;
```

it will be generated as:

```go
func (m *UserModel) my_func (...) {
...
}
```

## 2. Get One Record

The expression `limit 1` must be explicitly defined if you want to get only one record, for example:

```sql
-- fn: FindOne
select *
from user
where id = ? limit 1;
```

## 3. Marker or Values?

For arguments of SQL, you can use `?` or explicitly values to mark them, in sqlgen, the arguments
will be converted into variables, for example, the following query are equivalent:

> NOTES: It does not apply to rule 2

```sql
-- fn: FindLimit
select *
from user
where id = ?;

-- fn: FindLimit
select *
from user
where id = 1;

```

## 4. SQL Function

sqlgen supports aggregate function queries in sql, other than that, other functions are not
supported so far. All the aggregate function query expressions must contain AS expression, for
example:

```sql
-- fn: CountAll
select count(*) as count
from user;
```

For most query cases, you can
see [example.sql](https://github.com/anqiansong/sqlgen/blob/main/example/example.sql) for details.

# How it works

1. Create a SQL file
2. Write your SQL code in the SQL file
3. Run `sqlgen` to generate code

# Notes

1. Only support MYSQL code generation.
3. Do not support multiple tables in one SQL file.
4. Do not support join query.

sqlgen

XSD (XML Schema Definition) parser and Go/C/Java/Rust/TypeScript code generator.

<img width="450" src="./xgen.svg" alt="xgen logo">

 


 <a href="https://github.com/xuri/xgen/actions?workflow=Go"><img src="https://github.com/xuri/xgen/workflows/Go/badge.svg?branch=master" alt="Build Status"></a>
 <a href="https://codecov.io/gh/xuri/xgen"><img src="https://codecov.io/gh/xuri/xgen/branch/master/graph/badge.svg" alt="Code Coverage"></a>
 <a href="https://goreportcard.com/report/github.com/xuri/xgen"><img src="https://goreportcard.com/badge/github.com/xuri/xgen" alt="Go Report Card"></a>
 <a href="https://pkg.go.dev/github.com/xuri/xgen"><img src="https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white" alt="go.dev"></a>
 <a href="https://opensource.org/licenses/BSD-3-Clause"><img src="https://img.shields.io/badge/license-bsd-orange.svg" alt="Licenses"></a>
 <a href="https://www.paypal.me/xuri"><img src="https://img.shields.io/badge/Donate-PayPal-green.svg" alt="Donate"></a>


# xgen

## Introduction

xgen is a library written in pure Go providing a set of functions that allow you to parse XSD (XML schema definition) files. This library needs Go version 1.10 or later. The full API docs can be seen using go's built-in documentation tool, or online at [go.dev](https://pkg.go.dev/github.com/xuri/xgen).

`xgen` commands automatically compiles XML schema files into the multi-language type or class declarations code.

Install the command line tool first.

If you're using Go 1.17 and later, installing executables with `go install`

```sh
go install github.com/xuri/xgen/cmd/xgen@latest
```

If you're using Go 1.16 and earlier, installing executables with `go get`

```sh
go get -u -v github.com/xuri/xgen/cmd/...
```

The command below will walk on the `xsd` path and generate Go language struct code under the `output` directory.

```text
$ xgen -i /path/to/your/xsd -o /path/to/your/output -l Go
```

Usage:

```text
$ xgen [<flag> ...] <XSD file or directory> ...
 -i <path> Input file path or directory for the XML schema definition
 -o <path> Output file path or directory for the generated code
 -p Specify the package name
 -l Specify the language of generated code (Go/C/Java/Rust/TypeScript)
 -h Output this help and exit
 -v Output version and exit
```

## XSD (XML Schema Definition)

XSD, a recommendation of the World Wide Web Consortium ([W3C](https://www.w3.org)), specifies how to formally describe the elements in an Extensible Markup Language ([XML](https://www.w3.org/TR/xml/)) document. It can be used by programmers to verify each piece of item content in a document. They can check if it adheres to the description of the element it is placed in.

XSD can be used to express a set of rules to which an XML document must conform in order to be considered "valid" according to that schema. However, unlike most other schema languages, XSD was also designed with the intent that determination of a document's validity would produce a collection of information adhering to specific data types. Such a post-validation infoset can be useful in the development of XML document processing software.

## Contributing

Contributions are welcome! Open a pull request to fix a bug, or open an issue to discuss a new feature or change. XSD is compliant with [XML Schema Part 1: Structures Second Edition](https://www.w3.org/TR/xmlschema-1/).

## Licenses

This program is under the terms of the BSD 3-Clause License. See [https://opensource.org/licenses/BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause).

Logo is designed by [xuri](https://xuri.me). Licensed under the [Creative Commons 3.0 Attributions license](http://creativecommons.org/licenses/by/3.0/).

The Best Go Libraries For Go Generate Tools (12)