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 [] ... [{ 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 (_ ) [($.definition (let [[red green blue] (//.rgb ) [_ name] (symbol )] - (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 [] + [($.definition + "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 [] + [($.definition + "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 [ <$> ] + [($.definition + "Type-casting macro for abstract/nominal types." + ($.example (|> value + (is ) + <$> + (is ))))] + + [/.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 [ <$> ] - [($.definition - "Type-casting macro for abstract/nominal types." - ($.example (|> value - (is ) - <$> - (is ))))] - - [/.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 [] - [($.definition - "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 [] - [($.definition - "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