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:
//go:generate optional -type=Foo
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
- type Byte
- type Complex64
- type Complex128
- type 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) 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) UnmarshalJSON(data []byte) error
- type Int
- type Int8
- type Int16
- type Int32
- type Int64
- type Rune
- 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) UnmarshalJSON(data []byte) error
- type Uint
- type Uint8
- 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) 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) 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) 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) 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 (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 (Byte) MarshalJSON ¶ added in v0.4.0
func (*Byte) UnmarshalJSON ¶ added in v0.4.0
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 (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 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 (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.
type Error ¶
type Error struct {
// contains filtered or unexported fields
}
Error is an optional error.
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 (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) 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 (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) UnmarshalJSON ¶ added in v0.4.0
type Int ¶
type Int struct {
// contains filtered or unexported fields
}
Int is an optional int.
func (Int) MarshalJSON ¶ added in v0.4.0
func (*Int) UnmarshalJSON ¶ added in v0.4.0
type Int8 ¶
type Int8 struct {
// contains filtered or unexported fields
}
Int8 is an optional int8.
func (Int8) MarshalJSON ¶ added in v0.4.0
func (*Int8) UnmarshalJSON ¶ added in v0.4.0
type Int16 ¶
type Int16 struct {
// contains filtered or unexported fields
}
Int16 is an optional int16.
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 (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 (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 Rune ¶
type Rune struct {
// contains filtered or unexported fields
}
Rune is an optional rune.
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 (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 (Uint) MarshalJSON ¶ added in v0.4.0
func (*Uint) UnmarshalJSON ¶ added in v0.4.0
type Uint8 ¶
type Uint8 struct {
// contains filtered or unexported fields
}
Uint8 is an optional uint8.
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 Uint16 ¶
type Uint16 struct {
// contains filtered or unexported fields
}
Uint16 is an optional uint16.
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 (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 (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 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 (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) UnmarshalJSON ¶ added in v0.4.0
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
optional
command
Optional is a tool that generates 'optional' type wrappers around a given type T. Typically this process would be run using go generate, like this: //go:generate optional -type=Foo running this command optional -type=Foo in the same directory will create the file optional_foo.go containing a definition of type OptionalFoo struct { ...
|
Optional is a tool that generates 'optional' type wrappers around a given type T. Typically this process would be run using go generate, like this: //go:generate optional -type=Foo running this command optional -type=Foo in the same directory will create the file optional_foo.go containing a definition of type OptionalFoo struct { ... |