1
0
mirror of https://github.com/janet-lang/janet synced 2025-04-08 00:06:38 +00:00

Fix some documentation and add beginning of a document

generating script.
This commit is contained in:
Calvin Rose 2018-12-15 23:19:28 -05:00
parent a412eecd36
commit 8a5ede21f7
3 changed files with 105 additions and 22 deletions

View File

@ -218,7 +218,7 @@ Shorthand for `(quote x)`
Shorthand for `(splice x)`
### \`x
### ~x
Shorthand for `(quasiquote x)`

62
doc/gendoc.janet Normal file
View File

@ -0,0 +1,62 @@
# Generate documentation
(def- prelude
```
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Janet Language Documentation</title>
<meta name="description" content="API Documentation for the janet programming language.">
</head>
```)
(def- postlude
```
</html>
```)
(def- escapes
{10 "<br>"
09 "&nbsp;&nbsp;&nbsp;&nbsp;"
38 "&amp;"
60 "&lt;"
62 "&gt;"
34 "&quot;"
39 "&#39;"
47 "&#47;"})
(defn- trim-lead
"Trim leading newlines"
[str]
(var i 0)
(while (= 10 str.i) (++ i))
(string/slice str i))
(defn- html-escape
"Escape special characters for HTML encoding."
[str]
(def buf @"")
(loop [byte :in str]
(if-let [rep escapes.byte]
(buffer/push-string buf rep)
(buffer/push-byte buf byte)))
buf)
(defn- gen-one
"Generate documentation for a binding. Returns an
html fragment."
[key docstring]
(if-let [index (string/find "\n" docstring)]
(let [first-line (html-escape (string/slice docstring 0 index))
rest (html-escape (trim-lead (string/slice docstring (inc index))))]
(string "<h2>" first-line "</h2>\n"
"<p>" rest "</p>\n"))
(string "<h2>" (html-escape key) "</h2>\n"
"<p>" (html-escape docstring) "</p>\n")))
(def parts (seq [[k {:doc d :private p}] :in (sort (pairs (table/getproto _env)))
:when (and d (not p))]
(gen-one k d)))
(print prelude ;parts postlude)

View File

@ -84,25 +84,24 @@
(defn neg? "Check if x is less than 0." [x] (< x 0))
(defn one? "Check if x is equal to 1." [x] (== x 1))
(defn integer? "Check if x is an integer." [x] (= (type x) :integer))
(defn real? [x] "Check if x is a real number." (= (type x) :real))
(defn real? "Check if x is a real number." [x] (= (type x) :real))
(defn number? "Check if x is a number." [x]
(def t (type x))
(if (= t :integer) true (= t :real)))
(defn fiber? "Check if x is a fiber." [x] (= (type x) :fiber))
(defn string? "Check if x is a string." [x] (= (type x) :string))
(defn symbol? "Check if x is a symbol." [x] (= (type x) :symbol))
(defn keyword? "Check if x is a keyword style symbol."
[x]
(defn keyword? "Check if x is a keyword style symbol." [x]
(if (not= (type x) :symbol) nil (= 58 x.0)))
(defn buffer? "Check if x is a buffer." [x] (= (type x) :buffer))
(defn function? "Check if x is a function (not a cfunction)."
[x] (= (type x) :function))
(defn function? "Check if x is a function (not a cfunction)." [x]
(= (type x) :function))
(defn cfunction? "Check if x a cfunction." [x] (= (type x) :cfunction))
(defn table? [x] "Check if x a table." (= (type x) :table ))
(defn struct? [x] "Check if x a struct." (= (type x) :struct))
(defn array? [x] "Check if x is an array." (= (type x) :array))
(defn tuple? [x] "Check if x is a tuple." (= (type x) :tuple))
(defn boolean? [x] "Check if x is a boolean." (= (type x) :boolean))
(defn table? "Check if x a table." [x] (= (type x) :table ))
(defn struct? "Check if x a struct." [x] (= (type x) :struct))
(defn array? "Check if x is an array." [x] (= (type x) :array))
(defn tuple? "Check if x is a tuple." [x] (= (type x) :tuple))
(defn boolean? "Check if x is a boolean." [x] (= (type x) :boolean))
(defn bytes? "Check if x is a string, symbol, or buffer." [x]
(def t (type x))
(if (= t :string) true (if (= t :symbol) true (= t :buffer))))
@ -434,12 +433,14 @@
(tuple fiber/new (tuple 'fn '[&] ;body)))
(defn sum
"Returns the sum of xs. If xs is empty, returns 0."
[xs]
(var accum 0)
(loop [x :in xs] (+= accum x))
accum)
(defn product
"Returns the product of xs. If xs is empty, returns 1."
[xs]
(var accum 1)
(loop [x :in xs] (*= accum x))
@ -519,10 +520,23 @@
(if (order v ret) (:= ret v)))
ret))
(defn max [& args] (extreme > args))
(defn min [& args] (extreme < args))
(defn max-order [& args] (extreme order> args))
(defn min-order [& args] (extreme order< args))
(defn max
"Returns the numeric maximum of the arguments."
[& args] (extreme > args))
(defn min
"Returns the numeric minimum of the arguments."
[& args] (extreme < args))
(defn max-order
"Returns the maximum of the arguments according to a total
order over all values."
[& args] (extreme order> args))
(defn min-order
"Returns the minimum of the arguments according to a total
order over all values."
[& args] (extreme order< args))
(defn first
"Get the first element from an indexed data structure."
@ -541,7 +555,7 @@
###
(def sort
"Sort an array in-place. Uses quicksort and is not a stable sort."
"(sort xs [, by])\n\nSort an array in-place. Uses quicksort and is not a stable sort."
(do
(defn partition
@ -567,7 +581,7 @@
(sort-help a (+ piv 1) hi by))
a)
(fn [a by &]
(fn sort [a by &]
(sort-help a 0 (- (length a) 1) (or by order<)))))
(defn sorted
@ -1167,19 +1181,24 @@ value, one key will be ignored."
x))
ret)
(defn all [pred xs]
(defn all
[pred xs]
"Returns true if all xs are truthy, otherwise the first false or nil value."
(var ret true)
(loop [x :in xs :while ret] (:= ret (pred x)))
ret)
(defn some [pred xs]
(defn some
[pred xs]
"Returns false if all xs are false or nil, otherwise returns the first true value."
(var ret nil)
(loop [x :in xs :while (not ret)] (if-let [y (pred x)] (:= ret y)))
ret)
(defn deep-not= [x y]
(defn deep-not=
"Like not=, but mutable types (arrays, tables, buffers) are considered
equal if they have identical structure. Much slower than not=."
[x y]
(def tx (type x))
(or
(not= tx (type y))
@ -1191,9 +1210,10 @@ value, one key will be ignored."
:buffer (not= (string x) (string y))
(not= x y))))
(defn deep= [x y]
(defn deep=
"Like =, but mutable types (arrays, tables, buffers) are considered
equal if they have identical structure. Much slower than =."
[x y]
(not (deep-not= x y)))
(defn macex
@ -1411,7 +1431,8 @@ value, one key will be ignored."
path))
(def require
"Require a module with the given name. Will search all of the paths in
"(require module)\n\n
Require a module with the given name. Will search all of the paths in
module/paths, then the path as a raw file path. Returns the new environment
returned from compiling and running the file."
(do