bynil / optional

Optional is a library of optional Go types

Optional

Optional is a library that provides option types for the primitive Go types.

It can also be used as a tool to generate option type wrappers around your own types.

Motivation

In Go, variables declared without an explicit initial value are given their zero value. Most of the time this is what you want, but sometimes you want to be able to tell if a variable was set or if it's just a zero value. That's where option types come in handy.

Inspiration

• Java Optional
• https://github.com/leighmcculloch/go-optional
• golang/go#7054

Tool

Install

go get -u github.com/markphelps/optional/cmd/optional

Usage

Typically this process would be run using go generate, like this:

import _ "github.com/markphelps/optional

//go:generate optional -type=Foo
type Foo struct {
  ...
}

🗒️ Note: the blank import is necessary to prevent go mod tidy from removing this library as a dependency if you are only using it to generate your own types.

running this command:

optional -type=Foo

in the same directory will create the file optional_foo.go containing a definition of:

type OptionalFoo struct {
  ...
}

The default type is OptionalT or optionalT (depending on if the type is exported) and output file is optional_t.go. This can be overridden with the -output flag.

Library

• bool
• byte
• complex128
• complex64
• float32
• float64
• int
• int16
• int32
• int64
• int8
• rune
• string
• uint
• uint16
• uint32
• uint64
• uint8
• uintptr
• error

Usage

package main

import (
    "fmt"

    "github.com/markphelps/optional"
)

func main() {
    s := optional.NewString("foo")

    value, err := s.Get()
    if err != nil {
        // handle error!
    } else {
        fmt.Println(value)
    }

    t := optional.String{}
    fmt.Println(t.OrElse("bar"))
}

See example_test.go and the documentation for more usage.

Marshalling/Unmarshalling JSON

Note: v0.6.0 introduces a potential breaking change to anyone depending on marshalling non-present values to their zero values instead of null. See: #9 for more context.

Note: v0.8.0 removes JSON support from complex64 and complex128 types per #13

Option types marshal to/from JSON as you would expect:

Marshalling

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    var value = struct {
        Field optional.String `json:"field,omitempty"`
    }{
        Field: optional.NewString("bar"),
    }

    out, _ := json.Marshal(value)

    fmt.Println(string(out))
    // outputs: {"field":"bar"}
}

Unmarshalling

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    var value = &struct {
        Field optional.String `json:"field,omitempty"`
    }{}

    _ = json.Unmarshal([]byte(`{"field":"bar"}`), value)

    value.Field.If(func(s string) {
        fmt.Println(s)
    })
    // outputs: bar
}

See example_test.go for more examples.

Test Coverage

As you can see test coverage is a bit lacking for the library. This is simply because testing generated code is not super easy. I'm currently working on improving test coverage for the generated types, but in the meantime checkout string_test.go and int_test.go for examples.

Also checkout:

• example_test.go for example usage.
• cmd/optional/golden_test.go for golden file based testing of the generator itself.

Golden Files

If changing the API you may need to update the golden files for your tests to pass by running:

go test ./cmd/optional/... -update.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'feat: Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Conventional Commits

Optional uses Conventional Commits for commit messages. This allows us to automatically generate changelogs and releases.

To help with this, we use pre-commit to automatically lint commit messages. To install pre-commit, run:

pip install pre-commit or brew install pre-commit (if you're on a Mac)

Then run pre-commit install to install the git hook.