From 224797231a8144f6ead1baab3b4b01a74cab629c Mon Sep 17 00:00:00 2001
From: Eduardo Julian
Date: Mon, 21 Nov 2022 16:40:51 -0400
Subject: Added index section to documentation + re-named Primitive -> Nominal

---
 stdlib/source/documentation/lux.lux                |  14 +--
 .../documentation/lux/data/collection/array.lux    |   2 +-
 stdlib/source/documentation/lux/data/color.lux     |  13 +--
 .../source/documentation/lux/data/color/named.lux  |   9 +-
 stdlib/source/documentation/lux/meta/type.lux      |   8 +-
 .../source/documentation/lux/meta/type/linear.lux  |  97 ++++++++++++++++
 .../source/documentation/lux/meta/type/nominal.lux | 122 +++++++++++++++++++++
 .../documentation/lux/meta/type/primitive.lux      | 122 ---------------------
 .../documentation/lux/meta/type/resource.lux       |  97 ----------------
 9 files changed, 238 insertions(+), 246 deletions(-)
 create mode 100644 stdlib/source/documentation/lux/meta/type/linear.lux
 create mode 100644 stdlib/source/documentation/lux/meta/type/nominal.lux
 delete mode 100644 stdlib/source/documentation/lux/meta/type/primitive.lux
 delete mode 100644 stdlib/source/documentation/lux/meta/type/resource.lux

(limited to 'stdlib/source/documentation')

diff --git a/stdlib/source/documentation/lux.lux b/stdlib/source/documentation/lux.lux
index 84fb5c9d7..07e6a2dc2 100644
--- a/stdlib/source/documentation/lux.lux
+++ b/stdlib/source/documentation/lux.lux
@@ -225,10 +225,10 @@
           ($.comment "=>")
           ($.example "Aw hell naw!"))
 
-        ($.definition /.Primitive
-          "Macro to treat define new primitive types."
-          ($.example (Primitive "java.lang.Object"))
-          ($.example (Primitive "java.util.List" [(Primitive "java.lang.Long")])))
+        ($.definition /.Nominal
+          "Macro to treat define new nominal types."
+          ($.example (Nominal "java.lang.Object"))
+          ($.example (Nominal "java.util.List" [(Nominal "java.lang.Long")])))
 
         ($.definition /.`
           (format "Hygienic quasi-quotation as a macro."
@@ -324,7 +324,7 @@
               ($.example (type Type
                            (Rec @
                              (Variant
-                              {#Primitive Text (List @)}
+                              {#Nominal Text (List @)}
                               {#Sum @ @}
                               {#Product @ @}
                               {#Function @ @}
@@ -642,8 +642,8 @@
             ...   ($.example (def (reduced env type)
             ...                (-> (List Type) Type Type)
             ...                (when type
-            ...                  {.#Primitive name params}
-            ...                  {.#Primitive name (list#each (reduced env) params)}
+            ...                  {.#Nominal name params}
+            ...                  {.#Nominal name (list#each (reduced env) params)}
 
             ...                  (^with_template [<tag>]
             ...                                  [{<tag> left right}
diff --git a/stdlib/source/documentation/lux/data/collection/array.lux b/stdlib/source/documentation/lux/data/collection/array.lux
index 0f2c5094f..b806af2a4 100644
--- a/stdlib/source/documentation/lux/data/collection/array.lux
+++ b/stdlib/source/documentation/lux/data/collection/array.lux
@@ -15,7 +15,7 @@
   (list ($.module /._
                   "")
 
-        ($.definition /.primitive)
+        ($.definition /.nominal)
         ($.definition /.equivalence)
         ($.definition /.monoid)
         ($.definition /.functor)
diff --git a/stdlib/source/documentation/lux/data/color.lux b/stdlib/source/documentation/lux/data/color.lux
index 77162cec2..768fb1ffb 100644
--- a/stdlib/source/documentation/lux/data/color.lux
+++ b/stdlib/source/documentation/lux/data/color.lux
@@ -24,10 +24,7 @@
 
 (`` (def .public documentation
       (List $.Documentation)
-      (let [encoding (list ($.definition /.RGB
-                             "Red-Green-Blue color format.")
-
-                           ($.definition /.of_rgb)
+      (let [encoding (list ($.definition /.of_rgb)
                            ($.definition /.rgb)
 
                            ($.definition /.HSL
@@ -36,17 +33,11 @@
                            ($.definition /.hsl)
                            ($.definition /.of_hsl)
 
-                           ($.definition /.CMYK
-                             "Cyan-Magenta-Yellow-Key color format.")
-
                            ($.definition /.hsb)
                            ($.definition /.of_hsb)
 
                            ($.definition /.HSB
-                             "Hue-Saturation-Brightness color format.")
-
-                           ($.definition /.cmyk)
-                           ($.definition /.of_cmyk))
+                             "Hue-Saturation-Brightness color format."))
             transformation (list ($.definition /.gray_scale)
                                  ($.definition /.darker)
                                  ($.definition /.brighter)
diff --git a/stdlib/source/documentation/lux/data/color/named.lux b/stdlib/source/documentation/lux/data/color/named.lux
index cd4e683e0..49eb0847d 100644
--- a/stdlib/source/documentation/lux/data/color/named.lux
+++ b/stdlib/source/documentation/lux/data/color/named.lux
@@ -12,16 +12,17 @@
      ["[0]" nat (.use "hex#[0]" hex)]]]]]
  [\\library
   ["[0]" / (.only)
-   ["/[1]" //]]])
+   ["/[1]" // (.only)
+    ["[0]" rgb]]]])
 
 (def description
   (template (_ <name>)
     [($.definition <name>
        (let [[red green blue] (//.rgb <name>)
              [_ name] (symbol <name>)]
-         (format "R:" (hex#encoded red)
-                 " G:" (hex#encoded green)
-                 " B:" (hex#encoded blue)
+         (format "R:" (hex#encoded (rgb.number red))
+                 " G:" (hex#encoded (rgb.number green))
+                 " B:" (hex#encoded (rgb.number blue))
                  " | " (text.replaced "_" " " name))))]))
 
 (`` (def .public documentation
diff --git a/stdlib/source/documentation/lux/meta/type.lux b/stdlib/source/documentation/lux/meta/type.lux
index 292b084f2..b61ba2afd 100644
--- a/stdlib/source/documentation/lux/meta/type.lux
+++ b/stdlib/source/documentation/lux/meta/type.lux
@@ -14,14 +14,14 @@
  [\\library
   ["[0]" /]]
  ["[0]" /
-  ["[1][0]" primitive]
+  ["[1][0]" nominal]
   ["[1][0]" check]
   ["[1][0]" dynamic]
   ["[1][0]" implicit]
   ["[1][0]" poly]
   ["[1][0]" quotient]
   ["[1][0]" refinement]
-  ["[1][0]" resource]
+  ["[1][0]" linear]
   ["[1][0]" unit]
   ["[1][0]" variance]])
 
@@ -269,14 +269,14 @@
                     (all list#composite
                          ..\\parser
 
-                         /primitive.documentation
+                         /nominal.documentation
                          /check.documentation
                          /dynamic.documentation
                          /implicit.documentation
                          /poly.documentation
                          /quotient.documentation
                          /refinement.documentation
-                         /resource.documentation
+                         /linear.documentation
                          /unit.documentation
                          /variance.documentation
                          )
diff --git a/stdlib/source/documentation/lux/meta/type/linear.lux b/stdlib/source/documentation/lux/meta/type/linear.lux
new file mode 100644
index 000000000..c8e34ab6e
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/type/linear.lux
@@ -0,0 +1,97 @@
+(.require
+ [library
+  [lux (.except)
+   ["$" documentation]
+   [data
+    ["[0]" text (.only \n)
+     ["%" \\format (.only format)]]]]]
+ [\\library
+  ["[0]" /]])
+
+(`` (def .public documentation
+      (List $.Documentation)
+      (list ($.module /._
+                      "")
+
+            ($.definition /.monad)
+            ($.definition /.index_cannot_be_repeated)
+            ($.definition /.amount_cannot_be_zero)
+
+            ($.definition (/.Procedure monad input output value)
+              (format "A computation that takes a sequence of resource access rights as inputs and yields a different sequence as outputs."
+                      \n "A procedure yields a result value."
+                      \n "A procedure can make use of monadic effects."))
+
+            ($.definition (/.Linear monad value)
+              (format "A procedure that is constant with regards to resource access rights."
+                      \n "This means no additional resources will be available after the computation is over."
+                      \n "This also means no previously available resources will have been consumed."))
+
+            ($.definition (/.Affine monad permissions value)
+              "A procedure which expands the number of available resources.")
+
+            ($.definition (/.Relevant monad permissions value)
+              "A procedure which reduces the number of available resources.")
+
+            ($.definition /.run!
+              ""
+              ($.example (run! monad procedure)))
+
+            ($.definition /.lifted
+              ""
+              ($.example (lifted monad procedure)))
+
+            ($.definition /.Ordered
+              "The mode of keys which CANNOT be swapped, and for whom order of release/consumption matters.")
+
+            ($.definition /.Commutative
+              "The mode of keys which CAN be swapped, and for whom order of release/consumption DOES NOT matters.")
+
+            ($.definition (/.Key mode key)
+              (format "The access right for a resource."
+                      \n "Without the key for a resource existing somewhere among the available ambient rights, one cannot use a resource."))
+
+            ($.definition (/.Res key value)
+              (format "A resource locked by a key."
+                      \n "The 'key' represents the right to access/consume a resource."))
+
+            (,, (with_template [<name>]
+                  [($.definition <name>
+                     "Makes a value into a resource and adds the key/access-right to it to the ambient keyring for future use.")]
+
+                  [/.ordered]
+                  [/.commutative]
+                  ))
+
+            ($.definition /.read
+              "Access the value of a resource, so long as its key is available."
+              ($.example (read monad resource)))
+
+            ($.definition /.exchange
+              (format "A function that can exchange the keys for resource, so long as they are commutative."
+                      \n "This keys will be placed at the front of the keyring in the order they are specified."
+                      \n "The specific keys must be specified based of their index into the current keyring.")
+              ($.example (do (monad !)
+                           [res|left (commutative ! pre)
+                            res|right (commutative ! post)
+                            _ ((exchange [1 0]) !)
+                            left (read ! res|left)
+                            right (read ! res|right)]
+                           (in (format left right)))))
+
+            (,, (with_template [<name>]
+                  [($.definition <name>
+                     "Group/un-group keys in the keyring into/out-of tuples."
+                     ($.example (do (monad !)
+                                  [res|left (commutative ! pre)
+                                   res|right (commutative ! post)
+                                   _ ((group 2) !)
+                                   _ ((un_group 2) !)
+                                   right (read ! res|right)
+                                   left (read ! res|left)]
+                                  (in (format left right)))))]
+
+                  [/.group]
+                  [/.un_group]
+                  ))
+            )))
diff --git a/stdlib/source/documentation/lux/meta/type/nominal.lux b/stdlib/source/documentation/lux/meta/type/nominal.lux
new file mode 100644
index 000000000..036489d22
--- /dev/null
+++ b/stdlib/source/documentation/lux/meta/type/nominal.lux
@@ -0,0 +1,122 @@
+(.require
+ [library
+  [lux (.except)
+   ["$" documentation]
+   [data
+    ["[0]" text (.only \n)
+     ["%" \\format (.only format)]]]]]
+ [\\library
+  ["[0]" /]])
+
+(`` (def .public documentation
+      (List $.Documentation)
+      (list ($.module /._
+                      "")
+
+            ($.definition /.Frame
+              "Meta-data about an abstract/nominal type in a stack of them.")
+
+            ($.definition /.current
+              "The currently-being-defined abstract/nominal type.")
+
+            ($.definition /.specific
+              "A specific abstract/nominal type still being defined somewhere in the scope."
+              ($.example (specific name)))
+
+            (,, (with_template [<name> <from> <$> <to>]
+                  [($.definition <name>
+                     "Type-casting macro for abstract/nominal types."
+                     ($.example (|> value
+                                    (is <from>)
+                                    <$>
+                                    (is <to>))))]
+
+                  [/.abstraction Representation abstraction Abstraction]
+                  [/.representation Abstraction representation Representation]
+                  ))
+
+            ($.definition /.def
+              (format "Define abstract/nominal types which hide their representation details."
+                      \n "You can convert between the abstraction and its representation selectively to access the value, while hiding it from others.")
+              ($.example (/.def String
+                           Text
+
+                           (.def (string value)
+                             (-> Text String)
+                             (abstraction value))
+
+                           (.def (text value)
+                             (-> String Text)
+                             (representation value))))
+
+              ($.comment "Type-parameters are optional.")
+              ($.example (/.def (Duplicate a)
+                           [a a]
+
+                           (.def (duplicate value)
+                             (All (_ a) (-> a (Duplicate a)))
+                             (abstraction [value value]))))
+
+              ($.comment "Definitions can be nested.")
+              ($.example (/.def (Single a)
+                           a
+
+                           (.def (single value)
+                             (All (_ a) (-> a (Single a)))
+                             (abstraction value))
+
+                           (/.def (Double a)
+                             [a a]
+
+                             (.def (double value)
+                               (All (_ a) (-> a (Double a)))
+                               (abstraction [value value]))
+
+                             (.def (single' value)
+                               (All (_ a) (-> a (Single a)))
+                               (abstraction Single [value value]))
+
+                             (let [value 0123]
+                               (same? value
+                                      (|> value
+                                          single'
+                                          (representation Single)
+                                          double
+                                          representation))))))
+
+              ($.comment "Type-parameters do not necessarily have to be used in the representation type.")
+              ($.comment "If they are not used, they become phantom types and can be used to customize types without changing the representation.")
+              ($.example (/.def (JavaScript a)
+                           Text
+
+                           (/.def Expression Any)
+                           (/.def Statement Any)
+
+                           (.def (+ x y)
+                             (-> (JavaScript Expression) (JavaScript Expression) (JavaScript Expression))
+                             (abstraction
+                              (format "(" (representation x) "+" (representation y) ")")))
+
+                           (.def (while test body)
+                             (-> (JavaScript Expression) (JavaScript Statement) (JavaScript Statement))
+                             (abstraction
+                              (format "while(" (representation test) ") {"
+                                      (representation body)
+                                      "}"))))))
+
+            ($.definition /.transmutation
+              "Transmutes an abstract/nominal type's phantom types."
+              ($.example (/.def (JavaScript a)
+                           Text
+
+                           (/.def Expression Any)
+                           (/.def Statement Any)
+
+                           (.def (statement expression)
+                             (-> (JavaScript Expression) (JavaScript Statement))
+                             (transmutation expression))
+
+                           (.def (statement' expression)
+                             (-> (JavaScript Expression) (JavaScript Statement))
+                             (transmutation JavaScript expression)))))
+            )))
diff --git a/stdlib/source/documentation/lux/meta/type/primitive.lux b/stdlib/source/documentation/lux/meta/type/primitive.lux
deleted file mode 100644
index 036489d22..000000000
--- a/stdlib/source/documentation/lux/meta/type/primitive.lux
+++ /dev/null
@@ -1,122 +0,0 @@
-(.require
- [library
-  [lux (.except)
-   ["$" documentation]
-   [data
-    ["[0]" text (.only \n)
-     ["%" \\format (.only format)]]]]]
- [\\library
-  ["[0]" /]])
-
-(`` (def .public documentation
-      (List $.Documentation)
-      (list ($.module /._
-                      "")
-
-            ($.definition /.Frame
-              "Meta-data about an abstract/nominal type in a stack of them.")
-
-            ($.definition /.current
-              "The currently-being-defined abstract/nominal type.")
-
-            ($.definition /.specific
-              "A specific abstract/nominal type still being defined somewhere in the scope."
-              ($.example (specific name)))
-
-            (,, (with_template [<name> <from> <$> <to>]
-                  [($.definition <name>
-                     "Type-casting macro for abstract/nominal types."
-                     ($.example (|> value
-                                    (is <from>)
-                                    <$>
-                                    (is <to>))))]
-
-                  [/.abstraction Representation abstraction Abstraction]
-                  [/.representation Abstraction representation Representation]
-                  ))
-
-            ($.definition /.def
-              (format "Define abstract/nominal types which hide their representation details."
-                      \n "You can convert between the abstraction and its representation selectively to access the value, while hiding it from others.")
-              ($.example (/.def String
-                           Text
-
-                           (.def (string value)
-                             (-> Text String)
-                             (abstraction value))
-
-                           (.def (text value)
-                             (-> String Text)
-                             (representation value))))
-
-              ($.comment "Type-parameters are optional.")
-              ($.example (/.def (Duplicate a)
-                           [a a]
-
-                           (.def (duplicate value)
-                             (All (_ a) (-> a (Duplicate a)))
-                             (abstraction [value value]))))
-
-              ($.comment "Definitions can be nested.")
-              ($.example (/.def (Single a)
-                           a
-
-                           (.def (single value)
-                             (All (_ a) (-> a (Single a)))
-                             (abstraction value))
-
-                           (/.def (Double a)
-                             [a a]
-
-                             (.def (double value)
-                               (All (_ a) (-> a (Double a)))
-                               (abstraction [value value]))
-
-                             (.def (single' value)
-                               (All (_ a) (-> a (Single a)))
-                               (abstraction Single [value value]))
-
-                             (let [value 0123]
-                               (same? value
-                                      (|> value
-                                          single'
-                                          (representation Single)
-                                          double
-                                          representation))))))
-
-              ($.comment "Type-parameters do not necessarily have to be used in the representation type.")
-              ($.comment "If they are not used, they become phantom types and can be used to customize types without changing the representation.")
-              ($.example (/.def (JavaScript a)
-                           Text
-
-                           (/.def Expression Any)
-                           (/.def Statement Any)
-
-                           (.def (+ x y)
-                             (-> (JavaScript Expression) (JavaScript Expression) (JavaScript Expression))
-                             (abstraction
-                              (format "(" (representation x) "+" (representation y) ")")))
-
-                           (.def (while test body)
-                             (-> (JavaScript Expression) (JavaScript Statement) (JavaScript Statement))
-                             (abstraction
-                              (format "while(" (representation test) ") {"
-                                      (representation body)
-                                      "}"))))))
-
-            ($.definition /.transmutation
-              "Transmutes an abstract/nominal type's phantom types."
-              ($.example (/.def (JavaScript a)
-                           Text
-
-                           (/.def Expression Any)
-                           (/.def Statement Any)
-
-                           (.def (statement expression)
-                             (-> (JavaScript Expression) (JavaScript Statement))
-                             (transmutation expression))
-
-                           (.def (statement' expression)
-                             (-> (JavaScript Expression) (JavaScript Statement))
-                             (transmutation JavaScript expression)))))
-            )))
diff --git a/stdlib/source/documentation/lux/meta/type/resource.lux b/stdlib/source/documentation/lux/meta/type/resource.lux
deleted file mode 100644
index c8e34ab6e..000000000
--- a/stdlib/source/documentation/lux/meta/type/resource.lux
+++ /dev/null
@@ -1,97 +0,0 @@
-(.require
- [library
-  [lux (.except)
-   ["$" documentation]
-   [data
-    ["[0]" text (.only \n)
-     ["%" \\format (.only format)]]]]]
- [\\library
-  ["[0]" /]])
-
-(`` (def .public documentation
-      (List $.Documentation)
-      (list ($.module /._
-                      "")
-
-            ($.definition /.monad)
-            ($.definition /.index_cannot_be_repeated)
-            ($.definition /.amount_cannot_be_zero)
-
-            ($.definition (/.Procedure monad input output value)
-              (format "A computation that takes a sequence of resource access rights as inputs and yields a different sequence as outputs."
-                      \n "A procedure yields a result value."
-                      \n "A procedure can make use of monadic effects."))
-
-            ($.definition (/.Linear monad value)
-              (format "A procedure that is constant with regards to resource access rights."
-                      \n "This means no additional resources will be available after the computation is over."
-                      \n "This also means no previously available resources will have been consumed."))
-
-            ($.definition (/.Affine monad permissions value)
-              "A procedure which expands the number of available resources.")
-
-            ($.definition (/.Relevant monad permissions value)
-              "A procedure which reduces the number of available resources.")
-
-            ($.definition /.run!
-              ""
-              ($.example (run! monad procedure)))
-
-            ($.definition /.lifted
-              ""
-              ($.example (lifted monad procedure)))
-
-            ($.definition /.Ordered
-              "The mode of keys which CANNOT be swapped, and for whom order of release/consumption matters.")
-
-            ($.definition /.Commutative
-              "The mode of keys which CAN be swapped, and for whom order of release/consumption DOES NOT matters.")
-
-            ($.definition (/.Key mode key)
-              (format "The access right for a resource."
-                      \n "Without the key for a resource existing somewhere among the available ambient rights, one cannot use a resource."))
-
-            ($.definition (/.Res key value)
-              (format "A resource locked by a key."
-                      \n "The 'key' represents the right to access/consume a resource."))
-
-            (,, (with_template [<name>]
-                  [($.definition <name>
-                     "Makes a value into a resource and adds the key/access-right to it to the ambient keyring for future use.")]
-
-                  [/.ordered]
-                  [/.commutative]
-                  ))
-
-            ($.definition /.read
-              "Access the value of a resource, so long as its key is available."
-              ($.example (read monad resource)))
-
-            ($.definition /.exchange
-              (format "A function that can exchange the keys for resource, so long as they are commutative."
-                      \n "This keys will be placed at the front of the keyring in the order they are specified."
-                      \n "The specific keys must be specified based of their index into the current keyring.")
-              ($.example (do (monad !)
-                           [res|left (commutative ! pre)
-                            res|right (commutative ! post)
-                            _ ((exchange [1 0]) !)
-                            left (read ! res|left)
-                            right (read ! res|right)]
-                           (in (format left right)))))
-
-            (,, (with_template [<name>]
-                  [($.definition <name>
-                     "Group/un-group keys in the keyring into/out-of tuples."
-                     ($.example (do (monad !)
-                                  [res|left (commutative ! pre)
-                                   res|right (commutative ! post)
-                                   _ ((group 2) !)
-                                   _ ((un_group 2) !)
-                                   right (read ! res|right)
-                                   left (read ! res|left)]
-                                  (in (format left right)))))]
-
-                  [/.group]
-                  [/.un_group]
-                  ))
-            )))
-- 
cgit v1.2.3