updated janet-based docs

src/doc.janet

@@ -0,0 +1,127 @@
+(import /src/base :as base)
+(import /src/prelude :as prelude)
+
+(defn map-values [f dict] 
+ (from-pairs (map (fn [[k v]] [k (f v)]) (pairs dict))))
+
+(def with-docs (map-values base/doc prelude/ctx))
+
+(def sorted-names (-> with-docs keys sort))
+
+(defn escape-underscores [str] (string/replace  "_" "\\_" str))
+
+(defn escape-punctuation [str] (->> str
+ (string/replace "?" "")
+ (string/replace "!" "")))
+
+(defn toc-entry [name] 
+ (def escaped (escape-underscores name)) 
+ (string "[" escaped "](#" (escape-punctuation escaped) ")"))
+
+(def alphabetical-list
+ (string/join (map toc-entry sorted-names) "    "))
+
+(def topics {
+ "math" ["abs" "add" "angle" "atan/2" "between?" "ceil" "cos" "dec" "deg/rad" "deg/turn" "dist" "div" "div/0" "div/safe" "even?" "floor" "gt?" "gte?" "heading/vector" "inc" "inv" "inv/0" "inv/safe" "lt?" "lte?" "max" "min" "mod" "mult" "neg" "neg?" "odd?" "pi" "pos?" "rad/deg" "rad/turn" "random" "random_int" "range" "round" "sin" "square" "sub" "sum_of_squares" "tan" "tau" "turn/deg" "turn/rad" "zero?"]
+ "boolean" ["and" "bool" "bool?" "false?" "not" "or"]
+ "dicts" ["any?" "assoc" "assoc?" "coll?" "count" "dict" "dict?" "diff" "dissoc" "empty?" "get" "keys" "random" "update" "values"]
+ "lists" ["any?" "append" "at" "butlast" "coll?" "concat" "count" "each!" "empty?" "filter" "first" "fold" "join" "keep" "last" "list" "list?" "map" "ordered?""random" "range" "rest" "second" "sentence" "slice"]
+ "sets" ["any?" "append" "coll?" "concat" "count" "empty?" "random" "set" "set?"]
+ "strings" ["any?" "concat" "count" "downcase" "empty?" "join" "sentence" "show" "slice" "split" "string" "string?" "strip" "trim" "upcase" "words"]
+ "types and values" ["assoc?" "bool?" "coll?" "dict?" "eq?" "fn?" "keyword?" "list?" "neq?" "nil?" "number?" "ordered?" "show" "some" "some?" "string?" "type"]
+ "boxes and state" ["unbox" "store!" "update!"]
+ "results" ["err" "err?" "ok" "ok?" "unwrap!" "unwrap_or"]
+ "errors" ["assert!"]
+ "turtle graphics" ["back!" "background!" "bk!" "clear!" "colors" "fd!" "forward!" "goto!" "heading" "heading/vector" "home!" "left!" "lt!" "pc!" "pd!" "pencolor" "pencolor!" "pendown!" "pendown?" "penup!" "penwidth" "penwidth!" "position" "pu!" "pw!" "render_turtle!" "reset_turtle!" "right!" "rt!" "turtle_state"]
+ "environment and i/o" ["doc!" "print!" "report!" "state"]
+ })
+
+(defn capitalize [str]
+ (def fst (slice str 0 1))
+ (def rest (slice str 1))
+ (def init_cap (string/ascii-upper fst))
+ (def lower_rest (string/ascii-lower rest))
+ (string init_cap lower_rest))
+
+(defn topic-entry [topic] 
+ (string "### " (capitalize topic) "\n" 
+  (as-> topic _ (topics _) (slice _) (sort _) (map toc-entry _) 
+   (string/join _ "    "))
+  "\n"))
+
+(def by-topic (let [the-topics (-> topics keys sort)
+                    topics-entries (map topic-entry the-topics)]
+                (string/join topics-entries "\n")))
+
+(defn compose-entry [name]
+ 	(def header (string "### " name "\n"))   	
+ 	(def the-doc (get with-docs name))
+  (when (= "No documentation available." the-doc)
+   (break (string header the-doc "\n")))
+  (def lines (string/split "\n" the-doc))
+	(def description (last lines))
+  (def patterns (string/join (slice lines 1 (-> lines length dec)) "\n"))
+ 	(string header description "\n```\n" patterns "\n```\n"))
+
+(compose-entry "update")
+
+(def entries (string/join (map compose-entry sorted-names) "\n\n"))
+
+(def doc-file (string 
+```
+# Ludus prelude documentation
+These functions are available in every Ludus script.
+The documentation for any function can be found within Ludus by passing the function to `doc!`, 
+e.g., running `doc! (add)` will send the documentation for `add` to the console.
+
+For more information on the syntax & semantics of the Ludus language, see [language.md](./language.md).
+
+## A few notes
+**Naming conventions.** Functions whose name ends with a question mark, e.g., `eq?`, return booleans.
+Functions whose name ends with an exclamation point, e.g., `make!`, change state in some way.
+In other words, they _do things_ rather than _calculating values_. 
+Functions whose name includes a slash either convert from one value to another, e.g. `deg/rad`,
+or they are variations on a function, e.g. `div/0` as a variation on `div`.
+
+**How entries are formatted.** Each entry has a brief (sometimes too brief!) description of what it does.
+It is followed by the patterns for each of its function clauses.
+This should be enough to indicate order of arguments, types, and so on.
+
+**Patterns often, but do not always, indicate types.** Typed patterns are written as `foo as :bar`,
+where the type is indicated by the keyword. 
+Possible ludus types are: `:nil`, `:boolean`, `:number`, `:keyword` (atomic values);
+`:string` (strings are their own beast); `:tuple` and `:list` (indexed collections); `:set` (sets are specific), 
+`:dict` and `:ns` (associative collections); and `:ref` (references).
+
+**Conventional types.** Ludus has two types based on conventions.
+* _Result tuples._ Results are a way of modeling the result of a calculation that might fail.
+The two possible values are `(:ok, value)` and `(:err, msg)`.
+`msg` is usually a string describing what went wrong.
+To work with result tuples, see [`unwrap!`](#unwrap) and [`unwrap_or`](#unwrap_or).
+That said, usually you work with these using pattern matching.
+
+* _Vectors._ Vectors are 2-element tuples of x and y coordinates.
+The origin is `(0, 0)`. 
+Many math functions take vectors as well as numbers, e.g., `add` and `mult`.
+You will see vectors indicated in patterns by an `(x, y)` tuple.
+You can see what this looks like in the last clause of `add`: `((x1, y1), (x2, y2))`.
+
+## Functions by topic
+
+```
+by-topic
+```
+    
+## All functions, alphabetically
+
+```
+alphabetical-list
+```
+
+## Function documentation
+
+```
+entries
+))
+
+(spit "prelude.md" doc-file)