close #1: add a first enum implementation

Author: FabienMht

.gitignore

@@ -1,21 +1,6 @@
-# If you prefer the allow list template instead of the deny list, see community template:
-# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
-#
-# Binaries for programs and plugins
-*.exe
-*.exe~
-*.dll
-*.so
-*.dylib
-
-# Test binary, built with `go test -c`
-*.test
-
-# Output of the go coverage tool, specifically when used with LiteIDE
+# Trivy cache fodler
+.trivy
+# Task cache fodler
+.task
+# Coverage files
 *.out
-
-# Dependency directories (remove the comment below to include it)
-# vendor/
-
-# Go workspace file
-go.work

.golangci.yml

@@ -0,0 +1,98 @@
+run:
+  timeout: 5m
+  modules-download-mode: readonly
+  skip-files:
+    - "example_*"
+
+linters:
+  enable:
+    - errcheck
+    - gosimple
+    - govet
+    - ineffassign
+    - staticcheck
+    - typecheck
+    - unused
+    - goimports
+    - revive
+    - nolintlint
+    - usestdlibvars
+    - tagliatelle
+    - predeclared
+    - errorlint
+    - unconvert
+    - tagalign
+    - gofumpt
+    - misspell
+    - nonamedreturns
+    - forbidigo
+
+linters-settings:
+  errcheck:
+    # To check errors in type assertions
+    check-type-assertions: true
+    # To not allows to blank errors with _
+    check-blank: true
+
+  misspell:
+    # To set the language to check with
+    locale: US
+
+  tagalign:
+    # To not align tag
+    align: false
+    # To sort tags by name
+    sort: true
+    # To specify the order of tags, the other tags will be sorted by name
+    order:
+      - json
+
+  errorlint:
+    # To check whether fmt.Errorf uses the %w verb for formatting errors
+    errorf: true
+    # To not allows more than 1 %w verb
+    errorf-multi: false
+    # To check for plain type assertions and type switches
+    asserts: true
+    # To check for plain error comparisons
+    comparison: true
+
+  predeclared:
+    # To not include method names and field names in checks
+    q: false
+
+  tagliatelle:
+    case:
+      # Do not check field names in struct with the json tag
+      use-field-name: false
+      # Choose case for struct tags
+      rules:
+        json: snake
+
+  usestdlibvars:
+    # To use http method string instead of the stdlib vars
+    http-method: false
+
+  govet:
+    # To enable all analyzers
+    enable-all: true
+    # To disable analyzers by name
+    disable:
+      - fieldalignment
+      - shadow
+
+  gofumpt:
+    # To use extra rules on top of gofmt
+    extra-rules: true
+
+  forbidigo:
+    forbid:
+      - "fmt.Print*"
+
+issues:
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  exclude:
+    - "exported: .*"
+    - "package-comments: .*"

README.md

@@ -1,2 +1,195 @@
 # go-struct-enum
-A fully featured Golang struct based enums
+
+![Go Version](https://img.shields.io/github/go-mod/go-version/FabienMht/go-struct-enum.svg)
+[![GoDoc](https://img.shields.io/badge/godoc-reference-blue.svg)](https://pkg.go.dev/github.com/FabienMht/go-struct-enum)
+[![Go Report Card](https://goreportcard.com/badge/github.com/FabienMht/go-struct-enum)](https://goreportcard.com/report/github.com/FabienMht/go-struct-enum)
+[![Sourcegraph](https://sourcegraph.com/github.com/FabienMht/go-struct-enum/-/badge.svg)](https://sourcegraph.com/github.com/FabienMht/go-struct-enum)
+[![Tag](https://img.shields.io/github/tag/FabienMht/go-struct-enum.svg)](https://github.com/FabienMht/go-struct-enum/tags)
+[![Contributors](https://img.shields.io/github/contributors/FabienMht/go-struct-enum)](https://github.com/FabienMht/go-struct-enum/graphs/contributors)
+[![License](https://img.shields.io/github/license/FabienMht/go-struct-enum)](./LICENSE)
+
+A fully featured Golang struct based enums.
+It provides a simple way to declare enums and use them in structs.
+
+**Enums are [harden](https://github.com/nikolaydubina/go-enum-example/tree/master) against:**
+- Arithmetics operations
+- Comparison operators except == and !=
+- Implicit cast of [untyped constants](https://medium.com/golangspec/untyped-constants-in-go-2c69eb519b5b) (use the based type instead of the enum type)
+
+**An enum implements the following interfaces:**
+- `fmt.Stringer`
+- `json.Marshaler`
+- `json.Unmarshaler`
+- `sql.Scanner`
+- `driver.Valuer`
+
+## Install
+
+**Download it:**
+
+```bash
+$ go get github.com/FabienMht/go-struct-enum
+```
+
+**Add the following import:**
+
+```go
+enum "github.com/FabienMht/go-struct-enum"
+```
+
+## Usage
+
+### Basic
+
+Checkout the detailed example in the [documentation](https://pkg.go.dev/github.com/FabienMht/go-struct-enum#pkg-examples) for more information.
+
+**Declare enum values:**
+
+```go
+var (
+	// Define States
+	TestStateUnknown = &TestState{enum.New("")}
+	TestStatePassed  = &TestState{enum.New("passed")}
+	TestStateSkipped = &TestState{enum.New("skipped")}
+	TestStateFailed  = &TestState{enum.New("failed")}
+
+	// Define the ordered list of states
+	TestStates = []enum.Enummer[string]{
+		TestStateUnknown,
+		TestStatePassed,
+		TestStateSkipped,
+		TestStateFailed,
+	}
+
+	// Define states parsers
+	ParseTestState     = enum.Parse(TestStates)
+	MustParseTestState = enum.MustParse(TestStates)
+)
+
+// Define the state enum
+type TestState struct {
+	enum.Enum[string]
+}
+```
+
+**Use enum values:**
+
+```go
+// Parse a state
+state := ParseTestState("passed") // TestStatePassed
+// Or panic if the state is not valid
+state := MustParseTestState("passed") // TestStatePassed
+
+// Get the state value
+state.Value() // "passed"
+// Check the enum value
+state.EqualValue("passed") // true
+```
+
+**Use enum in structs:**
+
+```go
+type Test struct {
+    State *TestState `json:"state"`
+}
+
+// Marshal a struct with an enum
+json.Marshal(&Test{State: TestStatePassed}) // {"state":"passed"}
+
+// Unmarshal a struct with an enum
+var test Test
+json.Unmarshal([]byte(`{"state":"passed"}`), &test) // &Test{State: TestStatePassed}
+```
+
+### Comparison
+
+Checkout the detailed example in the [documentation](https://pkg.go.dev/github.com/FabienMht/go-struct-enum#pkg-examples) for more information.
+
+**Define comparison functions:**
+
+```go
+// Define the state enum
+type TestState struct {
+	enum.Enum[string]
+}
+
+func (ts *TestState) Equal(other *TestState) bool {
+	return enum.Equal(ts, other)
+}
+
+func (ts *TestState) GreaterThan(other *TestState) bool {
+	return enum.GreaterThan(TestStates)(ts, other)
+}
+
+func (ts *TestState) LessThan(other *TestState) bool {
+	return enum.LessThan(TestStates)(ts, other)
+}
+
+func (ts *TestState) GreaterThanOrEqual(other *TestState) bool {
+	return enum.GreaterThanOrEqual(TestStates)(ts, other)
+}
+
+func (ts *TestState) LessThanOrEqual(other *TestState) bool {
+	return enum.LessThanOrEqual(TestStates)(ts, other)
+}
+```
+
+**Use comparison functions:**
+
+```go
+TestStatePassed.Equal(TestStatePassed) // true
+TestStatePassed.Equal(TestStateFailed) // false
+TestStatePassed.GreaterThan(TestStatePassed) // false
+TestStatePassed.GreaterThan(TestStateFailed) // false
+TestStatePassed.GreaterThanOrEqual(TestStatePassed) // true
+TestStatePassed.GreaterThanOrEqual(TestStateFailed) // false
+TestStatePassed.LessThan(TestStatePassed) // false
+TestStatePassed.LessThan(TestStateFailed) // true
+TestStatePassed.LessThanOrEqual(TestStatePassed) // true
+TestStatePassed.LessThanOrEqual(TestStateFailed) // true
+```
+
+## Benchmark
+
+```bash
+$ task bench
+task: [bench] go test -bench=. -benchmem
+goos: linux
+goarch: amd64
+pkg: github.com/FabienMht/go-struct-enum
+cpu: Intel(R) Core(TM) i7-8565U CPU @ 1.80GHz
+BenchmarkParse-8                                15764276                77.69 ns/op           48 B/op          1 allocs/op
+BenchmarkParsePrealloc-8                        383380515                3.034 ns/op           0 B/op          0 allocs/op
+BenchmarkEqual-8                                63047527                16.52 ns/op            0 B/op          0 allocs/op
+BenchmarkGreaterThan-8                           6585123               187.9 ns/op            48 B/op          1 allocs/op
+BenchmarkGreaterThanPrealloc-8                  10859983               108.9 ns/op             0 B/op          0 allocs/op
+BenchmarkGreaterThanOrEqual-8                    6594724               184.5 ns/op            48 B/op          1 allocs/op
+BenchmarkGreaterThanOrEqualPrealloc-8           10677360               107.0 ns/op             0 B/op          0 allocs/op
+BenchmarkLessThan-8                              6341217               183.0 ns/op            48 B/op          1 allocs/op
+BenchmarkLessThanPrealloc-8                     10930384               107.0 ns/op             0 B/op          0 allocs/op
+BenchmarkLessThanOrEqualThan-8                   6474268               182.1 ns/op            48 B/op          1 allocs/op
+BenchmarkLessThanOrEqualThanPrealloc-8          10892846               107.9 ns/op             0 B/op          0 allocs/op
+PASS
+ok      github.com/FabienMht/go-struct-enum     14.543s
+```
+
+## Contributing
+
+Contributions are welcome ! Please open an issue or submit a pull request.
+
+```bash
+# Install task
+$ go install github.com/go-task/task/v3/cmd/task@v3
+
+# Install dev dependencies
+$ task dev
+
+# Run linter
+$ task lint
+
+# Run tests
+$ task test
+
+# Run benchmarks
+$ task bench
+```