From b60d60ef6c0c70821991991fe716935e73038832 Mon Sep 17 00:00:00 2001 From: Eduardo Julian Date: Wed, 22 Aug 2018 19:42:17 -0400 Subject: No more multi-line text. --- luxc/src/lux/lexer.clj | 39 +- stdlib/source/lux.lux | 769 +++++++++++------------ stdlib/source/lux/concurrency/actor.lux | 4 +- stdlib/source/lux/concurrency/atom.lux | 13 +- stdlib/source/lux/concurrency/stm.lux | 8 +- stdlib/source/lux/control/comonad.lux | 5 +- stdlib/source/lux/control/exception.lux | 5 +- stdlib/source/lux/control/hash.lux | 5 +- stdlib/source/lux/control/monoid.lux | 5 +- stdlib/source/lux/data/bit.lux | 4 +- stdlib/source/lux/data/collection/dictionary.lux | 10 +- stdlib/source/lux/data/collection/list.lux | 10 +- stdlib/source/lux/data/collection/sequence.lux | 13 +- stdlib/source/lux/data/format/json.lux | 5 +- stdlib/source/lux/data/maybe.lux | 13 +- stdlib/source/lux/macro.lux | 20 +- stdlib/source/lux/macro/syntax/common.lux | 5 +- stdlib/source/lux/math/modular.lux | 4 +- stdlib/source/lux/math/random.lux | 10 +- stdlib/source/lux/time/date.lux | 5 +- stdlib/source/lux/time/instant.lux | 5 +- 21 files changed, 458 insertions(+), 499 deletions(-) diff --git a/luxc/src/lux/lexer.clj b/luxc/src/lux/lexer.clj index 9e1414b7f..e81599957 100644 --- a/luxc/src/lux/lexer.clj +++ b/luxc/src/lux/lexer.clj @@ -62,39 +62,24 @@ (recur (+ 1 idx))))) (.toString buffer))))) -(defn- lex-text-body [multi-line? offset] - (|do [[_ eol? ^String pre-quotes**] (&reader/read-regex #"^([^\"]*)") - ^String pre-quotes* (if multi-line? - (|do [:let [empty-line? (and eol? (= "" pre-quotes**))] - _ (&/assert! (or empty-line? - (>= (.length pre-quotes**) offset)) - "Each line of a multi-line text must have an appropriate offset!")] - (return (if empty-line? - "\n" - (str "\n" (.substring pre-quotes** offset))))) - (return pre-quotes**)) +(defn- lex-text-body [_] + (|do [[_ _ ^String pre-quotes*] (&reader/read-regex #"^([^\"]*)") [pre-quotes post-quotes] (if (.endsWith pre-quotes* "\\") - (if eol? - (&/fail-with-loc "[Lexer Error] Cannot leave dangling back-slash \\") - (if (if-let [^String back-slashes (re-find #"\\+$" pre-quotes*)] - (odd? (.length back-slashes))) - (|do [[_ eol?* _] (&reader/read-regex #"^([\"])") - next-part (lex-text-body eol?* offset)] - (return (&/T [(.substring pre-quotes* 0 (dec (.length pre-quotes*))) - (str "\"" next-part)]))) - (|do [post-quotes* (lex-text-body false offset)] - (return (&/T [pre-quotes* post-quotes*]))))) - (if eol? - (|do [next-part (lex-text-body true offset)] - (return (&/T [pre-quotes* - next-part]))) - (return (&/T [pre-quotes* ""]))))] + (if (if-let [^String back-slashes (re-find #"\\+$" pre-quotes*)] + (odd? (.length back-slashes))) + (|do [[_ _ _] (&reader/read-regex #"^([\"])") + next-part (lex-text-body nil)] + (return (&/T [(.substring pre-quotes* 0 (dec (.length pre-quotes*))) + (str "\"" next-part)]))) + (|do [post-quotes* (lex-text-body nil)] + (return (&/T [pre-quotes* post-quotes*])))) + (return (&/T [pre-quotes* ""])))] (return (str (clean-line pre-quotes) post-quotes)))) (def lex-text (|do [[meta _ _] (&reader/read-text "\"") :let [[_ _ _column] meta] - token (lex-text-body false (inc _column)) + token (lex-text-body nil) _ (&reader/read-text "\"")] (return (&/T [meta ($Text token)])))) diff --git a/stdlib/source/lux.lux b/stdlib/source/lux.lux index 1114b069c..1b64aa22b 100644 --- a/stdlib/source/lux.lux +++ b/stdlib/source/lux.lux @@ -19,9 +19,9 @@ (1 [[dummy-cursor (7 ["lux" "export?"])] [dummy-cursor (0 #1)]] (1 [[dummy-cursor (7 ["lux" "doc"])] - [dummy-cursor (5 "The type of things whose type is irrelevant. - - It can be used to write functions or data-structures that can take, or return, anything.")]] + [dummy-cursor (5 ("lux text concat" + "The type of things whose type is irrelevant.\n\n" + "It can be used to write functions or data-structures that can take, or return, anything."))]] (0)))))]) ## (type: Nothing @@ -35,9 +35,9 @@ (1 [[dummy-cursor (7 ["lux" "export?"])] [dummy-cursor (0 #1)]] (1 [[dummy-cursor (7 ["lux" "doc"])] - [dummy-cursor (5 "The type of things whose type is undefined. - - Useful for expressions that cause errors or other \"extraordinary\" conditions.")]] + [dummy-cursor (5 ("lux text concat" + "The type of things whose type is undefined.\n\n" + "Useful for expressions that cause errors or other \"extraordinary\" conditions."))]] (0)))))]) ## (type: (List a) @@ -98,9 +98,9 @@ (#Cons [[dummy-cursor (7 ["lux" "export?"])] [dummy-cursor (0 #1)]] (#Cons [[dummy-cursor (7 ["lux" "doc"])] - [dummy-cursor (5 "Natural numbers (unsigned integers). - - They start at zero (0) and extend in the positive direction.")]] + [dummy-cursor (5 ("lux text concat" + "Natural numbers (unsigned integers).\n\n" + "They start at zero (0) and extend in the positive direction."))]] #Nil))))]) ("lux def" Int @@ -124,9 +124,9 @@ (#Cons [[dummy-cursor (7 ["lux" "export?"])] [dummy-cursor (0 #1)]] (#Cons [[dummy-cursor (7 ["lux" "doc"])] - [dummy-cursor (5 "Fractional numbers that live in the interval [0,1). - - Useful for probability, and other domains that work within that interval.")]] + [dummy-cursor (5 ("lux text concat" + "Fractional numbers that live in the interval [0,1).\n\n" + "Useful for probability, and other domains that work within that interval."))]] #Nil))))]) ("lux def" Frac @@ -162,9 +162,9 @@ (#Cons [[dummy-cursor (7 ["lux" "export?"])] [dummy-cursor (0 #1)]] (#Cons [[dummy-cursor (7 ["lux" "doc"])] - [dummy-cursor (5 "A name. - - It is used as part of Lux syntax to represent identifiers and tags.")]] + [dummy-cursor (5 ("lux text concat" + "A name.\n\n" + "It is used as part of Lux syntax to represent identifiers and tags."))]] #Nil))))]) ## (type: (Maybe a) @@ -747,11 +747,11 @@ (#Cons (text$ "host") #Nil)))))))))))))] (#Cons [(tag$ ["lux" "doc"]) - (text$ "Represents the state of the Lux compiler during a run. - - It is provided to macros during their invocation, so they can access compiler data. - - Caveat emptor: Avoid fiddling with it, unless you know what you're doing.")] + (text$ ("lux text concat" + "Represents the state of the Lux compiler during a run.\n\n" + ("lux text concat" + "It is provided to macros during their invocation, so they can access compiler data.\n\n" + "Caveat emptor: Avoid fiddling with it, unless you know what you're doing.")))] default-def-meta-exported)))) ## (type: (Meta a) @@ -763,9 +763,9 @@ (#Apply (#Product Lux (#Parameter 1)) (#Apply Text Either))))) (record$ (#Cons [(tag$ ["lux" "doc"]) - (text$ "Computations that can have access to the state of the compiler. - - These computations may fail, or modify the state of the compiler.")] + (text$ ("lux text concat" + "Computations that can have access to the state of the compiler.\n\n" + "These computations may fail, or modify the state of the compiler."))] (#Cons [(tag$ ["lux" "type-args"]) (tuple$ (#Cons (text$ "a") #Nil))] default-def-meta-exported)))) @@ -1027,9 +1027,11 @@ (macro:' #export (comment tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## Throws away any code given to it. - ## Great for commenting-out code, while retaining syntax high-lighting and formatting in your text editor. - (comment +1 +2 +3 +4)")] + (text$ ("lux text concat" + "## Throws away any code given to it.\n\n" + ("lux text concat" + "## Great for commenting-out code, while retaining syntax high-lighting and formatting in your text editor.\n\n" + "(comment +1 +2 +3 +4)")))] #Nil) (return #Nil)) @@ -1219,14 +1221,13 @@ (macro:' #export (All tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## Universal quantification. - (All [a] - (-> a a)) - - ## A name can be provided, to specify a recursive type. - (All List [a] - (| Any - [a (List a)]))")] + (text$ ("lux text concat" + "## Universal quantification.\n\n" + ("lux text concat" + "(All [a] (-> a a))\n\n" + ("lux text concat" + "## A name can be provided, to specify a recursive type.\n\n" + "(All List [a] (| Any [a (List a)]))"))))] #Nil) (let'' [self-name tokens] ({(#Cons [_ (#Identifier "" self-name)] tokens) [self-name tokens] @@ -1264,16 +1265,13 @@ (macro:' #export (Ex tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## 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))])")] + (text$ ("lux text concat" + "## Existential quantification.\n\n" + ("lux text concat" + "(Ex [a] [(Codec Text a) a])\n\n" + ("lux text concat" + "## A name can be provided, to specify a recursive type.\n\n" + "(Ex Self [a] [(Codec Text a) a (List (Self a))])"))))] #Nil) (let'' [self-name tokens] ({(#Cons [_ (#Identifier "" self-name)] tokens) [self-name tokens] @@ -1319,10 +1317,11 @@ (macro:' #export (-> tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## Function types: - (-> Int Int Int) - - ## This is the type of a function that takes 2 Ints and returns an Int.")] + (text$ ("lux text concat" + "## Function types:\n\n" + ("lux text concat" + "(-> Int Int Int)\n\n" + "## This is the type of a function that takes 2 Ints and returns an Int.")))] #Nil) ({(#Cons output inputs) (return (#Cons (list/fold ("lux check" (#Function Code (#Function Code Code)) @@ -1337,8 +1336,9 @@ (macro:' #export (list xs) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## List-construction macro. - (list +1 +2 +3)")] + (text$ ("lux text concat" + "## List-construction macro.\n\n" + "(list +1 +2 +3)"))] #Nil) (return (#Cons (list/fold (function'' [head tail] (form$ (#Cons (tag$ ["lux" "Cons"]) @@ -1350,9 +1350,11 @@ (macro:' #export (list& xs) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## List-construction macro, with the last element being a tail-list. - ## In other words, this macro prepends elements to another list. - (list& +1 +2 +3 (list +4 +5 +6))")] + (text$ ("lux text concat" + "## List-construction macro, with the last element being a tail-list.\n\n" + ("lux text concat" + "## In other words, this macro prepends elements to another list.\n\n" + "(list& +1 +2 +3 (list +4 +5 +6))")))] #Nil) ({(#Cons last init) (return (list (list/fold (function'' [head tail] @@ -1367,11 +1369,13 @@ (macro:' #export (& tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## Tuple types: - (& Text Int Bit) - - ## Any. - (&)")] + (text$ ("lux text concat" + "## Tuple types:\n\n" + ("lux text concat" + "(& Text Int Bit)\n\n" + ("lux text concat" + "## Any.\n\n" + "(&)"))))] #Nil) ({#Nil (return (list (identifier$ ["lux" "Any"]))) @@ -1384,11 +1388,13 @@ (macro:' #export (| tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## Variant types: - (| Text Int Bit) - - ## Nothing. - (|)")] + (text$ ("lux text concat" + "## Variant types:\n\n" + ("lux text concat" + "(| Text Int Bit)\n\n" + ("lux text concat" + "## Nothing.\n\n" + "(|)"))))] #Nil) ({#Nil (return (list (identifier$ ["lux" "Nothing"]))) @@ -1563,11 +1569,13 @@ (macro:' #export (_$ tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## Left-association for the application of binary functions over variadic arguments. - (_$ text/compose \"Hello, \" name \".\\nHow are you?\") - - ## => - (text/compose (text/compose \"Hello, \" name) \".\\nHow are you?\")")] + (text$ ("lux text concat" + "## Left-association for the application of binary functions over variadic arguments.\n\n" + ("lux text concat" + "(_$ text/compose \"Hello, \" name \".\\nHow are you?\")\n\n" + ("lux text concat" + "## =>\n\n" + "(text/compose (text/compose \"Hello, \" name) \".\\nHow are you?\")"))))] #Nil) ({(#Cons op tokens') ({(#Cons first nexts) @@ -1583,11 +1591,13 @@ (macro:' #export ($_ tokens) (#Cons [(tag$ ["lux" "doc"]) - (text$ "## Right-association for the application of binary functions over variadic arguments. - ($_ text/compose \"Hello, \" name \".\\nHow are you?\") - - ## => - (text/compose \"Hello, \" (text/compose name \".\\nHow are you?\"))")] + (text$ ("lux text concat" + "## Right-association for the application of binary functions over variadic arguments.\n\n" + ("lux text concat" + "($_ text/compose \"Hello, \" name \".\\nHow are you?\")\n\n" + ("lux text concat" + "## =>\n\n" + "(text/compose \"Hello, \" (text/compose name \".\\nHow are you?\"))"))))] #Nil) ({(#Cons op tokens') ({(#Cons last prevs) @@ -1715,13 +1725,10 @@ (macro:' #export (if tokens) (list [(tag$ ["lux" "doc"]) - (text$ "Picks which expression to evaluate based on a bit test value. - - (if #1 - \"Oh, yeah!\" - \"Aw hell naw!\") - - => \"Oh, yeah!\"")]) + (text$ ($_ "lux text concat" + "Picks which expression to evaluate based on a bit test value." "\n\n" + "(if #1 \"Oh, yeah!\" \"Aw hell naw!\")" "\n\n" + "=> \"Oh, yeah!\""))]) ({(#Cons test (#Cons then (#Cons else #Nil))) (return (list (form$ (list (record$ (list [(bit$ #1) then] [(bit$ #0) else])) @@ -1759,9 +1766,9 @@ (def:''' #export (log! message) (list [(tag$ ["lux" "doc"]) - (text$ "Logs message to standard output. - - Useful for debugging.")]) + (text$ ($_ "lux text concat" + "Logs message to standard output." "\n\n" + "Useful for debugging."))]) (-> Text Any) ("lux io log" message)) @@ -1966,10 +1973,10 @@ (macro:' #export (primitive tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Macro to treat define new primitive types. - (primitive \"java.lang.Object\") - - (primitive \"java.util.List\" [(primitive \"java.lang.Long\")])")]) + (text$ ($_ "lux text concat" + "## Macro to treat define new primitive types." "\n\n" + "(primitive \"java.lang.Object\")" "\n\n" + "(primitive \"java.util.List\" [(primitive \"java.lang.Long\")])"))]) ({(#Cons [_ (#Text class-name)] #Nil) (return (list (form$ (list (tag$ ["lux" "Primitive"]) (text$ class-name) (tag$ ["lux" "Nil"]))))) @@ -1997,11 +2004,10 @@ (macro:' #export (` tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Hygienic quasi-quotation as a macro. Unquote (~) and unquote-splice (~+) must also be used as forms. - ## 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))))")]) + (text$ ($_ "lux text concat" + "## Hygienic quasi-quotation as a macro. Unquote (~) and unquote-splice (~+) must also be used as forms." "\n\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." "\n\n" + "(` (def: (~ name) (function ((~' _) (~+ args)) (~ body))))"))]) ({(#Cons template #Nil) (do Monad [current-module current-module-name @@ -2016,10 +2022,9 @@ (macro:' #export (`' tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Unhygienic quasi-quotation as a macro. Unquote (~) and unquote-splice (~+) must also be used as forms. - (`' (def: (~ name) - (function (_ (~+ args)) - (~ body))))")]) + (text$ ($_ "lux text concat" + "## Unhygienic quasi-quotation as a macro. Unquote (~) and unquote-splice (~+) must also be used as forms." "\n\n" + "(`' (def: (~ name) (function (_ (~+ args)) (~ body))))"))]) ({(#Cons template #Nil) (do Monad [=template (untemplate #1 "" template)] @@ -2031,8 +2036,9 @@ (macro:' #export (' tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Quotation as a macro. - (' \"YOLO\")")]) + (text$ ($_ "lux text concat" + "## Quotation as a macro." "\n\n" + "(' \"YOLO\")"))]) ({(#Cons template #Nil) (do Monad [=template (untemplate #0 "" template)] @@ -2044,13 +2050,11 @@ (macro:' #export (|> tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Piping macro. - (|> elems (list/map int/encode) (interpose \" \") (fold text/compose \"\")) - - ## => - (fold text/compose \"\" - (interpose \" \" - (list/map int/encode elems)))")]) + (text$ ($_ "lux text concat" + "## Piping macro." "\n\n" + "(|> elems (list/map int/encode) (interpose \" \") (fold text/compose \"\"))" "\n\n" + "## =>" "\n\n" + "(fold text/compose \"\" (interpose \" \" (list/map int/encode elems)))"))]) ({(#Cons [init apps]) (return (list (list/fold ("lux check" (-> Code Code Code) (function' [app acc] @@ -2072,13 +2076,11 @@ (macro:' #export (<| tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Reverse piping macro. - (<| (fold text/compose \"\") (interpose \" \") (list/map int/encode) elems) - - ## => - (fold text/compose \"\" - (interpose \" \" - (list/map int/encode elems)))")]) + (text$ ($_ "lux text concat" + "## Reverse piping macro." "\n\n" + "(<| (fold text/compose \"\") (interpose \" \") (list/map int/encode) elems)" "\n\n" + "## =>" "\n\n" + "(fold text/compose \"\" (interpose \" \" (list/map int/encode elems)))"))]) ({(#Cons [init apps]) (return (list (list/fold ("lux check" (-> Code Code Code) (function' [app acc] @@ -2249,14 +2251,12 @@ (macro:' #export (do-template tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## By specifying a pattern (with holes), and the input data to fill those holes, repeats the pattern as many times as necessary. - (do-template [ ] - [(def: #export - (-> Int Int) - (i/+ ))] - - [inc +1] - [dec -1])")]) + (text$ ($_ "lux text concat" + "## By specifying a pattern (with holes), and the input data to fill those holes, repeats the pattern as many times as necessary." "\n\n" + "(do-template [ ]" "\n" + " " "[(def: #export (-> Int Int) (i/+ ))]" "\n\n" + " " "[inc +1]" "\n" + " " "[dec -1]"))]) ({(#Cons [[_ (#Tuple bindings)] (#Cons [[_ (#Tuple templates)] data])]) ({[(#Some bindings') (#Some data')] (let' [apply ("lux check" (-> RepEnv ($' List Code)) @@ -2602,11 +2602,10 @@ (def:''' #export (not x) (list [(tag$ ["lux" "doc"]) - (text$ "## Bit negation. - - (not #1) => #0 - - (not #0) => #1")]) + (text$ ($_ "lux text concat" + "## Bit negation." "\n\n" + "(not #1) => #0" "\n\n" + "(not #0) => #1"))]) (-> Bit Bit) (if x #0 #1)) @@ -2815,8 +2814,9 @@ (macro:' #export (type tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Takes a type expression and returns it's representation as data-structure. - (type (All [a] (Maybe (List a))))")]) + (text$ ($_ "lux text concat" + "## Takes a type expression and returns it's representation as data-structure." "\n\n" + "(type (All [a] (Maybe (List a))))"))]) ({(#Cons type #Nil) (do Monad [type+ (macro-expand-all type)] @@ -2833,8 +2833,9 @@ (macro:' #export (: tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## The type-annotation macro. - (: (List Int) (list +1 +2 +3))")]) + (text$ ($_ "lux text concat" + "## The type-annotation macro." "\n\n" + "(: (List Int) (list +1 +2 +3))"))]) ({(#Cons type (#Cons value #Nil)) (return (list (` ("lux check" (type (~ type)) (~ value))))) @@ -2844,8 +2845,9 @@ (macro:' #export (:coerce tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## The type-coercion macro. - (:coerce Dinosaur (list +1 +2 +3))")]) + (text$ ($_ "lux text concat" + "## The type-coercion macro." "\n\n" + "(:coerce Dinosaur (list +1 +2 +3))"))]) ({(#Cons type (#Cons value #Nil)) (return (list (` ("lux coerce" (type (~ type)) (~ value))))) @@ -2941,10 +2943,10 @@ (macro:' #export (Rec tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Parameter-less recursive types. - ## A name has to be given to the whole type, to use it within its body. - (Rec Self - [Int (List Self)])")]) + (text$ ($_ "lux text concat" + "## Parameter-less recursive types." "\n\n" + "## A name has to be given to the whole type, to use it within its body." "\n\n" + "(Rec Self [Int (List Self)])"))]) ({(#Cons [_ (#Identifier "" name)] (#Cons body #Nil)) (let' [body' (replace-syntax (list [name (` (#.Apply (~ (make-parameter 1)) (~ (make-parameter 0))))]) (update-parameters body))] @@ -2956,12 +2958,13 @@ (macro:' #export (exec tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Sequential execution of expressions (great for side-effects). - (exec - (log! \"#1\") - (log! \"#2\") - (log! \"#3\") - \"YOLO\")")]) + (text$ ($_ "lux text concat" + "## Sequential execution of expressions (great for side-effects)." "\n\n" + "(exec" "\n" + " " "(log! \"#1\")" "\n" + " " "(log! \"#2\")" "\n" + " " "(log! \"#3\")" "\n" + "\"YOLO\")"))]) ({(#Cons value actions) (let' [dummy (identifier$ ["" ""])] (return (list (list/fold ("lux check" (-> Code Code Code) @@ -3113,14 +3116,14 @@ (macro:' #export (case tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## The pattern-matching macro. - ## Allows the usage of macros within the patterns to provide custom syntax. - (case (: (List Int) (list +1 +2 +3)) - (#Cons x (#Cons y (#Cons z #Nil))) - (#Some ($_ i/* x y z)) - - _ - #None)")]) + (text$ ($_ "lux text concat" + "## The pattern-matching macro." "\n" + "## Allows the usage of macros within the patterns to provide custom syntax." "\n" + "(case (: (List Int) (list +1 +2 +3))" "\n" + " " "(#Cons x (#Cons y (#Cons z #Nil)))" "\n" + " " "(#Some ($_ i/* x y z))" "\n\n" + " " "_" "\n" + " " "#None)"))]) ({(#Cons value branches) (do Monad [expansion (expander branches)] @@ -3132,14 +3135,15 @@ (macro:' #export (^ tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Macro-expanding patterns. - ## It's a special macro meant to be used with 'case'. - (case (: (List Int) (list +1 +2 +3)) - (^ (list x y z)) - (#Some ($_ i/* x y z)) - - _ - #None)")]) + (text$ ($_ "lux text concat" + "## Macro-expanding patterns." "\n" + "## It's a special macro meant to be used with 'case'." "\n" + "(case (: (List Int) (list +1 +2 +3))" "\n" + " (^ (list x y z))" "\n" + " (#Some ($_ i/* x y z))" + "\n\n" + " _" "\n" + " #None)"))]) (case tokens (#Cons [_ (#Form (#Cons pattern #Nil))] (#Cons body branches)) (do Monad @@ -3156,25 +3160,19 @@ (macro:' #export (^or tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Or-patterns. - ## It's a special macro meant to be used with 'case'. - (type: Weekday - #Monday - #Tuesday - #Wednesday - #Thursday - #Friday - #Saturday - #Sunday) - - (def: (weekend? day) - (-> Weekday Bit) - (case day - (^or #Saturday #Sunday) - #1 - - _ - #0))")]) + (text$ ($_ "lux text concat" + "## Or-patterns." "\n" + "## It's a special macro meant to be used with 'case'." "\n" + "(type: Weekday #Monday #Tuesday #Wednesday #Thursday #Friday #Saturday #Sunday)" + "\n\n" + "(def: (weekend? day)" "\n" + " (-> Weekday Bit)" "\n" + " (case day" "\n" + " (^or #Saturday #Sunday)" "\n" + " #1" + "\n\n" + " _" "\n" + " #0))"))]) (case tokens (^ (list& [_ (#Form patterns)] body branches)) (case patterns @@ -3200,11 +3198,12 @@ (macro:' #export (let tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Creates local bindings. - ## Can (optionally) use pattern-matching macros when binding. - (let [x (foo bar) - y (baz quux)] - (op x y))")]) + (text$ ($_ "lux text concat" + "## Creates local bindings." "\n" + "## Can (optionally) use pattern-matching macros when binding." "\n" + "(let [x (foo bar)" "\n" + " y (baz quux)]" "\n" + " (op x y))"))]) (case tokens (^ (list [_ (#Tuple bindings)] body)) (if (multiple? 2 (list/size bindings)) @@ -3225,13 +3224,14 @@ (macro:' #export (function tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Syntax for creating functions. - ## Allows for giving the function itself a name, for the sake of recursion. - (: (All [a b] (-> a b a)) - (function (_ x y) x)) - - (: (All [a b] (-> a b a)) - (function (const x y) x))")]) + (text$ ($_ "lux text concat" + "## Syntax for creating functions." "\n" + "## Allows for giving the function itself a name, for the sake of recursion." "\n" + "(: (All [a b] (-> a b a))" "\n" + " (function (_ x y) x))" + "\n\n" + "(: (All [a b] (-> a b a))" "\n" + " (function (const x y) x))"))]) (case (: (Maybe [Text Code (List Code) Code]) (case tokens (^ (list [_ (#Form (list& [_ (#Identifier ["" name])] head tail))] body)) @@ -3343,15 +3343,16 @@ (macro:' #export (def: tokens) (list [(tag$ ["lux" "doc"]) - (text$ "## Defines global constants/functions. - (def: (rejoin-pair pair) - (-> [Code Code] (List Code)) - (let [[left right] pair] - (list left right))) - - (def: branching-exponent - Int - +5)")]) + (text$ ($_ "lux text concat" + "## Defines global constants/functions." "\n" + "(def: (rejoin-pair pair)" "\n" + " (-> [Code Code] (List Code))" "\n" + " (let [[left right] pair]" "\n" + " (list left right)))" + "\n\n" + "(def: branching-exponent" "\n" + " Int" "\n" + " +5)"))]) (let [[export? tokens'] (export^ tokens) parts (: (Maybe [Code (List Code) (Maybe Code) Code (List [Code Code])]) (case tokens' @@ -3427,17 +3428,17 @@ (macro:' #export (macro: tokens) (list [(tag$ ["lux" "doc"]) - (text$ "Macro-definition macro. - - (macro: #export (name-of tokens) - (case tokens - (^template [] - (^ (list [_ ( [prefix name])])) - (return (list (` [(~ (text$ prefix)) (~ (text$ name))])))) - ([#Identifier] [#Tag]) - - _ - (fail \"Wrong syntax for name-of\")))")]) + (text$ ($_ "lux text concat" + "## Macro-definition macro." "\n" + "(macro: #export (name-of tokens)" "\n" + " (case tokens" "\n" + " (^template []" "\n" + " (^ (list [_ ( [prefix name])]))" "\n" + " (return (list (` [(~ (text$ prefix)) (~ (text$ name))]))))" "\n" + " ([#Identifier] [#Tag])" + "\n\n" + " _" "\n" + " (fail \"Wrong syntax for name-of\")))"))]) (let [[exported? tokens] (export^ tokens) name+args+meta+body?? (: (Maybe [Name (List Code) Code Code]) (case tokens @@ -3474,18 +3475,19 @@ (fail "Wrong syntax for macro:")))) (macro: #export (signature: tokens) - {#.doc "## Definition of signatures ala ML. - (signature: #export (Ord a) - (: (Equivalence a) - eq) - (: (-> a a Bit) - <) - (: (-> a a Bit) - <=) - (: (-> a a Bit) - >) - (: (-> a a Bit) - >=))"} + {#.doc (text$ ($_ "lux text concat" + "## Definition of signatures ala ML." "\n" + "(signature: #export (Ord a)" "\n" + " (: (Equivalence a)" "\n" + " eq)" "\n" + " (: (-> a a Bit)" "\n" + " <)" "\n" + " (: (-> a a Bit)" "\n" + " <=)" "\n" + " (: (-> a a Bit)" "\n" + " >)" "\n" + " (: (-> a a Bit)" "\n" + " >=))"))} (let [[exported? tokens'] (export^ tokens) ?parts (: (Maybe [Name (List Code) Code (List Code)]) (case tokens' @@ -3600,17 +3602,20 @@ ("lux text clip" text from to)) (def: #export (error! message) - {#.doc "## Causes an error, with the given error message. - (error! \"OH NO!\")"} + {#.doc (text$ ($_ "lux text concat" + "## Causes an error, with the given error message." "\n" + "(error! \"OH NO!\")"))} (-> Text Nothing) ("lux io error" message)) (macro: (default tokens state) - {#.doc "## Allows you to provide a default value that will be used - ## if a (Maybe x) value turns out to be #.None. - (default +20 (#.Some +10)) => +10 - - (default +20 #.None) => +20"} + {#.doc (text$ ($_ "lux text concat" + "## Allows you to provide a default value that will be used" "\n" + "## if a (Maybe x) value turns out to be #.None." + "\n\n" + "(default +20 (#.Some +10)) ## => +10" + "\n\n" + "(default +20 #.None) ## => +20"))} (case tokens (^ (list else maybe)) (let [g!temp (: Code [dummy-cursor (#Identifier ["" ""])]) @@ -3883,19 +3888,20 @@ (|> parts list/reverse (list/fold text/compose ""))) (macro: #export (structure: tokens) - {#.doc "## Definition of structures ala ML. - (structure: #export Ord (Ord Int) - (def: eq Equivalence) - (def: (< test subject) - (lux.< test subject)) - (def: (<= test subject) - (or (lux.< test subject) - (lux.= test subject))) - (def: (lux.> test subject) - (lux.> test subject)) - (def: (lux.>= test subject) - (or (lux.> test subject) - (lux.= test subject))))"} + {#.doc (text$ ($_ "lux text concat" + "## Definition of structures ala ML." "\n" + "(structure: #export Ord (Ord Int)" "\n" + " (def: eq Equivalence)" "\n" + " (def: (< test subject)" "\n" + " (lux.i/< test subject))" "\n" + " (def: (<= test subject)" "\n" + " (or (lux.i/< test subject)" "\n" + " (lux.i/= test subject)))" "\n" + " (def: (> test subject)" "\n" + " (lux.i/> test subject))" "\n" + " (def: (>= test subject)" "\n" + " (or (lux.i/> test subject)" "\n" + " (lux.i/= test subject))))"))} (let [[exported? tokens'] (export^ tokens) ?parts (: (Maybe [Code (List Code) Code Code (List Code)]) (case tokens' @@ -3961,17 +3967,14 @@ (fail "Wrong syntax for structure:")))) (def: #export (id x) - {#.doc "Identity function. - - Does nothing to it's argument and just returns it."} + {#.doc "Identity function. Does nothing to it's argument and just returns it."} (All [a] (-> a a)) x) (macro: #export (type: tokens) - {#.doc "## The type-definition macro. - (type: (List a) - #Nil - (#Cons a (List a)))"} + {#.doc (text$ ($_ "lux text concat" + "## The type-definition macro." "\n" + "(type: (List a) #Nil (#Cons a (List a)))"))} (let [[exported? tokens'] (export^ tokens) [rec? tokens'] (case tokens' (#Cons [_ (#Tag [_ "rec"])] tokens') @@ -4202,7 +4205,7 @@ 0 prefix _ ($_ text/compose prefix "/" clean))] (return output)) - (fail ($_ text/compose + (fail ($_ "lux text concat" "Cannot climb the module hierarchy...\n" "Importing module: " module "\n" " Relative Root: " relative-root "\n")))))) @@ -4488,11 +4491,12 @@ )) (macro: #export (^open tokens) - {#.doc "## Same as the \"open\" macro, but meant to be used as a pattern-matching macro for generating local bindings. - ## Takes an \"alias\" text for the generated local bindings. - (def: #export (range (^open \".\") from to) - (All [a] (-> (Enum a) a a (List a))) - (range' <= succ from to))"} + {#.doc (text$ ($_ "lux text concat" + "## 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." "\n" + "(def: #export (range (^open \".\") from to)" "\n" + " (All [a] (-> (Enum a) a a (List a)))" "\n" + " (range' <= succ from to))"))} (case tokens (^ (list& [_ (#Form (list [_ (#Text alias)]))] body branches)) (do Monad @@ -4538,11 +4542,13 @@ (fail "Wrong syntax for ^open"))) (macro: #export (cond tokens) - {#.doc "## Branching structures with multiple test conditions. - (cond (n/even? num) \"even\" - (n/odd? num) \"odd\" - ## else-branch - \"???\")"} + {#.doc (text$ ($_ "lux text concat" + "## Branching structures with multiple test conditions." "\n" + "(cond (n/even? num) \"even\"" "\n" + " (n/odd? num) \"odd\"" + "\n\n" + " ## else-branch" "\n" + " \"???\")"))} (if (n/= 0 (n/% 2 (list/size tokens))) (fail "cond requires an uneven number of arguments.") (case (list/reverse tokens) @@ -4571,16 +4577,16 @@ (enumerate' 0 xs)) (macro: #export (get@ tokens) - {#.doc "## Accesses the value of a record at a given tag. - (get@ #field my-record) - - ## Can also work with multiple levels of nesting: - (get@ [#foo #bar #baz] my-record) - - ## And, if only the slot/path is given, generates an - ## accessor function: - (let [getter (get@ [#foo #bar #baz])] - (getter my-record))"} + {#.doc (text$ ($_ "lux text concat" + "## Accesses the value of a record at a given tag." "\n" + "(get@ #field my-record)" + "\n\n" + "## Can also work with multiple levels of nesting:" "\n" + "(get@ [#foo #bar #baz] my-record)" + "\n\n" + "## And, if only the slot/path is given, generates an accessor function:" "\n" + "(let [getter (get@ [#foo #bar #baz])]" "\n" + " (getter my-record))"))} (case tokens (^ (list [_ (#Tag slot')] record)) (do Monad @@ -4639,14 +4645,17 @@ [(~ cursor-code) (#.Record #Nil)]))))))) (macro: #export (open: tokens) - {#.doc "## Opens a structure and generates a definition for each of its members (including nested members). - ## For example: - (open: \"i:.\" Number) - ## Will generate: - (def: i:+ (:: Number +)) - (def: i:- (:: Number -)) - (def: i:* (:: Number *)) - ..."} + {#.doc (text$ ($_ "lux text concat" + "## Opens a structure and generates a definition for each of its members (including nested members)." + "\n\n" + "## For example:" "\n" + "(open: \"i:.\" Number)" + "\n\n" + "## Will generate:" "\n" + "(def: i:+ (:: Number +))" "\n" + "(def: i:- (:: Number -))" "\n" + "(def: i:* (:: Number *))" "\n" + "..."))} (case tokens (^ (list [_ (#Text alias)] struct)) (case struct @@ -4678,26 +4687,22 @@ (fail "Wrong syntax for open:"))) (macro: #export (|>> tokens) - {#.doc "## Similar to the piping macro, but rather than taking an initial object to work on, creates a function for taking it. - (|>> (list/map int/encode) (interpose \" \") (fold text/compose \"\")) - ## => - (function (_ ) - (fold text/compose \"\" - (interpose \" \" - (list/map int/encode ))))"} + {#.doc (text$ ($_ "lux text concat" + "## Similar to the piping macro, but rather than taking an initial object to work on, creates a function for taking it." "\n" + "(|>> (list/map int/encode) (interpose \" \") (fold text/compose \"\"))" "\n" + "## =>" "\n" + "(function (_ ) (fold text/compose \"\" (interpose \" \" (list/map int/encode ))))"))} (do Monad [g!_ (gensym "_") g!arg (gensym "arg")] (return (list (` (function ((~ g!_) (~ g!arg)) (|> (~ g!arg) (~+ tokens)))))))) (macro: #export (<<| tokens) - {#.doc "## Similar to the piping macro, but rather than taking an initial object to work on, creates a function for taking it. - (<<| (fold text/compose \"\") (interpose \" \") (list/map int/encode)) - ## => - (function (_ ) - (fold text/compose \"\" - (interpose \" \" - (list/map int/encode ))))"} + {#.doc (text$ ($_ "lux text concat" + "## Similar to the piping macro, but rather than taking an initial object to work on, creates a function for taking it." "\n" + "(<<| (fold text/compose \"\") (interpose \" \") (list/map int/encode))" "\n" + "## =>" "\n" + "(function (_ ) (fold text/compose \"\" (interpose \" \" (list/map int/encode ))))"))} (do Monad [g!_ (gensym "_") g!arg (gensym "arg")] @@ -4821,26 +4826,23 @@ (~+ openings))))) (macro: #export (module: tokens) - {#.doc "Module-definition macro. - - Can take optional annotations and allows the specification of modules to import. - - ## Examples - (.module: {#.doc \"Some documentation...\"} - [lux #* - [control - [\"M\" monad #*]] - [data - maybe - [\".\" name (\"name/.\" Codec)] - [\".\" text (\"text/.\" Monoid)] - [collection - [list (\"list/.\" Monad)]]] - meta - [macro - code]] - [// - [type (\".\" Equivalence)]])"} + {#.doc (text$ ($_ "lux text concat" + "## Module-definition macro." + "\n\n" + "## Can take optional annotations and allows the specification of modules to import." + "\n\n" + "## Example" "\n" + "(.module: {#.doc \"Some documentation...\"}" "\n" + " [lux #*" "\n" + " [control" "\n" + " [\"M\" monad #*]]" "\n" + " [data" "\n" + " maybe" "\n" + " [\".\" name (\"name/.\" Codec)]]" "\n" + " [macro" "\n" + " code]]" "\n" + " [//" "\n" + " [type (\".\" Equivalence)]])"))} (do Monad [#let [[_meta _imports] (: [(List [Code Code]) (List Code)] (case tokens @@ -4866,11 +4868,12 @@ (wrap (#Cons =module =refers)))) (macro: #export (:: tokens) - {#.doc "## Allows accessing the value of a structure's member. - (:: Codec encode) - - ## Also allows using that value as a function. - (:: Codec encode +123)"} + {#.doc (text$ ($_ "lux text concat" + "## Allows accessing the value of a structure's member." "\n" + "(:: Codec encode)" + "\n\n" + "## Also allows using that value as a function." "\n" + "(:: Codec encode +123)"))} (case tokens (^ (list struct [_ (#Identifier member)])) (return (list (` (let [(^open ".") (~ struct)] (~ (identifier$ member)))))) @@ -4882,19 +4885,16 @@ (fail "Wrong syntax for ::"))) (macro: #export (set@ tokens) - {#.doc "## Sets the value of a record at a given tag. - (set@ #name \"Lux\" lang) - - ## Can also work with multiple levels of nesting: - (set@ [#foo #bar #baz] value my-record) - - ## And, if only the slot/path and (optionally) the value are given, generates a - ## mutator function: - (let [setter (set@ [#foo #bar #baz] value)] - (setter my-record)) - - (let [setter (set@ [#foo #bar #baz])] - (setter value my-record))"} + {#.doc (text$ ($_ "lux text concat" + "## Sets the value of a record at a given tag." "\n" + "(set@ #name \"Lux\" lang)" + "\n\n" + "## Can also work with multiple levels of nesting:" "\n" + "(set@ [#foo #bar #baz] value my-record)" + "\n\n" + "## And, if only the slot/path and (optionally) the value are given, generates a mutator function:" "\n" + "(let [setter (set@ [#foo #bar #baz] value)] (setter my-record))" "\n" + "(let [setter (set@ [#foo #bar #baz])] (setter value my-record))"))} (case tokens (^ (list [_ (#Tag slot')] value record)) (do Monad @@ -4972,19 +4972,16 @@ (fail "Wrong syntax for set@"))) (macro: #export (update@ tokens) - {#.doc "## Modifies the value of a record at a given tag, based on some function. - (update@ #age inc person) - - ## Can also work with multiple levels of nesting: - (update@ [#foo #bar #baz] func my-record) - - ## And, if only the slot/path and (optionally) the value are given, generates a - ## mutator function: - (let [updater (update@ [#foo #bar #baz] func)] - (updater my-record)) - - (let [updater (update@ [#foo #bar #baz])] - (updater func my-record))"} + {#.doc (text$ ($_ "lux text concat" + "## Modifies the value of a record at a given tag, based on some function." "\n" + "(update@ #age inc person)" + "\n\n" + "## Can also work with multiple levels of nesting:" "\n" + "(update@ [#foo #bar #baz] func my-record)" + "\n\n" + "## And, if only the slot/path and (optionally) the value are given, generates a mutator function:" "\n" + "(let [updater (update@ [#foo #bar #baz] func)] (updater my-record))" "\n" + "(let [updater (update@ [#foo #bar #baz])] (updater func my-record))"))} (case tokens (^ (list [_ (#Tag slot')] fun record)) (do Monad @@ -5048,41 +5045,40 @@ (fail "Wrong syntax for update@"))) (macro: #export (^template tokens) - {#.doc "## It's similar to do-template, but meant to be used during pattern-matching. - (def: (beta-reduce env type) - (-> (List Type) Type Type) - (case type - (#.Primitive name params) - (#.Primitive name (list/map (beta-reduce env) params)) - - (^template [] - ( left right) - ( (beta-reduce env left) (beta-reduce env right))) - ([#.Sum] [#.Product]) - - (^template [] - ( left right) - ( (beta-reduce env left) (beta-reduce env right))) - ([#.Function] - [#.Apply]) - - (^template [] - ( old-env def) - (case old-env - #.Nil - ( env def) - - _ - type)) - ([#.UnivQ] - [#.ExQ]) - - (#.Parameter idx) - (default type (list.nth idx env)) - - _ - type - ))"} + {#.doc (text$ ($_ "lux text concat" + "## It's similar to do-template, but meant to be used during pattern-matching." "\n" + "(def: (beta-reduce env type)" "\n" + " (-> (List Type) Type Type)" "\n" + " (case type" "\n" + " (#.Primitive name params)" "\n" + " (#.Primitive name (list/map (beta-reduce env) params))" + "\n\n" + " (^template []" "\n" + " ( left right)" "\n" + " ( (beta-reduce env left) (beta-reduce env right)))" "\n" + " ([#.Sum] [#.Product])" + "\n\n" + " (^template []" "\n" + " ( left right)" "\n" + " ( (beta-reduce env left) (beta-reduce env right)))" "\n" + " ([#.Function] [#.Apply])" + "\n\n" + " (^template []" "\n" + " ( old-env def)" "\n" + " (case old-env" "\n" + " #.Nil" "\n" + " ( env def)" + "\n\n" + " _" "\n" + " type))" "\n" + " ([#.UnivQ] [#.ExQ])" + "\n\n" + " (#.Parameter idx)" "\n" + " (default type (list.nth idx env))" + "\n\n" + " _" "\n" + " type" "\n" + " ))"))} (case tokens (^ (list& [_ (#Form (list& [_ (#Tuple bindings)] templates))] [_ (#Form data)] @@ -5282,16 +5278,17 @@ (text/compose text "\n\n")))) (macro: #export (doc tokens) - {#.doc "## Creates code documentation, embedding text as comments and properly formatting the forms it's being given. - - ## For Example: - (doc \"Allows arbitrary looping, using the \\\"recur\\\" form to re-start the loop. - Can be used in monadic code to create monadic loops.\" - (loop [count +0 - x init] - (if (< +10 count) - (recur (inc count) (f x)) - x)))"} + {#.doc (text$ ($_ "lux text concat" + "## Creates code documentation, embedding text as comments and properly formatting the forms it's being given." + "\n\n" + "## For Example:" "\n" + "(doc \"Allows arbitrary looping, using the \\\"recur\\\" form to re-start the loop.\"" "\n" + " \"Can be used in monadic code to create monadic loops.\"" "\n" + " (loop [count +0" "\n" + " x init]" "\n" + " (if (< +10 count)" "\n" + " (recur (inc count) (f x))" "\n" + " x)))"))} (return (list (` [(~ cursor-code) (#.Text (~ (|> tokens (list/map (|>> identify-doc-fragment doc-fragment->Text)) diff --git a/stdlib/source/lux/concurrency/actor.lux b/stdlib/source/lux/concurrency/actor.lux index a9154877e..0af0d09f9 100644 --- a/stdlib/source/lux/concurrency/actor.lux +++ b/stdlib/source/lux/concurrency/actor.lux @@ -140,8 +140,8 @@ #end default-end}) (def: #export (poison actor) - {#.doc "Kills the actor by sending a message that will kill it upon processing, - but allows the actor to handle previous messages."} + {#.doc (doc "Kills the actor by sending a message that will kill it upon processing," + "but allows the actor to handle previous messages.")} (All [s] (-> (Actor s) (IO Bit))) (send (function (_ state self) (task.throw poisoned [])) diff --git a/stdlib/source/lux/concurrency/atom.lux b/stdlib/source/lux/concurrency/atom.lux index b0c016a12..c04930171 100644 --- a/stdlib/source/lux/concurrency/atom.lux +++ b/stdlib/source/lux/concurrency/atom.lux @@ -33,19 +33,16 @@ (AtomicReference::get [] (:representation atom))}))) (def: #export (compare-and-swap current new atom) - {#.doc "Only mutates an atom if you can present it's current value. - - That guarantees that atom was not updated since you last read from it."} + {#.doc (doc "Only mutates an atom if you can present it's current value." + "That guarantees that atom was not updated since you last read from it.")} (All [a] (-> a a (Atom a) (IO Bit))) (io (AtomicReference::compareAndSet [current new] (:representation atom)))) )) (def: #export (update f atom) - {#.doc "Updates an atom by applying a function to its current value. - - If it fails to update it (because some other process wrote to it first), it will retry until it succeeds. - - The retries will be done with the new values of the atom, as they show up."} + {#.doc (doc "Updates an atom by applying a function to its current value." + "If it fails to update it (because some other process wrote to it first), it will retry until it succeeds." + "The retries will be done with the new values of the atom, as they show up.")} (All [a] (-> (-> a a) (Atom a) (IO a))) (loop [_ []] (do io.Monad diff --git a/stdlib/source/lux/concurrency/stm.lux b/stdlib/source/lux/concurrency/stm.lux index d736baf2e..3c6691acc 100644 --- a/stdlib/source/lux/concurrency/stm.lux +++ b/stdlib/source/lux/concurrency/stm.lux @@ -232,11 +232,9 @@ ))) (def: #export (commit stm-proc) - {#.doc "Commits a transaction and returns its result (asynchronously). - - Note that a transaction may be re-run an indeterminate number of times if other transactions involving the same variables successfully commit first. - - For this reason, it's important to note that transactions must be free from side-effects, such as I/O."} + {#.doc (doc "Commits a transaction and returns its result (asynchronously)." + "Note that a transaction may be re-run an indeterminate number of times if other transactions involving the same variables successfully commit first." + "For this reason, it's important to note that transactions must be free from side-effects, such as I/O.")} (All [a] (-> (STM a) (Promise a))) (let [output (promise #.None)] (exec (io.run init-processor!) diff --git a/stdlib/source/lux/control/comonad.lux b/stdlib/source/lux/control/comonad.lux index 23a059ae4..76fe954e5 100644 --- a/stdlib/source/lux/control/comonad.lux +++ b/stdlib/source/lux/control/comonad.lux @@ -8,9 +8,8 @@ ## [Signatures] (signature: #export (CoMonad w) - {#.doc "CoMonads are the opposite/complement to monads. - - CoMonadic structures are often infinite in size and built upon lazily-evaluated functions."} + {#.doc (doc "CoMonads are the opposite/complement to monads." + "CoMonadic structures are often infinite in size and built upon lazily-evaluated functions.")} (: (F.Functor w) functor) (: (All [a] diff --git a/stdlib/source/lux/control/exception.lux b/stdlib/source/lux/control/exception.lux index d2e9c705d..085269e54 100644 --- a/stdlib/source/lux/control/exception.lux +++ b/stdlib/source/lux/control/exception.lux @@ -31,9 +31,8 @@ (text.starts-with? (get@ #label exception) error)) (def: #export (catch exception then try) - {#.doc "If a particular exception is detected on a possibly-erroneous value, handle it. - - If no exception was detected, or a different one from the one being checked, then pass along the original value."} + {#.doc (doc "If a particular exception is detected on a possibly-erroneous value, handle it." + "If no exception was detected, or a different one from the one being checked, then pass along the original value.")} (All [e a] (-> (Exception e) (-> Text a) (Error a) (Error a))) diff --git a/stdlib/source/lux/control/hash.lux b/stdlib/source/lux/control/hash.lux index aa668c7c7..4e50c3658 100644 --- a/stdlib/source/lux/control/hash.lux +++ b/stdlib/source/lux/control/hash.lux @@ -4,9 +4,8 @@ ## [Signatures] (signature: #export (Hash a) - {#.doc "A way to produce hash-codes for a type's instances. - - A necessity when working with some data-structures, such as dictionaries or sets."} + {#.doc (doc "A way to produce hash-codes for a type's instances." + "A necessity when working with some data-structures, such as dictionaries or sets.")} (: (Equivalence a) eq) (: (-> a Nat) diff --git a/stdlib/source/lux/control/monoid.lux b/stdlib/source/lux/control/monoid.lux index 4976830b6..7d89043a8 100644 --- a/stdlib/source/lux/control/monoid.lux +++ b/stdlib/source/lux/control/monoid.lux @@ -3,9 +3,8 @@ [// [fold (#+ Fold)]]) (signature: #export (Monoid a) - {#.doc "A way to compose values. - - Includes an identity value which does not alter any other value when combined with."} + {#.doc (doc "A way to compose values." + "Includes an identity value which does not alter any other value when combined with.")} (: a identity) (: (-> a a a) diff --git a/stdlib/source/lux/data/bit.lux b/stdlib/source/lux/data/bit.lux index 026f8bcab..8cf671429 100644 --- a/stdlib/source/lux/data/bit.lux +++ b/stdlib/source/lux/data/bit.lux @@ -45,7 +45,7 @@ ## [Values] (def: #export complement - {#.doc "Generates the complement of a predicate. - That is a predicate that returns the oposite of the original predicate."} + {#.doc (doc "Generates the complement of a predicate." + "That is a predicate that returns the oposite of the original predicate.")} (All [a] (-> (-> a Bit) (-> a Bit))) (compose not)) diff --git a/stdlib/source/lux/data/collection/dictionary.lux b/stdlib/source/lux/data/collection/dictionary.lux index e61d657a5..503ea312d 100644 --- a/stdlib/source/lux/data/collection/dictionary.lux +++ b/stdlib/source/lux/data/collection/dictionary.lux @@ -623,18 +623,16 @@ ) (def: #export (merge dict2 dict1) - {#.doc "Merges 2 dictionaries. - - If any collisions with keys occur, the values of dict2 will overwrite those of dict1."} + {#.doc (doc "Merges 2 dictionaries." + "If any collisions with keys occur, the values of dict2 will overwrite those of dict1.")} (All [k v] (-> (Dictionary k v) (Dictionary k v) (Dictionary k v))) (list/fold (function (_ [key val] dict) (put key val dict)) dict1 (entries dict2))) (def: #export (merge-with f dict2 dict1) - {#.doc "Merges 2 dictionaries. - - If any collisions with keys occur, a new value will be computed by applying 'f' to the values of dict2 and dict1."} + {#.doc (doc "Merges 2 dictionaries." + "If any collisions with keys occur, a new value will be computed by applying 'f' to the values of dict2 and dict1.")} (All [k v] (-> (-> v v v) (Dictionary k v) (Dictionary k v) (Dictionary k v))) (list/fold (function (_ [key val2] dict) (case (get key dict) diff --git a/stdlib/source/lux/data/collection/list.lux b/stdlib/source/lux/data/collection/list.lux index d11f0a080..ef1ebf5ac 100644 --- a/stdlib/source/lux/data/collection/list.lux +++ b/stdlib/source/lux/data/collection/list.lux @@ -53,9 +53,8 @@ [(filter p xs) (filter (complement p) xs)]) (def: #export (as-pairs xs) - {#.doc "Cut the list into pairs of 2. - - Caveat emptor: If the list has an uneven number of elements, the last one will be skipped."} + {#.doc (doc "Cut the list into pairs of 2." + "Caveat emptor: If the list has an uneven number of elements, the last one will be skipped.")} (All [a] (-> (List a) (List [a a]))) (case xs (^ (#.Cons [x1 (#.Cons [x2 xs'])])) @@ -517,9 +516,8 @@ (last xs'))) (def: #export (inits xs) - {#.doc "For a list of size N, returns the first N-1 elements. - - Empty lists will result in a #.None value being returned instead."} + {#.doc (doc "For a list of size N, returns the first N-1 elements." + "Empty lists will result in a #.None value being returned instead.")} (All [a] (-> (List a) (Maybe (List a)))) (case xs #.Nil diff --git a/stdlib/source/lux/data/collection/sequence.lux b/stdlib/source/lux/data/collection/sequence.lux index 6529a1ced..06209f4d6 100644 --- a/stdlib/source/lux/data/collection/sequence.lux +++ b/stdlib/source/lux/data/collection/sequence.lux @@ -41,9 +41,8 @@ (pending [x (repeat x)])) (def: #export (cycle xs) - {#.doc "Go over the elements of a list forever. - - The list should not be empty."} + {#.doc (doc "Go over the elements of a list forever." + "The list should not be empty.")} (All [a] (-> (List a) (Maybe (Sequence a)))) (case xs @@ -111,11 +110,9 @@ (filter p xs')))) (def: #export (partition p xs) - {#.doc "Split a sequence in two based on a predicate. - - The left side contains all entries for which the predicate is #1. - - The right side contains all entries for which the predicate is #0."} + {#.doc (doc "Split a sequence in two based on a predicate." + "The left side contains all entries for which the predicate is #1." + "The right side contains all entries for which the predicate is #0.")} (All [a] (-> (-> a Bit) (Sequence a) [(Sequence a) (Sequence a)])) [(filter p xs) (filter (complement p) xs)]) diff --git a/stdlib/source/lux/data/format/json.lux b/stdlib/source/lux/data/format/json.lux index 3594ef28c..c26df1893 100644 --- a/stdlib/source/lux/data/format/json.lux +++ b/stdlib/source/lux/data/format/json.lux @@ -1,6 +1,5 @@ -(.module: {#.doc "Functionality for reading and writing values in the JSON format. - - For more information, please see: http://www.json.org/"} +(.module: {#.doc (.doc "Functionality for reading and writing values in the JSON format." + "For more information, please see: http://www.json.org/")} [lux #* [control ["." monad (#+ do Monad)] diff --git a/stdlib/source/lux/data/maybe.lux b/stdlib/source/lux/data/maybe.lux index 57ff95727..d0dfe1886 100644 --- a/stdlib/source/lux/data/maybe.lux +++ b/stdlib/source/lux/data/maybe.lux @@ -82,11 +82,14 @@ (monad.lift Monad (:: Monad wrap))) (macro: #export (default tokens state) - {#.doc "## Allows you to provide a default value that will be used - ## if a (Maybe x) value turns out to be #.None. - (default +20 (#.Some +10)) => +10 - - (default +20 #.None) => +20"} + {#.doc (doc "Allows you to provide a default value that will be used" + "if a (Maybe x) value turns out to be #.None." + (default +20 (#.Some +10)) + "=>" + +10 + (default +20 #.None) + "=>" + +20)} (case tokens (^ (list else maybe)) (let [g!temp (: Code [dummy-cursor (#.Identifier ["" ""])]) diff --git a/stdlib/source/lux/macro.lux b/stdlib/source/lux/macro.lux index 7564518f4..88299a812 100644 --- a/stdlib/source/lux/macro.lux +++ b/stdlib/source/lux/macro.lux @@ -264,9 +264,8 @@ #.None)))) (def: #export (normalize name) - {#.doc "If given a name without a module prefix, gives it the current module's name as prefix. - - Otherwise, returns the name as-is."} + {#.doc (doc "If given a name without a module prefix, gives it the current module's name as prefix." + "Otherwise, returns the name as-is.")} (-> Name (Meta Name)) (case name ["" name] @@ -287,9 +286,8 @@ (#e.Success [compiler (find-macro' (get@ #.modules compiler) this-module module name)]))))) (def: #export (expand-once syntax) - {#.doc "Given code that requires applying a macro, does it once and returns the result. - - Otherwise, returns the code as-is."} + {#.doc (doc "Given code that requires applying a macro, does it once and returns the result." + "Otherwise, returns the code as-is.")} (-> Code (Meta (List Code))) (case syntax [_ (#.Form (#.Cons [[_ (#.Identifier name)] args]))] @@ -306,9 +304,8 @@ (:: Monad wrap (list syntax)))) (def: #export (expand syntax) - {#.doc "Given code that requires applying a macro, expands repeatedly until no more direct macro-calls are left. - - Otherwise, returns the code as-is."} + {#.doc (doc "Given code that requires applying a macro, expands repeatedly until no more direct macro-calls are left." + "Otherwise, returns the code as-is.")} (-> Code (Meta (List Code))) (case syntax [_ (#.Form (#.Cons [[_ (#.Identifier name)] args]))] @@ -367,9 +364,8 @@ (get@ #.seed compiler)]))) (def: #export (gensym prefix) - {#.doc "Generates a unique name as an Code node (ready to be used in code templates). - - A prefix can be given (or just be empty text \"\") to better identify the code for debugging purposes."} + {#.doc (doc "Generates a unique name as an Code node (ready to be used in code templates)." + "A prefix can be given (or just be empty text \"\") to better identify the code for debugging purposes.")} (-> Text (Meta Code)) (function (_ compiler) (#e.Success [(update@ #.seed inc compiler) diff --git a/stdlib/source/lux/macro/syntax/common.lux b/stdlib/source/lux/macro/syntax/common.lux index dc38d1409..0729c05fe 100644 --- a/stdlib/source/lux/macro/syntax/common.lux +++ b/stdlib/source/lux/macro/syntax/common.lux @@ -1,6 +1,5 @@ -(.module: {#.doc "Commons syntax readers and writers. - - The goal is to be able to reuse common syntax in macro definitions across libraries."} +(.module: {#.doc (.doc "Commons syntax readers and writers." + "The goal is to be able to reuse common syntax in macro definitions across libraries.")} [lux (#- Definition)]) (type: #export Declaration diff --git a/stdlib/source/lux/math/modular.lux b/stdlib/source/lux/math/modular.lux index ef0f36bb2..883febecb 100644 --- a/stdlib/source/lux/math/modular.lux +++ b/stdlib/source/lux/math/modular.lux @@ -19,8 +19,8 @@ (exception: #export zero-cannot-be-a-modulus) (abstract: #export (Modulus m) - {#.doc "A number used as a modulus in modular arithmetic. - It cannot be 0."} + {#.doc (doc "A number used as a modulus in modular arithmetic." + "It cannot be 0.")} Int diff --git a/stdlib/source/lux/math/random.lux b/stdlib/source/lux/math/random.lux index 92eced24d..ffb7bc592 100644 --- a/stdlib/source/lux/math/random.lux +++ b/stdlib/source/lux/math/random.lux @@ -268,9 +268,8 @@ (def: pcg-32-magic-mult Nat 6364136223846793005) (def: #export (pcg-32 [inc seed]) - {#.doc "An implementation of the PCG32 algorithm. - - For more information, please see: http://www.pcg-random.org/"} + {#.doc (doc "An implementation of the PCG32 algorithm." + "For more information, please see: http://www.pcg-random.org/")} (-> [(I64 Any) (I64 Any)] PRNG) (function (_ _) [(|> seed .nat (n/* pcg-32-magic-mult) ("lux i64 +" inc) [inc] pcg-32) @@ -283,9 +282,8 @@ .i64))])) (def: #export (xoroshiro-128+ [s0 s1]) - {#.doc "An implementation of the Xoroshiro128+ algorithm. - - For more information, please see: http://xoroshiro.di.unimi.it/"} + {#.doc (doc "An implementation of the Xoroshiro128+ algorithm." + "For more information, please see: http://xoroshiro.di.unimi.it/")} (-> [(I64 Any) (I64 Any)] PRNG) (function (_ _) [(let [s01 (i64.xor s0 s1)] diff --git a/stdlib/source/lux/time/date.lux b/stdlib/source/lux/time/date.lux index b902b631f..0e8f5468a 100644 --- a/stdlib/source/lux/time/date.lux +++ b/stdlib/source/lux/time/date.lux @@ -318,9 +318,8 @@ (l.run input lex-date)) (structure: #export _ - {#.doc "Based on ISO 8601. - - For example: 2017-01-15"} + {#.doc (doc "Based on ISO 8601." + "For example: 2017-01-15")} (Codec Text Date) (def: encode encode) (def: decode decode)) diff --git a/stdlib/source/lux/time/instant.lux b/stdlib/source/lux/time/instant.lux index 64d4fe172..70890ce4b 100644 --- a/stdlib/source/lux/time/instant.lux +++ b/stdlib/source/lux/time/instant.lux @@ -304,9 +304,8 @@ (l.run input lex-instant)) ## (structure: #export _ -## {#.doc "Based on ISO 8601. - -## For example: 2017-01-15T21:14:51.827Z"} +## {#.doc (doc "Based on ISO 8601." +## "For example: 2017-01-15T21:14:51.827Z")} ## (Codec Text Instant) ## (def: encode encode) ## (def: decode decode)) -- cgit v1.2.3