This module implements conveniences for dealing with the Option type in Nim. It is based on superfuncs maybe library and Toccatas novel boolean approach but also implements features found elsewhere.

The goal of this library is to make options in Nim easier and safer to work with by creating good patterns for option handling.

Usage

Let's start with the example from the options module:

import options

proc find(haystack: string, needle: char): Option[int] =
  for i, c in haystack:
    if c == needle:
      return some(i)
  return none(int)  # This line is actually optional,
                    # because the default is empty

let found = "abc".find('c')
assert found.isSome and found.get() == 2

This is probably a familiar pattern, we get an option value, check if it is a "some" value, and then extract the actual value. But this is verbose and error prone. What if we refactor the code and drop the isSome check, now we're in a scenario where found.get() will throw an exception if we're not careful. This module offers a couple of alternatives:

withSome found:
  some value: echo value
  none: discard

found?.echo

echo either(found, 0)

The first way, using withSome offers a safe unpacking pattern. You pass it an option, or a list of options, and give it branches to evaluate when either all of the options are some, or any of them is a none. The benefit of this pattern is that the options values are unpacked into variables automatically in the applicable branch. This means that you can't mess up a refactoring and move something from the some branch into the none branch. And as long as care is taken to stay away from options.get and options.unsafeGet this will ensure you can't have exception cases.

The second option is the existential operator, or optional chaining operator. This operator can be put where regular dot-chaining would apply and will only continue execution if the left-hand side is a some. In this example echo will only be called when found is a some, and won't return anything. However this also works when the right hand side might return something, in this case it will be wrapped in an Option[T] that will be a none if the left-hand side is a none.

And last but not least, a simple either template. This takes an option and a default value, but where the regular options.get with an otherwise argument the default value may be a procedure that returns a value. This procedure will only be called if the value is a none, making sure that no side-effects from the procedure will happen unless it's necessary.

This module also includes the convenient optCmp template allowing you to easily compare the values of two options in an option aware manner. So instead of having to wrap your options in one of the patterns above you can alse use optCmp to compare options directly:

let compared = some(5).optCmp(`<`, some(10))

Note however that this does not return a boolean, it returns the first value of the comparisson. So the above code will return a some option with the value 5. This means you can use them to filter values for example. And of course if either part of the comparisson is a none, then the result will be a none as well.

Besides this we also have optAnd and optOr, these don't work on the value of the option, but rather on the has-ity of the option. So optOr will return the first some option, or a none option. And optAnd will return the first none option, or the last option. This can be used to replace boolean expressions.

let x = "green"
# This will print out "5"
echo either(optAnd(optCmp(x, `==`, "green"), 5), 3)
# This will print out "3"
echo either(optAnd(optCmp("blue", `==`, "green"), 5), 3)

In the first example optAnd runs it's first expression, optCmp which returns an option with the value "green", since it has a value optAnd runs the second expression 5 which is automatically converted to some(5). Since both of these have a value optAnd returns the last one some(5), the either procedure is just an alias for get with a default value, since it's first argument has a value it returns that value.

In the second example optAnd runs it's first expression, optCmp which return an option without a value since the comparisson fails. optAnd then returns an option without a value, and the either procedure uses the default value of 3.

This example is the same as a if x == "green": 5 else: 3 but where x might not be set at all.

And last but not least, in case you have a library that doesn't use options there are wrapper procedures that wrap exceptions and error codes in option returns. This is to work well with the logic operations in this module.

let optParseInt = wrapCall: parseInt(x: string): int
echo optParseInt("10") # Prints "some(10)"
echo optParseInt("bob") # Prints "None[int]"
echo either(optParseInt("bob"), 10) # Prints 10, like a default value
withSome optOr(optParseInt("bob"), 10):
  some value:
    echo 10 # Prints 10, like a default value, but in a safe access pattern
  none:
    echo "No value"