Re-wrote documentation for options and optionutils

Author: PMunch

lib/pure/options.nim

@@ -39,17 +39,6 @@
 ##     return none(int)  # This line is actually optional,
 ##                       # because the default is empty
 ##
-## .. code-block:: nim
-##   require "abc".find('c'):
-##     some x: assert(x == 2)
-##     none: assert false # This will not be reached, because the string
-##                        # contains 'c'
-##
-## This pattern assures that you only access the value of on option in a safe
-## way. If you want to use a more familiar exception pattern you can use:
-##
-## .. code-block:: nim
-##
 ##   try:
 ##     assert("abc".find('c').get() == 2)  # Immediately extract the value
 ##   except UnpackError:  # If there is no value
@@ -59,58 +48,11 @@
 ## raises ``UnpackError`` if there is no value. There is another option for
 ## obtaining the value: ``unsafeGet``, but you must only use it when you are
 ## absolutely sure the value is present (e.g. after checking ``isSome``). If
-## you do not care about the tiny overhead that ``get`` and ``require`` causes,
-## you should simply never use ``unsafeGet``.
-##
-## By far the safest and simplest way to use an option value is the ``require``
-## procedure. It can take either a single statement as seen above, or multiple.
-## Note that in the same way as the other operators work ``require`` will not
-## evaluate all statements if an earlier one doesn't return a value:
-##
-## .. code-block:: nim
-##   let msg = require([some(-100), some(200)]):
-##     some [x, _]: "First value is " & $x
-##     none: "No value"
-##   echo msg # This will echo "First value is -100"
-##
-## As seen above you can ignore the value of the option with an underscore as
-## the identifier. But if you want to assign it to a locally available symbol
-## simply add it in the same position in the list. The underscore can be used to
-## ignore one value, the entire list of values, or only some of the values.
-##
-## This module also implements common mapping functionality to use a procedure
-## on an optional value, carrying over the absence state if there is no value:
-##
-## .. code-block:: nim
-##
-##   let
-##     x = some(10)
-##     y = none(int)
-##   assert(map(x, proc(x: int): int = x + 10) == some(20))
-##   assert(map(y, proc(x: int): int = x + 10).isNone)
-##
-## Options can also be used for conditional chaining. Let's use the ``find``
-## procedure we defined above:
-##
-## .. code-block:: nim
-##   var position = "hello world".find('w')
-##   echo position # echoes out Some(6) is expected
-##   position = "hello world".find('w').?min(4)
-##   echo position # echoes out Some(4), we take the minimum of 6 and 4
-##   position = "hello world".find('q').?min(4)
-##   echo position # echoes out None[int], min is never run since find returns
-##   # a none option.
-##   position = "hello world".find('w').?min(4).max(0)
-##   echo position # echoes out Some(4) both min and max are run
-##   position = "hello world".find('q').?min(4).max(0)
-##   echo position # echoes out None[int], min and max is never run
-##
-## Since options use their has-ity as their boolean value this chaining can
-## also be used in if statements:
-##
-## .. code-block:: nim
-##   if ("hello world".find('w').?min(4)).isSome:
-##     echo "Never run"
+## you do not care about the tiny overhead that ``get`` causes,
+## you should simply never use ``unsafeGet``. Also have a look at ``optionutils``
+## for more ways of safely interacting with optional values. Prior to 0.19.0 many
+## of the features found in that module was part of this module. This module now
+## only contains the basic concept of options.
 import typetraits
 
 type

lib/pure/optionutils.nim

@@ -1,3 +1,95 @@
+#
+#
+#            Nim's Runtime Library
+#        (c) Copyright 2015 Nim Contributors
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+## Abstract
+## ========
+##
+## This module expands the usability of options with several practical patters
+## and procedures. The goal is to make it safer and more ergonomic to use options
+## and to handle optional values.
+##
+## Tutorial
+## ========
+##
+## Let's start with the same example as in the options module: a procedure that
+## finds the index of a character in a string.
+##
+## .. code-block:: nim
+##
+##   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
+##
+##   allSome "abc".find('c'):
+##     some x: assert(x == 2)
+##     none: assert false # This will not be reached, because the string
+##                        # contains 'c'
+##
+## This pattern assures that you only access the value of on option in a safe
+## way. This is by far the safest and simplest way to use an option value. It
+## can take either a single statement as seen above, or multiple. Note that
+## ``allSome`` will not evaluate all statements if an earlier one doesn't return
+## a value:
+##
+## .. code-block:: nim
+##   let msg = allSome([none(int), some(200)]):
+##     some [x, _]: "First value is " & $x
+##     none: "No value"
+##   echo msg # This will echo "No value"
+##
+## In this block the call to ``some(200)`` is never executed, so it's safe to
+## put a list of expensive operations in a block like this.
+##
+## As seen above you can also ignore the value of an option by using an
+## underscore as the identifier. But if you want to assign it to a locally
+## available symbol simply add it in the same position in the list. The
+## underscore can be used to ignore one value, the entire list of values, or
+## only some of the values.
+##
+## This module also implements common mapping functionality to use a procedure
+## on an optional value, carrying over the absence state if there is no value:
+##
+## .. code-block:: nim
+##
+##   let
+##     x = some(10)
+##     y = none(int)
+##   assert(map(x, proc(x: int): int = x + 10) == some(20))
+##   assert(map(y, proc(x: int): int = x + 10).isNone)
+##
+## Options can also be used for conditional chaining with the `.?` operator.
+## Let's use the ``find`` procedure we defined above:
+##
+## .. code-block:: nim
+##   var position = "hello world".find('w')
+##   echo position # echoes out Some(6) as expected
+##   position = "hello world".find('w').?min(4)
+##   echo position # echoes out Some(4), we take the minimum of 6 and 4
+##   position = "hello world".find('q').?min(4)
+##   echo position # echoes out None[int], min is never run since find returns
+##   # a none option.
+##   position = "hello world".find('w').?min(4).max(0)
+##   echo position # echoes out Some(4) both min and max are run
+##   position = "hello world".find('q').?min(4).max(0)
+##   echo position # echoes out None[int], min and max is never run
+##
+## Since options use their has-ity as their boolean value this chaining can
+## also be used in if statements:
+##
+## .. code-block:: nim
+##   if ("hello world".find('w').?min(4)).isSome:
+##     echo "Never run"
 import options
 import macros