From cc5f798e1ab7e636d38a6f85c30c146ca7963b07 Mon Sep 17 00:00:00 2001 From: Eduardo Julian Date: Mon, 2 Jan 2017 23:48:40 -0400 Subject: - Updated documentation for lux/cli, lux/compiler, lux/codata/*. --- stdlib/source/lux.lux | 4 +- stdlib/source/lux/cli.lux | 3 + stdlib/source/lux/codata/cont.lux | 1 + stdlib/source/lux/codata/env.lux | 5 +- stdlib/source/lux/codata/function.lux | 6 +- stdlib/source/lux/codata/io.lux | 13 +++-- stdlib/source/lux/codata/state.lux | 11 +++- stdlib/source/lux/codata/struct/stream.lux | 12 ++++ stdlib/source/lux/compiler.lux | 94 +++++++++++++++++++++--------- 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) + {#;doc "Monad transformer for Env."} (All [M] (-> (Monad M) (All [e] (Monad (All [a] (Env e (M a))))))) (def: applicative (compA Applicative (get@ #M;applicative Monad))) (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 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) + {#;doc "A monad transformer to create composite stateful computations."} (All [M s] (-> (Monad M) (Monad (State' M s)))) (def: applicative (Applicative Monad)) (def: (join sMsMa) @@ -114,7 +122,8 @@ (sMa state'))))) (def: #export (lift-state Monad 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 [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 [ ] - [(def: #export ( tag meta) + [(def: #export ( tag anns) (-> Ident Anns (Maybe )) - (case (get-ann tag meta) + (case (get-ann tag anns) (#;Some ( 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 [ ] +(do-template [ ] [(def: #export + {#;doc (#;TextM ($_ Text/append "Checks whether a definition is " "."))} (-> Anns Bool) (flag-set? (ident-for )))] - [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 [ ] @@ -217,17 +224,18 @@ [try-mtext #;TextM Text] ) -(do-template [ ] - [(def: #export ( meta) +(do-template [ ] + [(def: #export ( anns) + {#;doc (#;TextM ($_ Text/append "Looks up the arguments of a " "."))} (-> Anns (List Text)) (default (list) (do Monad - [_args (get-ann (ident-for ) meta) + [_args (get-ann (ident-for ) 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 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 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 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 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 [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 [[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 [#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 [[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 [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 [#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 [(^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 - [=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 [=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 [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]))) -- cgit v1.2.3