Option

Represents an optional value in Lua. This is useful to avoid nil bugs, which can go silently undetected within code and cause hidden or hard-to-find bugs.

Properties

None

</>

Option.None: Option<None>

Represents no value.

Functions

Some

</>

Option.Some(value: T) → Option<T>

Creates an Option instance with the given value. Throws an error if the given value is nil.

Wrap

</>

Option.Wrap(value: T) → Option<T> | Option<None>

Safely wraps the given value as an option. If the value is nil, returns Option.None, otherwise returns Option.Some(value).

Is

</>

Option.Is(obj: any) → boolean

Returns true if obj is an Option.

Assert

</>

Option.Assert(obj: any) → ()

Throws an error if obj is not an Option.

Deserialize

</>

Option.Deserialize(data: table) → Option

Deserializes the data into an Option. This data should have come from the option:Serialize() method.

Serialize

</>

Option:Serialize() → table

Returns a serialized version of the option.

Match

</>

Option:Match(matches: {

Some: (value: any) → any,

None: () → any

}) → any

Matches against the option.

local opt = Option.Some(32)
opt:Match {
	Some = function(num) print("Number", num) end,
	None = function() print("No value") end,
}

IsSome

</>

Option:IsSome() → boolean

Returns true if the option has a value.

IsNone

</>

Option:IsNone() → boolean

Returns true if the option is None.

Expect

</>

Option:Expect(msg: string) → value: any

Unwraps the value in the option, otherwise throws an error with msg as the error message.

local opt = Option.Some(10)
print(opt:Expect("No number")) -> 10
print(Option.None:Expect("No number")) -- Throws an error "No number"

ExpectNone

</>

Option:ExpectNone(msg: string) → ()

Throws an error with msg as the error message if the value is not None.

Unwrap

</>

Option:Unwrap() → value: any

Returns the value in the option, or throws an error if the option is None.

UnwrapOr

</>

Option:UnwrapOr(default: any) → value: any

If the option holds a value, returns the value. Otherwise, returns default.

UnwrapOrElse

</>

Option:UnwrapOrElse(defaultFn: () → any) → value: any

If the option holds a value, returns the value. Otherwise, returns the result of the defaultFn function.

And

</>

Option:And(optionB: Option) → Option

Returns optionB if the calling option has a value, otherwise returns None.

local optionA = Option.Some(32)
local optionB = Option.Some(64)
local opt = optionA:And(optionB)
-- opt == optionB

local optionA = Option.None
local optionB = Option.Some(64)
local opt = optionA:And(optionB)
-- opt == Option.None

AndThen

</>

Option:AndThen(andThenFn: (value: any) → Option) → value: Option

If the option holds a value, then the andThenFn function is called with the held value of the option, and then the resultant Option returned by the andThenFn is returned. Otherwise, None is returned.

local optA = Option.Some(32)
local optB = optA:AndThen(function(num)
	return Option.Some(num * 2)
end)
print(optB:Expect("Expected number")) --> 64

Or

</>

Option:Or(optionB: Option) → Option

If caller has a value, returns itself. Otherwise, returns optionB.

OrElse

</>

Option:OrElse(orElseFn: () → Option) → Option

If caller has a value, returns itself. Otherwise, returns the option generated by the orElseFn function.

XOr

</>

Option:XOr(optionB: Option) → Option

If both self and optionB have values or both don't have a value, then this returns None. Otherwise, it returns the option that does have a value.

Filter

</>

Option:Filter(predicate: (value: any) → boolean) → Option

Returns self if this option has a value and the predicate returns `true. Otherwise, returns None.

Contains

</>

Option:Contains(value: any) → boolean

Returns true if this option contains value.

__tostring

</>

Option:__tostring() → string

Metamethod to transform the option into a string.

local optA = Option.Some(64)
local optB = Option.None
print(optA) --> Option<number>
print(optB) --> Option<None>

__eq

</>

Option:__eq(opt: Option) → boolean

Metamethod to check equality between two options. Returns true if both options hold the same value or both options are None.

local o1 = Option.Some(32)
local o2 = Option.Some(32)
local o3 = Option.Some(64)
local o4 = Option.None
local o5 = Option.None

print(o1 == o2) --> true
print(o1 == o3) --> false
print(o1 == o4) --> false
print(o4 == o5) --> true