aboutsummaryrefslogtreecommitdiff
path: root/stdlib/source
diff options
context:
space:
mode:
Diffstat (limited to 'stdlib/source')
-rw-r--r--stdlib/source/lux.lux4
-rw-r--r--stdlib/source/lux/cli.lux3
-rw-r--r--stdlib/source/lux/codata/cont.lux1
-rw-r--r--stdlib/source/lux/codata/env.lux5
-rw-r--r--stdlib/source/lux/codata/function.lux6
-rw-r--r--stdlib/source/lux/codata/io.lux13
-rw-r--r--stdlib/source/lux/codata/state.lux11
-rw-r--r--stdlib/source/lux/codata/struct/stream.lux12
-rw-r--r--stdlib/source/lux/compiler.lux94
9 files changed, 110 insertions, 39 deletions
diff --git a/stdlib/source/lux.lux b/stdlib/source/lux.lux
index ac1289395..4ff962e0f 100644
--- a/stdlib/source/lux.lux
+++ b/stdlib/source/lux.lux
@@ -3485,10 +3485,10 @@
(let [[exported? tokens'] (export-level^ tokens)
?parts (: (Maybe [AST (List AST) AST AST (List AST)])
(case tokens'
- (^ (list& [_ (#FormS (list& name args))] type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs))
+ (^ (list& [_ (#FormS (list& name args))] [meta-rec-cursor (#;RecordS meta-rec-parts)] type defs))
(#Some name args type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs)
- (^ (list& name type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs))
+ (^ (list& name [meta-rec-cursor (#;RecordS meta-rec-parts)] type defs))
(#Some name #Nil type [meta-rec-cursor (#;RecordS meta-rec-parts)] defs)
(^ (list& [_ (#FormS (list& name args))] type defs))
diff --git a/stdlib/source/lux/cli.lux b/stdlib/source/lux/cli.lux
index 73c78a7a6..a8604180b 100644
--- a/stdlib/source/lux/cli.lux
+++ b/stdlib/source/lux/cli.lux
@@ -19,6 +19,7 @@
## [Types]
(type: #export (CLI a)
+ {#;doc "A command-line interface parser."}
(-> (List Text) (Error [(List Text) a])))
## [Utils]
@@ -126,6 +127,7 @@
_ (#;Left (Text/append "Unknown parameters: " (text;join-with " " inputs))))))
(def: #export (assert message test)
+ {#;doc "Fails with the given message if the test is false."}
(-> Text Bool (CLI Unit))
(lambda [inputs]
(if test
@@ -166,6 +168,7 @@
(#;Right [inputs' (sum;left l)]))))
(def: #export (not opt)
+ {#;doc "The opposite of the given CLI."}
(All [a] (-> (CLI a) (CLI Unit)))
(lambda [inputs]
(case (opt inputs)
diff --git a/stdlib/source/lux/codata/cont.lux b/stdlib/source/lux/codata/cont.lux
index a75e5a029..7f1b787e1 100644
--- a/stdlib/source/lux/codata/cont.lux
+++ b/stdlib/source/lux/codata/cont.lux
@@ -14,6 +14,7 @@
## [Types]
(type: #export (Cont a)
+ {#;doc "Delimited continuations."}
(All [b]
(-> (-> a b) b)))
diff --git a/stdlib/source/lux/codata/env.lux b/stdlib/source/lux/codata/env.lux
index 818dd8a7e..18e07e84c 100644
--- a/stdlib/source/lux/codata/env.lux
+++ b/stdlib/source/lux/codata/env.lux
@@ -11,6 +11,7 @@
## [Types]
(type: #export (Env r a)
+ {#;doc "Computations that have access to some environmental value."}
(-> r a))
## [Structures]
@@ -38,7 +39,7 @@
## [Values]
(def: #export ask
- {#;doc "Get the value of the environment."}
+ {#;doc "Get the environment."}
(All [r] (Env r r))
(lambda [env] env))
@@ -52,6 +53,7 @@
(env-proc env))
(struct: #export (EnvT Monad<M>)
+ {#;doc "Monad transformer for Env."}
(All [M] (-> (Monad M) (All [e] (Monad (All [a] (Env e (M a)))))))
(def: applicative (compA Applicative<Env> (get@ #M;applicative Monad<M>)))
(def: (join eMeMa)
@@ -61,5 +63,6 @@
(run env eMa)))))
(def: #export lift-env
+ {#;doc "Lift monadic values to the Env wrapper."}
(All [M e a] (-> (M a) (Env e (M a))))
(:: Monad<Env> wrap))
diff --git a/stdlib/source/lux/codata/function.lux b/stdlib/source/lux/codata/function.lux
index fba5528a8..4f13be813 100644
--- a/stdlib/source/lux/codata/function.lux
+++ b/stdlib/source/lux/codata/function.lux
@@ -8,11 +8,13 @@
(lux (control monoid)))
## [Functions]
-(def: #export (const x y)
+(def: #export (const c)
+ {#;doc "Create constant functions."}
(All [a b] (-> a (-> b a)))
- x)
+ (lambda [_] c))
(def: #export (flip f)
+ {#;doc "Flips the order of the arguments of a function."}
(All [a b c]
(-> (-> a b c) (-> b a c)))
(lambda [x y] (f y x)))
diff --git a/stdlib/source/lux/codata/io.lux b/stdlib/source/lux/codata/io.lux
index 1398dfae5..e612c24c9 100644
--- a/stdlib/source/lux/codata/io.lux
+++ b/stdlib/source/lux/codata/io.lux
@@ -12,16 +12,16 @@
## [Types]
(type: #export (IO a)
+ {#;doc "A type that represents synchronous, effectful computations that may interact with the outside world."}
(-> Void a))
## [Syntax]
(macro: #export (io tokens state)
- {#;doc (doc
- "Delays the evaluation of an expression, by wrapping it in an IO 'thunk'."
- "Great for wrapping side-effecting computations (which won't be performed until the IO is \"run\")."
- (io (exec
- (log! msg)
- "Some value...")))}
+ {#;doc (doc "Delays the evaluation of an expression, by wrapping it in an IO 'thunk'."
+ "Great for wrapping effectful computations (which won't be performed until the IO is \"run\")."
+ (io (exec
+ (log! msg)
+ "Some value...")))}
(case tokens
(^ (list value))
(let [blank (: AST [["" -1 -1] (#;SymbolS ["" ""])])]
@@ -52,5 +52,6 @@
## [Functions]
(def: #export (run action)
+ {#;doc "A way to execute IO computations and perform their side-effects."}
(All [a] (-> (IO a) a))
(action (:! Void [])))
diff --git a/stdlib/source/lux/codata/state.lux b/stdlib/source/lux/codata/state.lux
index 2ff0ea3a8..e0eebda56 100644
--- a/stdlib/source/lux/codata/state.lux
+++ b/stdlib/source/lux/codata/state.lux
@@ -11,6 +11,7 @@
## [Types]
(type: #export (State s a)
+ {#;doc "Stateful computations."}
(-> s [s a]))
## [Structures]
@@ -43,16 +44,19 @@
## [Values]
(def: #export get
+ {#;doc "Read the current state."}
(All [s] (State s s))
(lambda [state]
[state state]))
(def: #export (put new-state)
+ {#;doc "Set the new state."}
(All [s] (-> s (State s Unit)))
(lambda [state]
[new-state []]))
(def: #export (update change)
+ {#;doc "Compute the new state."}
(All [s] (-> (-> s s) (State s Unit)))
(lambda [state]
[(change state) []]))
@@ -71,6 +75,7 @@
[state output])))
(def: #export (run state action)
+ {#;doc "Run a stateful computation."}
(All [s a] (-> s (State s a) [s a]))
(action state))
@@ -98,13 +103,16 @@
(wrap [state (f a)])))))
(type: #export (State' M s a)
+ {#;doc "Stateful computations decorated by a monad."}
(-> s (M [s a])))
(def: #export (run' state action)
+ {#;doc "Run a stateful computation decorated by a monad."}
(All [M s a] (-> s (State' M s a) (M [s a])))
(action state))
(struct: #export (StateT Monad<M>)
+ {#;doc "A monad transformer to create composite stateful computations."}
(All [M s] (-> (Monad M) (Monad (State' M s))))
(def: applicative (Applicative<StateT> Monad<M>))
(def: (join sMsMa)
@@ -114,7 +122,8 @@
(sMa state')))))
(def: #export (lift-state Monad<M> ma)
- (All [M s a] (-> (Monad M) (M a) (-> s (M [s a]))))
+ {#;doc "Lift monadic values to the State' wrapper."}
+ (All [M s a] (-> (Monad M) (M a) (State' M s a)))
(lambda [state]
(do Monad<M>
[a ma]
diff --git a/stdlib/source/lux/codata/struct/stream.lux b/stdlib/source/lux/codata/struct/stream.lux
index 6eb0ed4a9..5691b0c69 100644
--- a/stdlib/source/lux/codata/struct/stream.lux
+++ b/stdlib/source/lux/codata/struct/stream.lux
@@ -16,6 +16,7 @@
## [Types]
(type: #export (Stream a)
+ {#;doc "An infinite stream of lazily-evaluated values."}
(Cont [a (Stream a)]))
## [Utils]
@@ -28,16 +29,21 @@
## [Functions]
(def: #export (iterate f x)
+ {#;doc "Create a stream by applying a function to a value, and to its result, on and on..."}
(All [a]
(-> (-> a a) a (Stream a)))
(@lazy [x (iterate f (f x))]))
(def: #export (repeat x)
+ {#;doc "Repeat a value forever."}
(All [a]
(-> a (Stream a)))
(@lazy [x (repeat x)]))
(def: #export (cycle xs)
+ {#;doc "Go over the elements of a list forever.
+
+ The list shouldn't be empty."}
(All [a]
(-> (List a) (Maybe (Stream a))))
(case xs
@@ -91,6 +97,7 @@
)
(def: #export (unfold step init)
+ {#;doc "A stateful way of infinitely calculating the values of a stream."}
(All [a b]
(-> (-> a [a b]) a (Stream b)))
(let [[next x] (step init)]
@@ -104,6 +111,11 @@
(filter p xs'))))
(def: #export (partition p xs)
+ {#;doc "Split a stream in two based on a predicate.
+
+ The left side contains all entries for which the predicate is true.
+
+ The right side contains all entries for which the predicate is false."}
(All [a] (-> (-> a Bool) (Stream a) [(Stream a) (Stream a)]))
[(filter p xs) (filter (complement p) xs)])
diff --git a/stdlib/source/lux/compiler.lux b/stdlib/source/lux/compiler.lux
index feade4a8c..2f3fdbe3c 100644
--- a/stdlib/source/lux/compiler.lux
+++ b/stdlib/source/lux/compiler.lux
@@ -89,6 +89,7 @@
(#;Right output)))
(def: #export (either left right)
+ {#;doc "Pick whichever computation succeeds."}
(All [a] (-> (Lux a) (Lux a) (Lux a)))
(lambda [compiler]
(case (left compiler)
@@ -99,6 +100,7 @@
(#;Right [compiler' output]))))
(def: #export (assert message test)
+ {#;doc "Fails with the given message if the test is false."}
(-> Text Bool (Lux Unit))
(lambda [compiler]
(if test
@@ -106,6 +108,7 @@
(#;Left message))))
(def: #export (fail msg)
+ {#;doc "Fails with the given message."}
(All [a]
(-> Text (Lux a)))
(lambda [_]
@@ -143,23 +146,24 @@
[this-module-name current-module-name]
(find-module this-module-name)))
-(def: #export (get-ann tag meta)
+(def: #export (get-ann tag anns)
+ {#;doc "Looks-up a particular annotation's value within the set of annotations."}
(-> Ident Anns (Maybe Ann-Value))
(let [[p n] tag]
- (case meta
- (#;Cons [[p' n'] dmv] meta')
+ (case anns
+ (#;Cons [[p' n'] dmv] anns')
(if (and (Text/= p p')
(Text/= n n'))
(#;Some dmv)
- (get-ann tag meta'))
+ (get-ann tag anns'))
#;Nil
#;None)))
(do-template [<name> <tag> <type>]
- [(def: #export (<name> tag meta)
+ [(def: #export (<name> tag anns)
(-> Ident Anns (Maybe <type>))
- (case (get-ann tag meta)
+ (case (get-ann tag anns)
(#;Some (<tag> value))
(#;Some value)
@@ -176,31 +180,34 @@
[get-dict-ann #;DictM (List [Text Ann-Value])]
)
-(def: #export (get-doc meta)
+(def: #export (get-doc anns)
+ {#;doc "Looks-up a definition's documentation."}
(-> Anns (Maybe Text))
- (get-text-ann ["lux" "doc"] meta))
+ (get-text-ann ["lux" "doc"] anns))
-(def: #export (flag-set? flag-name meta)
+(def: #export (flag-set? flag-name anns)
+ {#;doc "Finds out whether an annotation-as-a-flag is set (has value 'true')."}
(-> Ident Anns Bool)
- (case (get-ann flag-name meta)
+ (case (get-ann flag-name anns)
(#;Some (#;BoolM true))
true
_
false))
-(do-template [<name> <tag>]
+(do-template [<name> <tag> <desc>]
[(def: #export <name>
+ {#;doc (#;TextM ($_ Text/append "Checks whether a definition is " <desc> "."))}
(-> Anns Bool)
(flag-set? (ident-for <tag>)))]
- [export? #;export?]
- [hidden? #;hidden?]
- [macro? #;macro?]
- [type? #;type?]
- [struct? #;struct?]
- [type-rec? #;type-rec?]
- [sig? #;sig?]
+ [export? #;export? "exported"]
+ [hidden? #;hidden? "hidden"]
+ [macro? #;macro? "a macro"]
+ [type? #;type? "a type"]
+ [struct? #;struct? "a structure"]
+ [type-rec? #;type-rec? "a recursive type"]
+ [sig? #;sig? "a signature"]
)
(do-template [<name> <tag> <type>]
@@ -217,17 +224,18 @@
[try-mtext #;TextM Text]
)
-(do-template [<name> <tag>]
- [(def: #export (<name> meta)
+(do-template [<name> <tag> <desc>]
+ [(def: #export (<name> anns)
+ {#;doc (#;TextM ($_ Text/append "Looks up the arguments of a " <desc> "."))}
(-> Anns (List Text))
(default (list)
(do Monad<Maybe>
- [_args (get-ann (ident-for <tag>) meta)
+ [_args (get-ann (ident-for <tag>) anns)
args (try-mlist _args)]
(mapM @ try-mtext args))))]
- [func-args #;func-args]
- [type-args #;type-args]
+ [func-args #;func-args "function"]
+ [type-args #;type-args "parameterized type"]
)
(def: (find-macro' modules this-module module name)
@@ -256,6 +264,9 @@
(#;Right [state (find-macro' (get@ #;modules state) this-module module name)]))))))
(def: #export (normalize ident)
+ {#;doc "If given an identifier without a module prefix, gives it the current module's name as prefix.
+
+ Otherwise, returns the identifier as-is."}
(-> Ident (Lux Ident))
(case ident
["" name]
@@ -267,6 +278,9 @@
(:: Monad<Lux> wrap ident)))
(def: #export (macro-expand-once syntax)
+ {#;doc "Given code that requires applying a macro, does it once and returns the result.
+
+ Otherwise, returns the code as-is."}
(-> AST (Lux (List AST)))
(case syntax
[_ (#;FormS (#;Cons [[_ (#;SymbolS macro-name)] args]))]
@@ -284,6 +298,9 @@
(:: Monad<Lux> wrap (list syntax))))
(def: #export (macro-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."}
(-> AST (Lux (List AST)))
(case syntax
[_ (#;FormS (#;Cons [[_ (#;SymbolS macro-name)] args]))]
@@ -304,6 +321,7 @@
(:: Monad<Lux> wrap (list syntax))))
(def: #export (macro-expand-all syntax)
+ {#;doc "Expands all macro-calls everywhere recursively, until only primitive/base code remains."}
(-> AST (Lux (List AST)))
(case syntax
[_ (#;FormS (#;Cons [[_ (#;SymbolS macro-name)] args]))]
@@ -337,6 +355,9 @@
(:: Monad<Lux> wrap (list syntax))))
(def: #export (gensym prefix)
+ {#;doc "Generates a unique identifier as an AST 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 (Lux AST))
(lambda [state]
(#;Right [(update@ #;seed n.inc state)
@@ -376,6 +397,7 @@
(fail "Wrong syntax for with-gensyms")))
(def: #export (macro-expand-1 token)
+ {#;doc "Works just like macro-expand, except that it ensures that the output is a single AST token."}
(-> AST (Lux AST))
(do Monad<Lux>
[token+ (macro-expand token)]
@@ -404,6 +426,7 @@
(#;Some y) (#;Some y)))
(def: #export (find-var-type name)
+ {#;doc "Looks-up the type of a local variable somewhere in the environment."}
(-> Text (Lux Type))
(lambda [state]
(let [test (: (-> [Text Analysis] Bool)
@@ -424,6 +447,7 @@
(#;Left ($_ Text/append "Unknown variable: " name))))))
(def: #export (find-def name)
+ {#;doc "Looks-up a definition's whole data in the available modules (including the current one)."}
(-> Ident (Lux Def))
(lambda [state]
(case (: (Maybe Def)
@@ -431,19 +455,21 @@
[#let [[v-prefix v-name] name]
(^slots [#;defs]) (get v-prefix (get@ #;modules state))]
(get v-name defs)))
- (#;Some _meta)
- (#;Right [state _meta])
+ (#;Some _anns)
+ (#;Right [state _anns])
_
(#;Left ($_ Text/append "Unknown definition: " (Ident/encode name))))))
(def: #export (find-def-type name)
+ {#;doc "Looks-up a definition's type in the available modules (including the current one)."}
(-> Ident (Lux Type))
(do Monad<Lux>
[[def-type def-data def-value] (find-def name)]
(wrap def-type)))
(def: #export (find-type name)
+ {#;doc "Looks-up the type of either a local variable or a definition."}
(-> Ident (Lux Type))
(do Monad<Lux>
[#let [[_ _name] name]]
@@ -453,12 +479,14 @@
(find-def-type name)))))
(def: #export (find-type-def name)
+ {#;doc "Finds the value of a type definition (such as Int, Top or Compiler)."}
(-> Ident (Lux Type))
(do Monad<Lux>
[[def-type def-data def-value] (find-def name)]
(wrap (:! Type def-value))))
(def: #export (defs module-name)
+ {#;doc "The entire list of definitions in a module (including the unexported/private ones)."}
(-> Text (Lux (List [Text Def])))
(lambda [state]
(case (get module-name (get@ #;modules state))
@@ -467,6 +495,7 @@
)))
(def: #export (exports module-name)
+ {#;doc "All the exported definitions in a module."}
(-> Text (Lux (List [Text Def])))
(do Monad<Lux>
[defs (defs module-name)]
@@ -476,6 +505,7 @@
defs))))
(def: #export modules
+ {#;doc "All the available modules (including the current one)."}
(Lux (List Text))
(lambda [state]
(|> state
@@ -485,6 +515,7 @@
#;Right)))
(def: #export (tags-of type-name)
+ {#;doc "All the tags associated with a type definition."}
(-> Ident (Lux (List Ident)))
(do Monad<Lux>
[#let [[module name] type-name]
@@ -497,11 +528,13 @@
(wrap (list)))))
(def: #export cursor
+ {#;doc "The cursor of the current expression being analyzed."}
(Lux Cursor)
(lambda [state]
(#;Right [state (get@ #;cursor state)])))
(def: #export expected-type
+ {#;doc "The expected type of the current expression being analyzed."}
(Lux Type)
(lambda [state]
(case (get@ #;expected state)
@@ -512,15 +545,18 @@
(#;Left "Not expecting any type."))))
(def: #export (imported-modules module-name)
+ {#;doc "All the modules imported by a specified module."}
(-> Text (Lux (List Text)))
(do Monad<Lux>
[(^slots [#;imports]) (find-module module-name)]
(wrap imports)))
-(def: #export (resolve-tag (^@ tag [module name]))
+(def: #export (resolve-tag tag)
+ {#;doc "Given a tag, finds out what is its index, its related tag-list and it's associated type."}
(-> Ident (Lux [Nat (List Ident) Type]))
(do Monad<Lux>
- [=module (find-module module)
+ [#let [[module name] tag]
+ =module (find-module module)
this-module-name current-module-name]
(case (get name (get@ #;tags =module))
(#;Some [idx tag-list exported? type])
@@ -533,6 +569,7 @@
(fail ($_ Text/append "Unknown tag: " (Ident/encode tag))))))
(def: #export (tag-lists module)
+ {#;doc "All the tag-lists defined in a module, with their associated types."}
(-> Text (Lux (List [(List Ident) Type])))
(do Monad<Lux>
[=module (find-module module)
@@ -545,6 +582,7 @@
[tag-list type]))))))
(def: #export locals
+ {#;doc "All the local variables currently in scope, separated in different scopes."}
(Lux (List (List [Text Type])))
(lambda [state]
(case (list;inits (get@ #;scopes state))
@@ -559,6 +597,7 @@
scopes)]))))
(def: #export (un-alias def-name)
+ {#;doc "Given an aliased definition's name, returns the original definition being referenced."}
(-> Ident (Lux Ident))
(do Monad<Lux>
[def-name (normalize def-name)
@@ -571,6 +610,7 @@
(wrap def-name))))
(def: #export get-compiler
+ {#;doc "Obtains the current state of the compiler."}
(Lux Compiler)
(lambda [compiler]
(#;Right [compiler compiler])))
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-23 12:33:51 +0000