README
¶
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
- https://github.com/golang/go/issues/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
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Documentation
¶
Overview ¶
Example (Get) ¶
package main
import (
"fmt"
"github.com/markphelps/optional"
)
func main() {
values := []optional.String{
optional.NewString("foo"),
optional.NewString(""),
optional.NewString("bar"),
{},
}
for _, v := range values {
value, err := v.Get()
if err != nil {
fmt.Println(err.Error())
} else {
fmt.Println(value)
}
}
}
Output: foo bar value not present
Example (If) ¶
package main
import (
"fmt"
"github.com/markphelps/optional"
)
func main() {
values := []optional.String{
optional.NewString("foo"),
optional.NewString(""),
optional.NewString("bar"),
{},
}
for _, v := range values {
v.If(func(s string) {
fmt.Println("present")
})
}
}
Output: present present present
Example (MarshalJSON) ¶
package main
import (
"encoding/json"
"fmt"
"github.com/markphelps/optional"
)
func main() {
type example struct {
Field *optional.String `json:"field,omitempty"`
FieldTwo *optional.String `json:"field_two"`
}
var values = []optional.String{
optional.NewString("foo"),
optional.NewString(""),
optional.NewString("bar"),
}
for _, v := range values {
out, _ := json.Marshal(&example{
Field: &v,
FieldTwo: &v,
})
fmt.Println(string(out))
}
out, _ := json.Marshal(&example{})
fmt.Println(string(out))
}
Output: {"field":"foo","field_two":"foo"} {"field":"","field_two":""} {"field":"bar","field_two":"bar"} {"field_two":null}
Example (MustGet) ¶
package main
import (
"fmt"
"github.com/markphelps/optional"
)
func main() {
values := []optional.String{
optional.NewString("foo"),
optional.NewString(""),
optional.NewString("bar"),
{},
}
for _, v := range values {
if v.Present() {
value := v.MustGet()
fmt.Println(value)
} else {
fmt.Println("not present")
}
}
}
Output: foo bar not present
Example (OrElse) ¶
package main
import (
"fmt"
"github.com/markphelps/optional"
)
func main() {
values := []optional.String{
optional.NewString("foo"),
optional.NewString(""),
optional.NewString("bar"),
{},
}
for _, v := range values {
fmt.Println(v.OrElse("not present"))
}
}
Output: foo bar not present
Example (Set) ¶
package main
import (
"fmt"
"github.com/markphelps/optional"
)
func main() {
var (
values = []string{
"foo",
"",
"bar",
}
s = optional.NewString("baz")
)
for _, v := range values {
s.Set(v)
value, err := s.Get()
if err != nil {
fmt.Println(err.Error())
} else {
fmt.Println(value)
}
}
}
Output: foo bar
Example (UnmarshalJSON) ¶
package main
import (
"encoding/json"
"fmt"
"github.com/markphelps/optional"
)
func main() {
var values = []string{
`{"field":"foo","field_two":"foo"}`,
`{"field":"","field_two":""}`,
`{"field":"null","field_two":"null"}`,
`{"field":"bar","field_two":"bar"}`,
"{}",
}
for _, v := range values {
var o = &struct {
Field optional.String `json:"field,omitempty"`
FieldTwo optional.String `json:"field_two"`
}{}
if err := json.Unmarshal([]byte(v), o); err != nil {
fmt.Println(err)
}
o.Field.If(func(s string) {
fmt.Println(s)
})
o.FieldTwo.If(func(s string) {
fmt.Println(s)
})
}
Output:
Index ¶
- type Bool
- func (b Bool) Get() (bool, error)
- func (b Bool) If(fn func(bool))
- func (b Bool) MarshalJSON() ([]byte, error)
- func (b Bool) MustGet() bool
- func (b Bool) OrElse(v bool) bool
- func (b Bool) Present() bool
- func (b *Bool) Set(v bool)
- func (b Bool) ToPtr() *bool
- func (b *Bool) UnmarshalJSON(data []byte) error
- type Byte
- func (b Byte) Get() (byte, error)
- func (b Byte) If(fn func(byte))
- func (b Byte) MarshalJSON() ([]byte, error)
- func (b Byte) MustGet() byte
- func (b Byte) OrElse(v byte) byte
- func (b Byte) Present() bool
- func (b *Byte) Set(v byte)
- func (b Byte) ToPtr() *byte
- func (b *Byte) UnmarshalJSON(data []byte) error
- type Complex128
- type Complex64
- type Error
- func (e Error) Get() (error, error)
- func (e Error) If(fn func(error))
- func (e Error) MarshalJSON() ([]byte, error)
- func (e Error) MustGet() error
- func (e Error) OrElse(v error) error
- func (e Error) Present() bool
- func (e *Error) Set(v error)
- func (e Error) ToPtr() *error
- func (e *Error) UnmarshalJSON(data []byte) error
- type Float32
- func (f Float32) Get() (float32, error)
- func (f Float32) If(fn func(float32))
- func (f Float32) MarshalJSON() ([]byte, error)
- func (f Float32) MustGet() float32
- func (f Float32) OrElse(v float32) float32
- func (f Float32) Present() bool
- func (f *Float32) Set(v float32)
- func (f Float32) ToPtr() *float32
- func (f *Float32) UnmarshalJSON(data []byte) error
- type Float64
- func (f Float64) Get() (float64, error)
- func (f Float64) If(fn func(float64))
- func (f Float64) MarshalJSON() ([]byte, error)
- func (f Float64) MustGet() float64
- func (f Float64) OrElse(v float64) float64
- func (f Float64) Present() bool
- func (f *Float64) Set(v float64)
- func (f Float64) ToPtr() *float64
- func (f *Float64) UnmarshalJSON(data []byte) error
- type Int
- type Int16
- func (i Int16) Get() (int16, error)
- func (i Int16) If(fn func(int16))
- func (i Int16) MarshalJSON() ([]byte, error)
- func (i Int16) MustGet() int16
- func (i Int16) OrElse(v int16) int16
- func (i Int16) Present() bool
- func (i *Int16) Set(v int16)
- func (i Int16) ToPtr() *int16
- func (i *Int16) UnmarshalJSON(data []byte) error
- type Int32
- func (i Int32) Get() (int32, error)
- func (i Int32) If(fn func(int32))
- func (i Int32) MarshalJSON() ([]byte, error)
- func (i Int32) MustGet() int32
- func (i Int32) OrElse(v int32) int32
- func (i Int32) Present() bool
- func (i *Int32) Set(v int32)
- func (i Int32) ToPtr() *int32
- func (i *Int32) UnmarshalJSON(data []byte) error
- type Int64
- func (i Int64) Get() (int64, error)
- func (i Int64) If(fn func(int64))
- func (i Int64) MarshalJSON() ([]byte, error)
- func (i Int64) MustGet() int64
- func (i Int64) OrElse(v int64) int64
- func (i Int64) Present() bool
- func (i *Int64) Set(v int64)
- func (i Int64) ToPtr() *int64
- func (i *Int64) UnmarshalJSON(data []byte) error
- type Int8
- func (i Int8) Get() (int8, error)
- func (i Int8) If(fn func(int8))
- func (i Int8) MarshalJSON() ([]byte, error)
- func (i Int8) MustGet() int8
- func (i Int8) OrElse(v int8) int8
- func (i Int8) Present() bool
- func (i *Int8) Set(v int8)
- func (i Int8) ToPtr() *int8
- func (i *Int8) UnmarshalJSON(data []byte) error
- type Rune
- func (r Rune) Get() (rune, error)
- func (r Rune) If(fn func(rune))
- func (r Rune) MarshalJSON() ([]byte, error)
- func (r Rune) MustGet() rune
- func (r Rune) OrElse(v rune) rune
- func (r Rune) Present() bool
- func (r *Rune) Set(v rune)
- func (r Rune) ToPtr() *rune
- func (r *Rune) UnmarshalJSON(data []byte) error
- type String
- func (s String) Get() (string, error)
- func (s String) If(fn func(string))
- func (s String) MarshalJSON() ([]byte, error)
- func (s String) MustGet() string
- func (s String) OrElse(v string) string
- func (s String) Present() bool
- func (s *String) Set(v string)
- func (s String) ToPtr() *string
- func (s *String) UnmarshalJSON(data []byte) error
- type Uint
- func (u Uint) Get() (uint, error)
- func (u Uint) If(fn func(uint))
- func (u Uint) MarshalJSON() ([]byte, error)
- func (u Uint) MustGet() uint
- func (u Uint) OrElse(v uint) uint
- func (u Uint) Present() bool
- func (u *Uint) Set(v uint)
- func (u Uint) ToPtr() *uint
- func (u *Uint) UnmarshalJSON(data []byte) error
- type Uint16
- func (u Uint16) Get() (uint16, error)
- func (u Uint16) If(fn func(uint16))
- func (u Uint16) MarshalJSON() ([]byte, error)
- func (u Uint16) MustGet() uint16
- func (u Uint16) OrElse(v uint16) uint16
- func (u Uint16) Present() bool
- func (u *Uint16) Set(v uint16)
- func (u Uint16) ToPtr() *uint16
- func (u *Uint16) UnmarshalJSON(data []byte) error
- type Uint32
- func (u Uint32) Get() (uint32, error)
- func (u Uint32) If(fn func(uint32))
- func (u Uint32) MarshalJSON() ([]byte, error)
- func (u Uint32) MustGet() uint32
- func (u Uint32) OrElse(v uint32) uint32
- func (u Uint32) Present() bool
- func (u *Uint32) Set(v uint32)
- func (u Uint32) ToPtr() *uint32
- func (u *Uint32) UnmarshalJSON(data []byte) error
- type Uint64
- func (u Uint64) Get() (uint64, error)
- func (u Uint64) If(fn func(uint64))
- func (u Uint64) MarshalJSON() ([]byte, error)
- func (u Uint64) MustGet() uint64
- func (u Uint64) OrElse(v uint64) uint64
- func (u Uint64) Present() bool
- func (u *Uint64) Set(v uint64)
- func (u Uint64) ToPtr() *uint64
- func (u *Uint64) UnmarshalJSON(data []byte) error
- type Uint8
- func (u Uint8) Get() (uint8, error)
- func (u Uint8) If(fn func(uint8))
- func (u Uint8) MarshalJSON() ([]byte, error)
- func (u Uint8) MustGet() uint8
- func (u Uint8) OrElse(v uint8) uint8
- func (u Uint8) Present() bool
- func (u *Uint8) Set(v uint8)
- func (u Uint8) ToPtr() *uint8
- func (u *Uint8) UnmarshalJSON(data []byte) error
- type Uintptr
- func (u Uintptr) Get() (uintptr, error)
- func (u Uintptr) If(fn func(uintptr))
- func (u Uintptr) MarshalJSON() ([]byte, error)
- func (u Uintptr) MustGet() uintptr
- func (u Uintptr) OrElse(v uintptr) uintptr
- func (u Uintptr) Present() bool
- func (u *Uintptr) Set(v uintptr)
- func (u Uintptr) ToPtr() *uintptr
- func (u *Uintptr) UnmarshalJSON(data []byte) error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Bool ¶
type Bool struct {
// contains filtered or unexported fields
}
Bool is an optional bool.
func NewBoolFromPtr ¶ added in v0.11.0
NewBoolFromPtr creates an optional.Bool from a bool pointer.
func (Bool) MarshalJSON ¶ added in v0.4.0
func (*Bool) UnmarshalJSON ¶ added in v0.4.0
type Byte ¶
type Byte struct {
// contains filtered or unexported fields
}
Byte is an optional byte.
func NewByteFromPtr ¶ added in v0.11.0
NewByteFromPtr creates an optional.Byte from a byte pointer.
func (Byte) MarshalJSON ¶ added in v0.4.0
func (*Byte) UnmarshalJSON ¶ added in v0.4.0
type Complex128 ¶
type Complex128 struct {
// contains filtered or unexported fields
}
Complex128 is an optional complex128.
func NewComplex128 ¶ added in v0.3.0
func NewComplex128(v complex128) Complex128
NewComplex128 creates an optional.Complex128 from a complex128.
func NewComplex128FromPtr ¶ added in v0.11.0
func NewComplex128FromPtr(v *complex128) Complex128
NewComplex128FromPtr creates an optional.Complex128 from a complex128 pointer.
func (Complex128) Get ¶
func (c Complex128) Get() (complex128, error)
Get returns the complex128 value or an error if not present.
func (Complex128) If ¶ added in v0.2.0
func (c Complex128) If(fn func(complex128))
If calls the function f with the value if the value is present.
func (Complex128) MustGet ¶ added in v0.10.0
func (c Complex128) MustGet() complex128
MustGet returns the complex128 value or panics if not present.
func (Complex128) OrElse ¶
func (c Complex128) OrElse(v complex128) complex128
OrElse returns the complex128 value or a default value if the value is not present.
func (Complex128) Present ¶
func (c Complex128) Present() bool
Present returns whether or not the value is present.
func (Complex128) ToPtr ¶ added in v0.11.0
func (c Complex128) ToPtr() *complex128
ToPtr returns a *complex128 of the value or nil if not present.
type Complex64 ¶
type Complex64 struct {
// contains filtered or unexported fields
}
Complex64 is an optional complex64.
func NewComplex64 ¶ added in v0.3.0
NewComplex64 creates an optional.Complex64 from a complex64.
func NewComplex64FromPtr ¶ added in v0.11.0
NewComplex64FromPtr creates an optional.Complex64 from a complex64 pointer.
func (Complex64) If ¶ added in v0.2.0
If calls the function f with the value if the value is present.
func (Complex64) MustGet ¶ added in v0.10.0
MustGet returns the complex64 value or panics if not present.
func (Complex64) OrElse ¶
OrElse returns the complex64 value or a default value if the value is not present.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is an optional error.
func NewErrorFromPtr ¶ added in v0.11.0
NewErrorFromPtr creates an optional.Error from a error pointer.
func (Error) MarshalJSON ¶ added in v0.4.0
func (Error) OrElse ¶
OrElse returns the error value or a default value if the value is not present.
func (*Error) UnmarshalJSON ¶ added in v0.4.0
type Float32 ¶
type Float32 struct {
// contains filtered or unexported fields
}
Float32 is an optional float32.
func NewFloat32 ¶ added in v0.3.0
NewFloat32 creates an optional.Float32 from a float32.
func NewFloat32FromPtr ¶ added in v0.11.0
NewFloat32FromPtr creates an optional.Float32 from a float32 pointer.
func (Float32) MarshalJSON ¶ added in v0.4.0
func (Float32) MustGet ¶ added in v0.10.0
MustGet returns the float32 value or panics if not present.
func (Float32) OrElse ¶
OrElse returns the float32 value or a default value if the value is not present.
func (Float32) ToPtr ¶ added in v0.11.0
ToPtr returns a *float32 of the value or nil if not present.
func (*Float32) UnmarshalJSON ¶ added in v0.4.0
type Float64 ¶
type Float64 struct {
// contains filtered or unexported fields
}
Float64 is an optional float64.
func NewFloat64 ¶ added in v0.3.0
NewFloat64 creates an optional.Float64 from a float64.
func NewFloat64FromPtr ¶ added in v0.11.0
NewFloat64FromPtr creates an optional.Float64 from a float64 pointer.
func (Float64) MarshalJSON ¶ added in v0.4.0
func (Float64) MustGet ¶ added in v0.10.0
MustGet returns the float64 value or panics if not present.
func (Float64) OrElse ¶
OrElse returns the float64 value or a default value if the value is not present.
func (Float64) ToPtr ¶ added in v0.11.0
ToPtr returns a *float64 of the value or nil if not present.
func (*Float64) UnmarshalJSON ¶ added in v0.4.0
type Int ¶
type Int struct {
// contains filtered or unexported fields
}
Int is an optional int.
func NewIntFromPtr ¶ added in v0.11.0
NewIntFromPtr creates an optional.Int from a int pointer.
func (Int) MarshalJSON ¶ added in v0.4.0
func (*Int) UnmarshalJSON ¶ added in v0.4.0
type Int16 ¶
type Int16 struct {
// contains filtered or unexported fields
}
Int16 is an optional int16.
func NewInt16FromPtr ¶ added in v0.11.0
NewInt16FromPtr creates an optional.Int16 from a int16 pointer.
func (Int16) MarshalJSON ¶ added in v0.4.0
func (Int16) OrElse ¶
OrElse returns the int16 value or a default value if the value is not present.
func (*Int16) UnmarshalJSON ¶ added in v0.4.0
type Int32 ¶
type Int32 struct {
// contains filtered or unexported fields
}
Int32 is an optional int32.
func NewInt32FromPtr ¶ added in v0.11.0
NewInt32FromPtr creates an optional.Int32 from a int32 pointer.
func (Int32) MarshalJSON ¶ added in v0.4.0
func (Int32) OrElse ¶
OrElse returns the int32 value or a default value if the value is not present.
func (*Int32) UnmarshalJSON ¶ added in v0.4.0
type Int64 ¶
type Int64 struct {
// contains filtered or unexported fields
}
Int64 is an optional int64.
func NewInt64FromPtr ¶ added in v0.11.0
NewInt64FromPtr creates an optional.Int64 from a int64 pointer.
func (Int64) MarshalJSON ¶ added in v0.4.0
func (Int64) OrElse ¶
OrElse returns the int64 value or a default value if the value is not present.
func (*Int64) UnmarshalJSON ¶ added in v0.4.0
type Int8 ¶
type Int8 struct {
// contains filtered or unexported fields
}
Int8 is an optional int8.
func NewInt8FromPtr ¶ added in v0.11.0
NewInt8FromPtr creates an optional.Int8 from a int8 pointer.
func (Int8) MarshalJSON ¶ added in v0.4.0
func (*Int8) UnmarshalJSON ¶ added in v0.4.0
type Rune ¶
type Rune struct {
// contains filtered or unexported fields
}
Rune is an optional rune.
func NewRuneFromPtr ¶ added in v0.11.0
NewRuneFromPtr creates an optional.Rune from a rune pointer.
func (Rune) MarshalJSON ¶ added in v0.4.0
func (*Rune) UnmarshalJSON ¶ added in v0.4.0
type String ¶
type String struct {
// contains filtered or unexported fields
}
String is an optional string.
func NewStringFromPtr ¶ added in v0.11.0
NewStringFromPtr creates an optional.String from a string pointer.
func (String) MarshalJSON ¶ added in v0.4.0
func (String) OrElse ¶
OrElse returns the string value or a default value if the value is not present.
func (*String) UnmarshalJSON ¶ added in v0.4.0
type Uint ¶
type Uint struct {
// contains filtered or unexported fields
}
Uint is an optional uint.
func NewUintFromPtr ¶ added in v0.11.0
NewUintFromPtr creates an optional.Uint from a uint pointer.
func (Uint) MarshalJSON ¶ added in v0.4.0
func (*Uint) UnmarshalJSON ¶ added in v0.4.0
type Uint16 ¶
type Uint16 struct {
// contains filtered or unexported fields
}
Uint16 is an optional uint16.
func NewUint16FromPtr ¶ added in v0.11.0
NewUint16FromPtr creates an optional.Uint16 from a uint16 pointer.
func (Uint16) MarshalJSON ¶ added in v0.4.0
func (Uint16) OrElse ¶
OrElse returns the uint16 value or a default value if the value is not present.
func (*Uint16) UnmarshalJSON ¶ added in v0.4.0
type Uint32 ¶
type Uint32 struct {
// contains filtered or unexported fields
}
Uint32 is an optional uint32.
func NewUint32FromPtr ¶ added in v0.11.0
NewUint32FromPtr creates an optional.Uint32 from a uint32 pointer.
func (Uint32) MarshalJSON ¶ added in v0.4.0
func (Uint32) OrElse ¶
OrElse returns the uint32 value or a default value if the value is not present.
func (*Uint32) UnmarshalJSON ¶ added in v0.4.0
type Uint64 ¶
type Uint64 struct {
// contains filtered or unexported fields
}
Uint64 is an optional uint64.
func NewUint64FromPtr ¶ added in v0.11.0
NewUint64FromPtr creates an optional.Uint64 from a uint64 pointer.
func (Uint64) MarshalJSON ¶ added in v0.4.0
func (Uint64) OrElse ¶
OrElse returns the uint64 value or a default value if the value is not present.
func (*Uint64) UnmarshalJSON ¶ added in v0.4.0
type Uint8 ¶
type Uint8 struct {
// contains filtered or unexported fields
}
Uint8 is an optional uint8.
func NewUint8FromPtr ¶ added in v0.11.0
NewUint8FromPtr creates an optional.Uint8 from a uint8 pointer.
func (Uint8) MarshalJSON ¶ added in v0.4.0
func (Uint8) OrElse ¶
OrElse returns the uint8 value or a default value if the value is not present.
func (*Uint8) UnmarshalJSON ¶ added in v0.4.0
type Uintptr ¶
type Uintptr struct {
// contains filtered or unexported fields
}
Uintptr is an optional uintptr.
func NewUintptr ¶ added in v0.3.0
NewUintptr creates an optional.Uintptr from a uintptr.
func NewUintptrFromPtr ¶ added in v0.11.0
NewUintptrFromPtr creates an optional.Uintptr from a uintptr pointer.
func (Uintptr) MarshalJSON ¶ added in v0.4.0
func (Uintptr) MustGet ¶ added in v0.10.0
MustGet returns the uintptr value or panics if not present.
func (Uintptr) OrElse ¶
OrElse returns the uintptr value or a default value if the value is not present.
func (Uintptr) ToPtr ¶ added in v0.11.0
ToPtr returns a *uintptr of the value or nil if not present.
Source Files
Directories