Switch to ~null~ and ~void~ (vs <opt> and <void>)

A long time ago when there was only one state you could put in values
that could not be in blocks, it was called VOID.  It didn't have a
datatype, so some alternative signal was needed in the type spec
blocks.  The idea of using a TAG! and saying `<opt>` was chosen
as a temporary solution.

That temporary solution wound up lasting for many years, as the lack
of a satisfactory answer persisted.  The type changed from being VOID
to being NULL, and then something called VOID came along with a similar
problem.  So `<void>` was used for that.

As the needs to be more expressive about the properties of parameters
grew, tags began to control other features...making it a bit saturated
to also be using tags for void and null indications.  The modern idea
is to use quasiforms to represent their antiforms, and it seemed like
a pretty reasonable solution...but didn't fit the situation with void
not being an antiform of the word "void"

But that's changed, and now void *is* the antiform of the word void.
So ~void~ makes a good indicator in the typespec if you want to call
more attention to it than with the function VOID?.

So this finally bites the bullet and shifts to using ~null~ and ~void~.

extensions/console/ext-console-init.reb

@@ -271,7 +271,7 @@ export console!: make object! [
         "Receives line input, parse/transform, send back to CONSOLE eval"
 
         return: "null if EOF, ~escape~ if canceled, else line of text input"
-            [<opt> text! quasi-word?]
+            [~null~ text! quasi-word?]
     ][
         return read-line
     ]
@@ -431,13 +431,13 @@ ext-console-impl: func [
     return: "Code for C caller to sandbox, exit status, RESUME code, or hook"
         [block! group! integer! meta-group! handle!]  ; RETURN is hooked below!
     prior "BLOCK! or GROUP! that last invocation of HOST-CONSOLE requested"
-        [<opt> block! group!]
+        [~null~ block! group!]
     result "^META result from evaluating PRIOR, or non-quoted error"
-        [<opt> error! quoted? quasi?]
+        [~null~ error! quoted? quasi?]
     resumable "Is the RESUME function allowed to exit this console"
         [logic?]
     skin "Console skin to use if the console has to be launched"
-        [<opt> object! file!]
+        [~null~ object! file!]
 ][
     === HOOK RETURN FUNCTION TO GIVE EMITTED INSTRUCTION ===
 

extensions/crypt/mod-crypt.c

@@ -1465,7 +1465,7 @@ DECLARE_NATIVE(aes_key)
 //  "Encrypt/decrypt data using AES algorithm"
 //
 //      return: "Encrypted/decrypted data (null if zero length)"
-//          [<opt> binary!]
+//          [~null~ binary!]
 //      ctx "Stream cipher context"
 //          [handle!]
 //      data [binary!]

extensions/debugger/ext-debugger-init.reb

@@ -111,7 +111,7 @@ Expect crashes and mayhem.  But see BACKTRACE, RESUME, and STEP.}
 backtrace*: func [
     "Backtrace to find a specific FRAME!, or other queried property."
 
-    return: [<opt> block! frame!]
+    return: [~null~ block! frame!]
         "Nothing if printing, if specific level a frame! else block"
     start [frame!]
         "Where to consider the trace point as starting from"
@@ -338,7 +338,7 @@ interrupt: adapt :breakpoint* [
 debug: func [
     {Dialect for interactive debugging, see documentation for details}
     return: [~]
-    'value [<opt> integer! frame! block!]
+    'value [~null~ integer! frame! block!]
         {Stack level to inspect or dialect block, or enter debug mode}
 ][
     if not integer? :value [

extensions/filesystem/mod-filesystem.c

@@ -568,7 +568,7 @@ DECLARE_NATIVE(file_to_local)
 //
 //  "Returns the current directory path"
 //
-//      return: [<opt> file! url!]
+//      return: [~null~ file! url!]
 //  ]
 //
 DECLARE_NATIVE(what_dir)
@@ -608,7 +608,7 @@ DECLARE_NATIVE(what_dir)
 //
 //  "Changes the current path (where scripts with relative paths will be run)"
 //
-//      return: [<opt> file! url!]
+//      return: [~null~ file! url!]
 //      path [<maybe> file! url!]
 //  ]
 //
@@ -648,7 +648,7 @@ extern Value* Get_Current_Exec(void);
 //
 //  "Get the current path to the running executable"
 //
-//      return: [<opt> file!]
+//      return: [~null~ file!]
 //  ]
 //
 DECLARE_NATIVE(get_current_exec)

extensions/javascript/mod-javascript.c

@@ -972,7 +972,7 @@ DECLARE_NATIVE(js_native)
 //  "Evaluate textual JavaScript code"
 //
 //      return: "Note: Only supports types that reb.Box() supports"
-//          [~ <opt> logic? integer! text!]
+//          [~ ~null~ logic? integer! text!]
 //      source "JavaScript code as a text string" [text!]
 //      /local "Evaluate in local scope (as opposed to global)"
 //      /value "Return a Rebol value"

extensions/javascript/tools/prep-libr3-js.reb

@@ -251,7 +251,7 @@ e-cwrap/emit {
 }
 
 to-js-type: func [
-    return: [<opt> text! tag!]
+    return: [~null~ text! tag!]
     s [text!] "C type as string"
 ][
     return case [

extensions/locale/ext-locale-init.reb

@@ -451,7 +451,7 @@ if 'Windows <> first system.platform [
     "zu" "Zulu" ]
 
     hijack :locale func [
-        return: [<opt> text!]
+        return: [~null~ text!]
         type [word!]
         <static>
         iso-639 (iso-639-table)

extensions/locale/mod-locale.c

@@ -42,7 +42,7 @@ typedef RebolValue Value;
 //
 //   "Get locale specific information"
 //
-//      return: [<opt> text!]
+//      return: [~null~ text!]
 //      category [word!]
 //          {Language: English name of the language,
 //          Territory: English name of the country/region,
@@ -134,7 +134,7 @@ DECLARE_NATIVE(locale)
 //
 //  "Set/Get current locale, just a simple wrapper around C version"
 //
-//      return: [<opt> text!]
+//      return: [~null~ text!]
 //      category [word!]
 //      value [text!]
 //  ]

extensions/network/mod-network.c

@@ -1168,8 +1168,8 @@ DECLARE_NATIVE(shutdown_p)
 //  "Waits for a duration, port, or both"
 //
 //      return: "NULL if timeout, PORT! that awoke or BLOCK! of ports if /ALL"
-//          [<opt> port! block!]
-//      value [<opt> any-number? time! port! block!]
+//          [~null~ port! block!]
+//      value [~null~ any-number? time! port! block!]
 //  ]
 //
 DECLARE_NATIVE(wait_p)  // See wrapping function WAIT in usermode code

extensions/odbc/mod-odbc.c

@@ -838,7 +838,7 @@ SQLRETURN Get_ODBC_Catalog(
     int index;
     for (index = 2; index != 6; ++index) {
         pattern[index - 2] = rebSpellWide(  // gives nullptr if BLANK!
-            "ensure [<opt> text!]",
+            "ensure [~null~ text!]",
                 "pick ensure block!", block, rebI(index)
         );
     }
@@ -1233,7 +1233,7 @@ DECLARE_NATIVE(insert_odbc)
         // then prepare a new statement.
         //
         use_cache = rebUnboxLogic(
-            "strict-equal? (first sql) ensure [<opt> text!] statement.string"
+            "strict-equal? (first sql) ensure [~null~ text!] statement.string"
         );
 
         SQLLEN sql_index = 1;

extensions/process/mod-process.c

@@ -265,7 +265,7 @@ static void kill_process(pid_t pid, int signal)
 //
 //  "Terminate a process (not current one)"
 //
-//      return: [<opt>]
+//      return: [~null~]
 //      pid [integer!]
 //          {The process ID}
 //  ]
@@ -336,7 +336,7 @@ DECLARE_NATIVE(terminate)
 //  "Returns the value of an OS environment variable (for current process)"
 //
 //      return: "String the variable was set to, or null if not set"
-//          [<opt> text!]
+//          [~null~ text!]
 //      variable "Name of variable to get (case-insensitive in Windows)"
 //          [<maybe> text! word!]
 //  ]
@@ -448,10 +448,10 @@ DECLARE_NATIVE(get_env)
 //  "Sets value of operating system environment variable for current process"
 //
 //      return: "Returns same value passed in"
-//          [<opt> text!]
+//          [~null~ text!]
 //      variable [<maybe> text! word!]
 //          "Variable to set (case-insensitive in Windows)"
-//      value [<opt> text!]
+//      value [~null~ text!]
 //          "Value to set the variable to, or NULL to unset it"
 //  ]
 //
@@ -464,7 +464,7 @@ DECLARE_NATIVE(set_env)
 
   #if TO_WINDOWS
     WCHAR* key_wide = rebSpellWide(variable);
-    Option(WCHAR*) val_wide = rebSpellWideMaybe("ensure [<opt> text!]", value);
+    Option(WCHAR*) val_wide = rebSpellWideMaybe("ensure [~null~ text!]", value);
 
     if (not SetEnvironmentVariable(
         key_wide,

extensions/process/process-posix.c

@@ -127,7 +127,7 @@ DECLARE_NATIVE(set_uid)
 //  "Get effective user ID of the process"
 //
 //      return: "Same ID as input"
-//          [<opt>]
+//          [~null~]
 //      euid "The effective user ID"
 //          [integer!]
 //  ]
@@ -158,7 +158,7 @@ DECLARE_NATIVE(set_euid)
 //  "Set real group ID of the process"
 //
 //      return: "Same ID as input"
-//          [<opt>]
+//          [~null~]
 //      gid "The effective group ID"
 //          [integer!]
 //  ]

extensions/stdio/mod-stdio.c

@@ -161,7 +161,7 @@ DECLARE_NATIVE(write_stdout)
 //  "Read binary data from standard input"
 //
 //      return: "Null if no more input is available, ~escape~ if aborted"
-//          [<opt> binary! quasi-word?]
+//          [~null~ binary! quasi-word?]
 //      @eof "Set to true if end of file reached"
 //          [logic?]
 //      size "Maximum size of input to read"
@@ -230,7 +230,7 @@ DECLARE_NATIVE(read_stdin)
 //  "Read a line from standard input, with smart line editing if available"
 //
 //      return: "Null if no more input is available, ~escape~ if aborted"
-//          [<opt> text! quasi-word?]
+//          [~null~ text! quasi-word?]
 //      @eof "Set to true if end of file reached"
 //          [logic?]
 //      /raw "Include the newline, and allow reaching end of file with no line"
@@ -392,7 +392,7 @@ DECLARE_NATIVE(read_line)
 //  "Inputs a single character from the input"
 //
 //      return: "Null if end of file or input was aborted (e.g. via ESCAPE)"
-//          [<opt> char? word! quasi-word?]
+//          [~null~ char? word! quasi-word?]
 //
 //      /virtual "Return keys like Up, Ctrl-A, or ESCAPE vs. ignoring them"
 //      /timeout "Seconds to wait before returning ~timeout~ if no input"

extensions/tcc/mod-tcc.c

@@ -182,7 +182,7 @@ static void Process_Text_Helper(
     const char *label
 ){
     Value* text = rebValue(
-        "ensure [<opt> text!] select", config, "as word!", rebT(label)
+        "ensure [~null~ text!] select", config, "as word!", rebT(label)
     );
 
     if (text) {
@@ -383,7 +383,7 @@ DECLARE_NATIVE(make_native)
 //  "INTERNAL USE ONLY: Expects arguments to be fully vetted by COMPILE"
 //
 //      return: "No return value, unless /INSPECT is used to see result"
-//          [<opt> text!]
+//          [~null~ text!]
 //      compilables [block!] "Should be just TEXT! and user native ACTION!s"
 //      config [object!] "Vetted and simplified form of /OPTIONS block"
 //      /inspect "Return the C source code as text, but don't compile it"

extensions/view/mod-view.c

@@ -94,7 +94,7 @@ typedef RebolValue Value;
 //  "Asks user to select file(s) and returns full file path(s)"
 //
 //      return: "Null if canceled, otherwise a path or block of paths"
-//          [<opt> file! block!]
+//          [~null~ file! block!]
 //      /save "File save mode"
 //      /multi "Allows multiple file selection, returned as a block"
 //      /initial "Default file name or directory"

scripts/encap.reb

@@ -231,7 +231,7 @@ elf-format: context [
     ]
 
     find-section: meth [
-        return: [<opt> integer!]
+        return: [~null~ integer!]
             {The index of the section header with encap (sh_xxx vars set)}
         name [text!]
         section-headers [binary!]
@@ -489,7 +489,7 @@ elf-format: context [
     ]
 
     get-embedding: meth [
-        return: [<opt> binary!]
+        return: [~null~ binary!]
         file [file!]
     ][
         let header-data: read/part file 64  ; 64-bit size, 32-bit is smaller
@@ -999,7 +999,7 @@ pe-format: context [
 
     find-section: func [
         "Find a section to the exe"
-        return: [<opt> binary!]
+        return: [~null~ binary!]
         exe-data [binary!]
         section-name [text!]
         /header "Return only the section header"
@@ -1157,7 +1157,7 @@ pe-format: context [
     ]
 
     get-embedding: func [
-        return: [<opt> binary!]
+        return: [~null~ binary!]
         file [file!]
     ][
         ;print ["Geting embedded from" mold file]
@@ -1219,7 +1219,7 @@ generic-format: context [
     ]
 
     get-embedding: meth [
-        return: [<opt> binary!]
+        return: [~null~ binary!]
         file [file!]
     ][
         let info: query file
@@ -1301,7 +1301,7 @@ encap: func [
 
 get-encap: func [
     return: "NULL if no encapping found, unzipped BLOCK! results if found"
-        [<opt> block!]
+        [~null~ block!]
     rebol-path "The executable to search for the encap information in"
         [file!]
 ][

scripts/make-file.r

@@ -232,7 +232,7 @@ make-file-path-parts: func [
 make-file: func [
     {Create a FILE! using the file path specification dialect}
 
-    return: [<opt> file!]
+    return: [~null~ file!]
     def [<maybe> word! path! tuple! block!]
     /predicate [action?]
     <local> result

scripts/prot-http.r

@@ -77,7 +77,7 @@ make-http-request: func [
         {In case of text!, no escaping is performed.}
         {(eg. useful to override escaping etc.). Careful!}
     headers [block!] "Request headers (set-word! text! pairs)"
-    content [<opt> text! binary!]
+    content [~null~ text! binary!]
         {Request contents (Content-Length is created automatically).}
         {Empty string not exactly like blank.}
     <local> result

scripts/prot-tls.r

@@ -272,7 +272,7 @@ make-tls-error: lambda [
 parse-asn: func [
     {Create a legible Rebol-structured BLOCK! from an ASN.1 BINARY! encoding}
 
-    return: [<opt> block!]
+    return: [~null~ block!]
     data [binary!]
 
     <static>
@@ -421,7 +421,7 @@ make-state-updater: func [
         ctx [object!]
         new [tag! issue!]
     ][
-        let old: ensure [<opt> issue! tag!] ctx.mode
+        let old: ensure [~null~ issue! tag!] ctx.mode
         debug [mold old unspaced ["=" direction "=>"] mold new]
 
         let legal
@@ -1817,7 +1817,7 @@ sys.util.make-scheme [
         ]
 
         write: func [
-            return: [<opt> port!]
+            return: [~null~ port!]
             port [port!]
             value [any-value?]
         ][
@@ -2049,7 +2049,7 @@ sys.util.make-scheme [
             return if port.data [copy port.data]
         ]
 
-        query: func [return: [<opt> object!] port [port!]] [
+        query: func [return: [~null~ object!] port [port!]] [
             return all [port.state, query port.state.connection]
         ]
     ]

src/boot/errors.r

@@ -162,7 +162,7 @@ Script: [
     bad-func-def:       [{invalid function definition:} :arg1]
     bad-func-arg:       [{function argument} :arg1 {is not valid}]
 
-    needs-return-opt:   [:arg1 {can't return null (see RETURN: [<opt> ...])}]
+    needs-return-opt:   [:arg1 {can't return null (see RETURN: [~null~ ...])}]
     bad-return-type:    [:arg1 {doesn't have RETURN: enabled for} :arg2]
     bad-void-return:    [:arg1 {doesn't have void RETURN enabled}]
 
@@ -232,7 +232,7 @@ Script: [
     varargs-no-look:    {VARARGS! may only lookahead by 1 if "hard quoted"}
     varargs-take-last:  {VARARGS! does not support TAKE-ing only /LAST item}
 
-    null-vararg-array:  {Can't MAKE ANY-ARRAY? from VARARGS! that allow <opt>}
+    null-vararg-array:  {Can't MAKE ANY-ARRAY? from VARARGS! allowing ~null~}
     null-object-block:  {Can't create block from object if it has null values}
 
     conflicting-key:    [:arg1 {key conflicts; use SELECT or PUT with /CASE}]