Updates to the Lua compiler.

1 files changed, 983 insertions, 5 deletions

diff --git a/stdlib/source/documentation/lux.lux b/stdlib/source/documentation/lux.lux
index 4365ea0eb..a046d1fdc 100644
--- a/stdlib/source/documentation/lux.lux
+++ b/stdlib/source/documentation/lux.lux
@@ -5,7 +5,17 @@
     ["$" documentation (#+ documentation:)]
     ["." debug]
     [control
-     ["." io]]]]
+     ["." io]
+     ["<>" parser
+      ["<.>" code]]]
+    [data
+     ["." text (#+ \n)
+      ["%" format (#+ format)]]
+     [collection
+      ["." list]
+      ["." set]]]
+    [macro
+     ["." template]]]]
   [\\library
    ["." /]]
   ["." / #_
@@ -14,6 +24,7 @@
    ["#." data]
    ["#." debug]
    ["#." documentation]
+   ["#." extension]
    ["#." ffi]
    ["#." locale]
    ["#." macro]
@@ -26,22 +37,988 @@
    ["#." time]
    ... ["#." tool] ... TODO: Documentation for this
    ["#." type]
-   ... ["#." world]
-   ... ["#." extension]
+   ["#." world]
    ... ["#." target #_
    ...  <target>]
    ])
 
+(documentation: /.prelude_module
+  (format "The name of the prelude module"
+          \n "Value: " (%.text /.prelude_module)))
+
+(documentation: /.Any
+  (format "The type of things whose type is irrelevant."
+          \n "It can be used to write functions or data-structures that can take, or return, anything."))
+
+(documentation: /.Nothing
+  (format "The type of things whose type is undefined."
+          \n "Useful for expressions that cause errors or other 'extraordinary' conditions."))
+
+(documentation: /.List
+  "A potentially empty list of values.")
+
+(documentation: /.Bit
+  "Your standard, run-of-the-mill boolean values (as #0 or #1 bits).")
+
+(documentation: /.I64
+  "64-bit integers without any semantics.")
+
+(documentation: /.Nat
+  (format "Natural numbers (unsigned integers)."
+          \n "They start at zero (0) and extend in the positive direction."))
+
+(documentation: /.Int
+  "Your standard, run-of-the-mill integer numbers.")
+
+(documentation: /.Rev
+  (format "Fractional numbers that live in the interval [0,1)."
+          \n "Useful for probability, and other domains that work within that interval."))
+
+(documentation: /.Frac
+  "Your standard, run-of-the-mill floating-point (fractional) numbers.")
+
+(documentation: /.Text
+  "Your standard, run-of-the-mill string values.")
+
+(documentation: /.Name
+  "A name. It is used as part of Lux syntax to represent identifiers and tags.")
+
+(documentation: /.Maybe
+  "A potentially missing value.")
+
+(documentation: /.Type
+  "This type represents the data-structures that are used to specify types themselves.")
+
+(documentation: /.Location
+  "Locations are for specifying the location of Code nodes in Lux files during compilation.")
+
+(documentation: /.Ann
+  "The type of things that can be annotated with meta-data of arbitrary types.")
+
+(documentation: /.Code
+  "The type of Code nodes for Lux syntax.")
+
+(documentation: /.private
+  "The export policy for private/local definitions.")
+
+(documentation: /.local
+  "The export policy for private/local definitions.")
+
+(documentation: /.public
+  "The export policy for public/global definitions.")
+
+(documentation: /.global
+  "The export policy for public/global definitions.")
+
+(documentation: /.Definition
+  "Represents all the data associated with a definition: its type, its annotations, and its value.")
+
+(documentation: /.Global
+  "Represents all the data associated with a global constant.")
+
+(documentation: /.Either
+  "A choice between two values of different types.")
+
+(documentation: /.Module
+  "All the information contained within a Lux module.")
+
+(documentation: /.Mode
+  "A sign that shows the conditions under which the compiler is running.")
+
+(documentation: /.Info
+  "Information about the current version and type of compiler that is running.")
+
+(documentation: /.Lux
+  (format "Represents the state of the Lux compiler during a run."
+          \n "It is provided to macros during their invocation, so they can access compiler data."
+          \n "Caveat emptor: Avoid fiddling with it, unless you know what you're doing."))
+
+(documentation: /.Meta
+  (format "Computations that can have access to the state of the compiler."
+          \n "These computations may fail, or modify the state of the compiler."))
+
+(documentation: /.Macro
+  "Functions that run at compile-time and allow you to transform and extend the language in powerful ways.")
+
+(documentation: /.comment
+  (format "Throws away any code given to it."
+          \n "Great for commenting-out code, while retaining syntax high-lighting and formatting in your text editor.")
+  [(comment
+     (def: (this will not)
+       (Be Defined)
+       (because it will be (commented out))))])
+
+(documentation: /.All
+  "Universal quantification."
+  [(All [a]
+     (-> a a))]
+  ["A name can be provided, to specify a recursive type."
+   (All List [a]
+     (Or Any
+         [a (List a)]))])
+
+(documentation: /.Ex
+  "Existential quantification."
+  [(Ex [a]
+     [(Codec Text a) a])]
+  ["A name can be provided, to specify a recursive type."
+   (Ex Self [a]
+     [(Codec Text a)
+      a
+      (List (Self a))])])
+
+(documentation: /.->
+  "Function types."
+  ["This is the type of a function that takes 2 Ints and returns an Int."
+   (-> Int Int Int)])
+
+(documentation: /.list
+  "List literals."
+  [(: (List Nat)
+      (list 0 1 2 3))])
+
+(documentation: /.list&
+  "List literals, with the last element being a tail-list."
+  [(: (List Nat)
+      (list& 0 1 2 3
+             (: (List Nat)
+                (list 4 5 6))))])
+
+(documentation: /.Union
+  "Union types."
+  [(Union Bit Nat Text)]
+  [(= Nothing
+      (Union))])
+
+(documentation: /.Tuple
+  "Tuple types."
+  [(Tuple Bit Nat Text)]
+  [(= Any
+      (Tuple))])
+
+(documentation: /.Or
+  "An alias for the Union type constructor."
+  [(= (Union Bit Nat Text)
+      (Or Bit Nat Text))]
+  [(= (Union)
+      (Or))])
+
+(documentation: /.And
+  "An alias for the Tuple type constructor."
+  [(= (Tuple Bit Nat Text)
+      (And Bit Nat Text))]
+  [(= (Tuple)
+      (And))])
+
+(documentation: /._$
+  "Left-association for the application of binary functions over variadic arguments."
+  [(_$ text\composite "Hello, " name ". How are you?")
+   "=>"
+   (text\composite (text\composite "Hello, " name) ". How are you?")])
+
+(documentation: /.$_
+  "Right-association for the application of binary functions over variadic arguments."
+  [($_ text\composite "Hello, " name ". How are you?")
+   "=>"
+   (text\composite "Hello, " (text\composite name ". How are you?"))])
+
+(documentation: /.if
+  "Picks which expression to evaluate based on a bit test value."
+  [(if #1
+     "Oh, yeah!"
+     "Aw hell naw!")
+   "=>"
+   "Oh, yeah!"]
+  [(if #0
+     "Oh, yeah!"
+     "Aw hell naw!")
+   "=>"
+   "Aw hell naw!"])
+
+(documentation: /.primitive
+  "Macro to treat define new primitive types."
+  [(primitive "java.lang.Object")]
+  [(primitive "java.util.List" [(primitive "java.lang.Long")])])
+
+(documentation: /.`
+  (format "Hygienic quasi-quotation as a macro."
+          \n "Unquote (~) and unquote-splice (~+) must also be used as forms."
+          \n "All unprefixed macros will receive their parent module's prefix if imported; otherwise will receive the prefix of the module on which the quasi-quote is being used.")
+  [(` (def: (~ name)
+        (function ((~' _) (~+ args))
+          (~ body))))])
+
+(documentation: /.`'
+  (format "Unhygienic quasi-quotation as a macro."
+          \n "Unquote (~) and unquote-splice (~+) must also be used as forms.")
+  [(`' (def: (~ name)
+         (function (_ (~+ args))
+           (~ body))))])
+
+(documentation: /.'
+  "Quotation as a macro."
+  [(' YOLO)])
+
+(documentation: /.|>
+  "Piping macro."
+  [(|> elems
+       (list\each int\encoded)
+       (interposed " ")
+       (mix text\composite ""))
+   "=>"
+   (mix text\composite ""
+        (interposed " "
+                    (list\each int\encoded
+                               elems)))])
+
+(documentation: /.<|
+  "Reverse piping macro."
+  [(<| (mix text\composite "")
+       (interposed " ")
+       (list\each int\encoded)
+       elems)
+   "=>"
+   (mix text\composite ""
+        (interposed " "
+                    (list\each int\encoded
+                               elems)))])
+
+(documentation: /.template
+  ""
+  ["By specifying a pattern (with holes), and the input data to fill those holes, repeats the pattern as many times as necessary."
+   (template [<name> <diff>]
+     [(def: .public <name>
+        (-> Int Int)
+        (+ <diff>))]
+     [++ +1]
+     [-- -1])])
+
+(documentation: /.not
+  "Bit negation."
+  [(not #1)
+   "=>"
+   #0]
+  [(not #0)
+   "=>"
+   #1])
+
+(documentation: /.type
+  "Takes a type expression and returns its representation as data-structure."
+  [(type (All [a]
+           (Maybe (List a))))])
+
+(documentation: /.:
+  "The type-annotation macro."
+  [(: (List Int)
+      (list +1 +2 +3))])
+
+(documentation: /.:as
+  "The type-coercion macro."
+  [(:as Dinosaur
+        (list +1 +2 +3))])
+
+(documentation: /.Rec
+  "Parameter-less recursive types."
+  ["A name has to be given to the whole type, to use it within its body."
+   (Rec Int_List
+     (Or Any
+         [Int Int_List]))])
+
+(documentation: /.exec
+  "Sequential execution of expressions (great for side-effects)."
+  [(exec
+     (log! "#1")
+     (log! "#2")
+     (log! "#3")
+     "YOLO")])
+
+(documentation: /.case
+  (format "The pattern-matching macro."
+          \n "Allows the usage of macros within the patterns to provide custom syntax.")
+  [(case (: (List Int)
+            (list +1 +2 +3))
+     (#Item x (#Item y (#Item z #End)))
+     (#Some ($_ * x y z))
+
+     _
+     #None)])
+
+(documentation: /.^
+  (format "Macro-expanding patterns."
+          \n "It's a special macro meant to be used with 'case'.")
+  [(case (: (List Int)
+            (list +1 +2 +3))
+     (^ (list x y z))
+     (#Some ($_ * x y z))
+
+     _
+     #None)])
+
+(documentation: /.^or
+  (format "Or-patterns."
+          \n "It's a special macro meant to be used with 'case'.")
+  [(type: Weekday
+     (Variant
+      #Monday
+      #Tuesday
+      #Wednesday
+      #Thursday
+      #Friday
+      #Saturday
+      #Sunday))
+   
+   (def: (weekend? day)
+     (-> Weekday Bit)
+     (case day
+       (^or #Saturday #Sunday)
+       #1
+
+       _
+       #0))])
+
+(documentation: /.let
+  (format "Creates local bindings."
+          \n "Can (optionally) use pattern-matching macros when binding.")
+  [(let [x (foo bar)
+         y (baz quux)]
+     (op x y))])
+
+(documentation: /.function
+  "Syntax for creating functions."
+  [(: (All [a b]
+        (-> a b a))
+      (function (_ x y)
+        x))]
+  ["Allows for giving the function itself a name, for the sake of recursion."
+   (: (-> Nat Nat)
+      (function (factorial n)
+        (case n
+          0 1
+          _ (* n  (factorial (-- n))))))])
+
+(documentation: /.def:
+  "Defines global constants/functions."
+  [(def: branching_exponent
+     Int
+     +5)]
+  ["The type is optional."
+   (def: branching_exponent
+     +5)]
+  [(def: (pair_list pair)
+     (-> [Code Code] (List Code))
+     (let [[left right] pair]
+       (list left right)))]
+  ["Can pattern-match on the inputs to functions."
+   (def: (pair_list [left right])
+     (-> [Code Code] (List Code))
+     (list left right))])
+
+(documentation: /.macro:
+  "Macro-definition macro."
+  [(macro: .public (name_of tokens)
+     (case tokens
+       (^template [<tag>]
+         [(^ (list [_ (<tag> [module name])]))
+          (in (list (` [(~ (text$ module)) (~ (text$ name))])))])
+       ([#Identifier] [#Tag])
+       
+       _
+       (failure "Wrong syntax for name_of")))])
+
+(documentation: /.and
+  "Short-circuiting 'and'."
+  [(and #1 #0)
+   "=>"
+   #0]
+  [(and #1 #1)
+   "=>"
+   #1])
+
+(documentation: /.or
+  "Short-circuiting 'or'."
+  [(or #1 #0)
+   "=>"
+   #1]
+  [(or #0 #0)
+   "=>"
+   #0])
+
+(documentation: /.panic!
+  "Causes an error, with the given error message."
+  [(panic! "OH NO!")])
+
+(documentation: /.implementation
+  "Express a value that implements an interface."
+  [(: (Order Int)
+      (implementation
+       (def: &equivalence
+         equivalence)
+       (def: (< reference subject)
+         (< reference subject))
+       ))])
+
+(documentation: /.implementation:
+  "Interface implementation."
+  [(implementation: .public order
+     (Order Int)
+     (def: &equivalence
+       equivalence)
+     (def: (< test subject)
+       (< test subject)))])
+
+(documentation: /.Variant
+  (format "Syntax for defining labelled/tagged sum/union types."
+          \n "WARNING: Only use it within the type: macro.")
+  [(type: Referrals
+     (Variant
+      #All
+      (#Only (List Text))
+      (#Exclude (List Text))
+      #Ignore
+      #Nothing))])
+
+(documentation: /.Record
+  (format "Syntax for defining labelled/slotted product/tuple types."
+          \n "WARNING: Only use it within the type: macro.")
+  [(type: Refer
+     (Record
+      {#refer_defs Referrals
+       #refer_open (List Openings)}))])
+
+(documentation: /.type:
+  "The type-definition macro."
+  [(type: (List a)
+     #End
+     (#Item a (List a)))])
+
+(documentation: /.interface:
+  "Interface definition."
+  [(interface: .public (Order a)
+     (: (Equivalence a)
+        &equivalence)
+     (: (-> a a Bit)
+        <))])
+
+(.template [<name>]
+  [(documentation: <name>
+     "Safe type-casting for I64 values.")]
+
+  [/.i64]
+  [/.nat]
+  [/.int]
+  [/.rev]
+  )
+
+(documentation: /.module_separator
+  (format "Character used to separate the parts of module names."
+          \n "Value: " (%.text /.module_separator)))
+
+(documentation: /.^open
+  (format "Same as the 'open' macro, but meant to be used as a pattern-matching macro for generating local bindings."
+          \n "Takes an 'alias' text for the generated local bindings.")
+  [(def: .public (range enum from to)
+     (All [a] (-> (Enum a) a a (List a)))
+     (let [(^open ".") enum]
+       (loop [end to
+              output #.End]
+         (cond (< end from)
+               (recur (pred end) (#.Item end output))
+
+               (< from end)
+               (recur (succ end) (#.Item end output))
+
+               ... (= end from)
+               (#.Item end output)))))])
+
+(documentation: /.cond
+  "Conditional branching with multiple test conditions."
+  [(cond (even? num) "WHEN even"
+         (odd? num) "WHEN odd"
+         "ELSE")])
+
+(documentation: /.value@
+  "Accesses the value of a record at a given tag."
+  [(value@ #field my_record)]
+  ["Can also work with multiple levels of nesting."
+   (value@ [#foo #bar #baz] my_record)]
+  ["And, if only the slot/path is given, generates an accessor function."
+   (let [getter (value@ [#foo #bar #baz])]
+     (getter my_record))])
+
+(documentation: /.open:
+  "Opens a implementation and generates a definition for each of its members (including nested members)."
+  [(open: "i:." order)
+   "=>"
+   (def: i:= (\ order =))
+   (def: i:< (\ order <))])
+
+(documentation: /.|>>
+  "Similar to the piping macro, but rather than taking an initial object to work on, creates a function for taking it."
+  [(|>> (list\each int\encoded)
+        (interposed " ")
+        (mix text\composite ""))
+   "=>"
+   (function (_ <it>)
+     (mix text\composite ""
+          (interposed " "
+                      (list\each int\encoded <it>))))])
+
+(documentation: /.<<|
+  "Similar to the reverse piping macro, but rather than taking an initial object to work on, creates a function for taking it."
+  [(<<| (mix text\composite "")
+        (interposed " ")
+        (list\each int\encoded))
+   "=>"
+   (function (_ <it>)
+     (mix text\composite ""
+          (interposed " "
+                      (list\each int\encoded
+                                 <it>))))])
+
+(documentation: /.module:
+  "Module-definition macro."
+  [(.module:
+     [lux #*
+      [control
+       ["M" monad #*]]
+      [data
+       maybe
+       ["." name ("#/." codec)]]
+      [macro
+       code]]
+     [//
+      [type ("." equivalence)]])])
+
+(documentation: /.\
+  "Allows accessing the value of a implementation's member."
+  [(\ codec encoded)]
+  ["Also allows using that value as a function."
+   (\ codec encoded +123)])
+
+(documentation: /.with@
+  "Sets the value of a record at a given tag."
+  [(with@ #name "Lux" lang)]
+  ["Can also work with multiple levels of nesting."
+   (with@ [#foo #bar #baz] value my_record)]
+  ["And, if only the slot/path and (optionally) the value are given, generates a mutator function."
+   (let [setter (with@ [#foo #bar #baz] value)]
+     (setter my_record))
+   (let [setter (with@ [#foo #bar #baz])]
+     (setter value my_record))])
+
+(documentation: /.revised@
+  "Modifies the value of a record at a given tag, based on some function."
+  [(revised@ #age ++ person)]
+  ["Can also work with multiple levels of nesting."
+   (revised@ [#foo #bar #baz] func my_record)]
+  ["And, if only the slot/path and (optionally) the value are given, generates a mutator function."
+   (let [updater (revised@ [#foo #bar #baz] func)]
+     (updater my_record))
+   (let [updater (revised@ [#foo #bar #baz])]
+     (updater func my_record))])
+
+(documentation: /.^template
+  "It's similar to template, but meant to be used during pattern-matching."
+  [(def: (reduced env type)
+     (-> (List Type) Type Type)
+     (case type
+       (#.Primitive name params)
+       (#.Primitive name (list\each (reduced env) params))
+
+       (^template [<tag>]
+         [(<tag> left right)
+          (<tag> (reduced env left) (reduced env right))])
+       ([#.Sum] [#.Product])
+
+       (^template [<tag>]
+         [(<tag> left right)
+          (<tag> (reduced env left) (reduced env right))])
+       ([#.Function] [#.Apply])
+
+       (^template [<tag>]
+         [(<tag> old_env def)
+          (case old_env
+            #.End
+            (<tag> env def)
+
+            _
+            type)])
+       ([#.UnivQ] [#.ExQ])
+
+       (#.Parameter idx)
+       (else type (list.item idx env))
+
+       _
+       type
+       ))])
+
+(.template [<name> <doc>]
+  [(documentation: <name>
+     <doc>)]
+
+  [/.++ "Increment function."]
+  [/.-- "Decrement function."]
+  )
+
+(documentation: /.loop
+  (format "Allows arbitrary looping, using the 'recur' form to re-start the loop."
+          \n "Can be used in monadic code to create monadic loops.")
+  [(loop [count +0
+          x init]
+     (if (< +10 count)
+       (recur (++ count) (f x))
+       x))]
+  ["Loops can also be given custom names."
+   (loop my_loop
+     [count +0
+      x init]
+     (if (< +10 count)
+       (my_loop (++ count) (f x))
+       x))])
+
+(documentation: /.^slots
+  "Allows you to extract record members as local variables with the same names."
+  [(let [(^slots [#foo #bar #baz]) quux]
+     (f foo bar baz))])
+
+(documentation: /.with_expansions
+  (format "Controlled macro-expansion."
+          \n "Bind an arbitraty number of Code nodes resulting from macro-expansion to local bindings."
+          \n "Wherever a binding appears, the bound Code nodes will be spliced in there.")
+  [(def: test
+     Test
+     (with_expansions
+       [<tests> (template [<function> <parameter> <expected>]
+                  [(cover [<function>]
+                          (compare <text>
+                                   (\ codec encoded <function> <parameter>)))]
+
+                  [bit #1                              "#1"]
+                  [int +123                            "+123"]
+                  [frac +123.0                         "+123.0"]
+                  [text "123"                           "'123'"]
+                  [tag ["yolo" "lol"]                  "#yolo.lol"]
+                  [identifier ["yolo" "lol"]           "yolo.lol"]
+                  [form (list (bit #1))                "(#1)"]
+                  [tuple (list (bit #1))               "[#1]"]
+                  [record (list [(bit #1) (int +123)]) "{#1 +123}"]
+                  )]
+       ($_ and
+           <tests>
+           )))])
+
+(documentation: /.static
+  (format "Resolves the names of definitions to their values at compile-time, assuming their values are either:"
+          \n "* Bit"
+          \n "* Nat"
+          \n "* Int"
+          \n "* Rev"
+          \n "* Frac"
+          \n "* Text")
+  [(def: my_nat 123)
+   (def: my_text "456")
+   (and (case [my_nat my_text]
+          (^ (static [..my_nat ..my_text]))
+          true
+
+          _
+          false)
+        (case [my_nat my_text]
+          (^ [(static ..my_nat) (static ..my_text)])
+          true
+
+          _
+          false))])
+
+(documentation: /.^multi
+  (format "Multi-level pattern matching."
+          \n "Useful in situations where the result of a branch depends on further refinements on the values being matched.")
+  [(case (split (size static) uri)
+     (^multi (#Some [chunk uri'])
+             {(text\= static chunk) #1})
+     (match_uri endpoint? parts' uri')
+
+     _
+     (#Left (format "Static part " (%t static) " does not match URI: " uri)))]
+  ["Short-cuts can be taken when using bit tests."
+   "The example above can be rewritten as..."
+   (case (split (size static) uri)
+     (^multi (#Some [chunk uri'])
+             (text\= static chunk))
+     (match_uri endpoint? parts' uri')
+
+     _
+     (#Left (format "Static part " (%t static) " does not match URI: " uri)))])
+
+(documentation: /.name_of
+  "Given an identifier or a tag, gives back a 2 tuple with the module and name parts, both as Text."
+  [(name_of #.doc)
+   "=>"
+   ["library/lux" "doc"]])
+
+(documentation: /.:parameter
+  (format "WARNING: Please stay away from this macro; it's very likely to be removed in a future version of Lux."
+          "Allows you to refer to the type-variables in a polymorphic function's type, by their index.")
+  ["In the example below, 0 corresponds to the 'a' variable."
+   (def: .public (of_list list)
+     (All [a] (-> (List a) (Row a)))
+     (list\mix add
+               (: (Row (:parameter 0))
+                  empty)
+               list))])
+
+(documentation: /.same?
+  "Tests whether the 2 values are identical (not just 'equal')."
+  ["This one should succeed:"
+   (let [value +5]
+     (same? value
+            value))]
+  ["This one should fail:"
+   (same? +5
+          (+ +2 +3))])
+
+(documentation: /.^@
+  "Allows you to simultaneously bind and de-structure a value."
+  [(def: (hash (^@ set [member_hash _]))
+     (list\mix (function (_ elem acc)
+                 (+ acc
+                    (\ member_hash hash elem)))
+               0
+               (set.list set)))])
+
+(documentation: /.^|>
+  "Pipes the value being pattern-matched against prior to binding it to a variable."
+  [(case input
+     (^|> value [++ (% 10) (max 1)])
+     (foo value))])
+
+(documentation: /.:expected
+  "Coerces the given expression to the type of whatever is expected."
+  [(: Dinosaur
+      (:expected (: (List Nat)
+                    (list 1 2 3))))])
+
+(documentation: /.undefined
+  (format "Meant to be used as a stand-in for functions with undefined implementations."
+          \n "Undefined expressions will type-check against everything, so they make good dummy implementations."
+          \n "However, if an undefined expression is ever evaluated, it will raise a runtime error.")
+  [(def: (square x)
+     (-> Int Int)
+     (undefined))])
+
+(documentation: /.:of
+  "Generates the type corresponding to a given expression."
+  [(let [my_num +123]
+     (:of my_num))
+   "=="
+   Int]
+  [(:of +123)
+   "=="
+   Int])
+
+(documentation: /.template:
+  (format "Define macros in the style of template and ^template."
+          \n "For simple macros that do not need any fancy features.")
+  [(template: (square x)
+     (* x x))])
+
+(documentation: /.as_is
+  (format "Given a (potentially empty) list of codes, just returns them immediately, without any work done."
+          \n "This may seen useless, but it has its utility when dealing with controlled-macro-expansion macros.")
+  [(with_expansions [<operands> (as_is 1
+                                       2
+                                       3
+                                       4)]
+     ($_ + <operands>))])
+
+(documentation: /.char
+  "If given a 1-character text literal, yields the char-code of the sole character."
+  [(: Nat
+      (char "A"))
+   "=>"
+   65])
+
+(documentation: /.for
+  (format "Selects the appropriate code for a given target-platform when compiling Lux to it."
+          \n "Look-up the available targets in library/lux/target.")
+  [(def: js "JavaScript")
+   (for {"JVM" (do jvm stuff)
+         ..js (do js stuff)}
+        (do default stuff))])
+
+(documentation: /.``
+  (format "Delimits a controlled (spliced) macro-expansion."
+          \n "Uses a (~~) special form to specify where to expand.")
+  [(`` (some expression
+             (~~ (some macro which may yield 0 or more results))))])
+
+(documentation: /.^code
+  "Generates pattern-matching code for Code values in a way that looks like code-templating."
+  [(: (Maybe Nat)
+      (case (` (#0 123 +456.789))
+        (^code (#0 (~ [_ (#.Nat number)]) +456.789))
+        (#.Some number)
+
+        _
+        #.None))])
+
+(documentation: /.false
+  "The boolean FALSE value.")
+
+(documentation: /.true
+  "The boolean TRUE value.")
+
+(documentation: /.:let
+  "Local bindings for types."
+  [(:let [side (Either Int Frac)]
+     (List [side side]))])
+
+(documentation: /.try
+  ""
+  [(: Foo
+      (case (: (Either Text Bar)
+               (try (: Bar
+                       (risky computation which may panic))))
+        (#.Right success)
+        (: Foo
+           (do something after success))
+
+        (#.Left error)
+        (: Foo
+           (recover from error))))])
+
 (.def: .public documentation
   (.List $.Module)
   ($.module /._
             ""
-            []
+            [..prelude_module
+             ..Any
+             ..Nothing
+             ..List
+             ..Bit
+             ..I64
+             ..Nat
+             ..Int
+             ..Rev
+             ..Frac
+             ..Text
+             ..Name
+             ..Maybe
+             ..Type
+             ..Location
+             ..Ann
+             ..Code
+             ..private
+             ..local
+             ..public
+             ..global
+             ..Definition
+             ..Global
+             ..Either
+             ..Module
+             ..Mode
+             ..Info
+             ..Lux
+             ..Meta
+             ..Macro
+             ..comment
+             ..All
+             ..Ex
+             ..->
+             ..list
+             ..list&
+             ..Union
+             ..Tuple
+             ..Or
+             ..And
+             .._$
+             ..$_
+             ..if
+             ..primitive
+             ..`
+             ..`'
+             ..'
+             ..|>
+             ..<|
+             ..template
+             ..not
+             ..type
+             ..:
+             ..:as
+             ..Rec
+             ..exec
+             ..case
+             ..^
+             ..^or
+             ..let
+             ..function
+             ..def:
+             ..macro:
+             ..and
+             ..or
+             ..panic!
+             ..implementation
+             ..implementation:
+             ..Variant
+             ..Record
+             ..type:
+             ..interface:
+             ..i64
+             ..nat
+             ..int
+             ..rev
+             ..module_separator
+             ..^open
+             ..cond
+             ..value@
+             ..open:
+             ..|>>
+             ..<<|
+             ..module:
+             ..\
+             ..with@
+             ..revised@
+             ..^template
+             ..++
+             ..--
+             ..loop
+             ..^slots
+             ..with_expansions
+             ..static
+             ..^multi
+             ..name_of
+             ..:parameter
+             ..same?
+             ..^@
+             ..^|>
+             ..:expected
+             ..undefined
+             ..:of
+             ..template:
+             ..as_is
+             ..char
+             ..for
+             ..``
+             ..^code
+             ..false
+             ..true
+             ..:let
+             ..try
+             ($.default /.Code')
+             ($.default /.Alias)
+             ($.default /.Bindings)
+             ($.default /.Ref)
+             ($.default /.Scope)
+             ($.default /.Source)
+             ($.default /.Module_State)
+             ($.default /.Type_Context)
+             ($.default /.Macro')]
             [/abstract.documentation
              /control.documentation
              /data.documentation
              /debug.documentation
              /documentation.documentation
+             /extension.documentation
              /ffi.documentation
              /locale.documentation
              /macro.documentation
@@ -52,7 +1029,8 @@
              /target.documentation
              /test.documentation
              /time.documentation
-             /type.documentation]))
+             /type.documentation
+             /world.documentation]))
 
 (program: inputs
   (io.io (debug.log! ($.documentation ..documentation))))