ref: ad400bef13cb9703064590465eca4413b253b2c9
parent: ec4d8b26ab214f3b601db96d7effd78ea5da89c8
author: Sigrid Solveig Haflínudóttir <sigrid@ftrv.se>
date: Wed Mar 19 02:55:46 EDT 2025
docs styling
--- a/boot/sl.boot
+++ b/boot/sl.boot
@@ -23,7 +23,7 @@
(name (:type vec) (:named T) (:constructor T) (:conc-name NIL) (:predicate NIL) . slots)) eof-object? ((term)) help ((term)) __finish ((status)) rand-u32 (NIL) = ((a . rest)
(num…)) rand-u64 (NIL) buffer (NIL) compare ((x y)) num? ((v)) /= ((a . rest)) fn? ((v)) add-exit-hook ((fun)) lz-pack ((data
(level 0))) rand-float (NIL) *prompt* (NIL) builtin? ((v)) cons? ((value)) vm-stats (NIL) * ((num…)) putprop ((symbol
- key val)) getprop ((symbol key (def NIL))) aref ((seq subscript…)) io->str ((io))) *doc* #table(io->str "Return an in-memory `io` buffer converted to a string." bound? "Return `T` if `symbol` has a value associated with it, `NIL` otherwise." io-eof? "Return `T` if `io` is currently in the \"end of file\" state, `NIL`\notherwise." sym "Convert terms to a symbol.\n\nThis is equivalent to `(sym (str terms…))`." nan? "Return `T` if `v` is a floating point representation of NaN, either\nnegative or positive, `NIL` otherwise." for "Call the function `fn` with a single integer argument, starting from\n`min` and ending with `max`.\n\nExamples:\n\n(for 0 2 (λ (i) (print (- 2 i)))) → 210" fixnum? "Return `T` if `v` is of a fixnum type, `NIL` otherwise." exit "Terminate the process with the specified status. Does not return." > "Return `T` if the arguments are in strictly decreasing order (previous\none is greater than the next one)." + "Return sum of the numbers or `0` with no arguments." __finish "A function called right before exit by the VM." lz-unpack "Return decompressed data previously compressed using lz-pack.\n\nEither destination for the decompressed data or the expected size of\nthe decompressed data must be specified. In the latter case a new\narray is allocated." defstruct "Defines a structure type with a specific name and slots.\n\nThe default underlying type is a \"named\" vector (`:type vec`),\nwhere the first element is the name of the structure's type, the\nrest are the slot values. If the name as the first element isn't\nrequired, `:named NIL` should be used. A list can be used instead\nof a vector by adding `:type list` option.\n\nAn example of a default constructor signature, based on structure\ndefinition:\n\n (defstruct blah a b c) →\n (make-blah (:a NIL) (:b NIL) (:c NIL))\n\nIt can be customized in several ways. For example:\n\n ; disable the constructor altogether\n (defstruct blah :constructor NIL a b c)\n ; only change its name\n (defstruct blah :constructor blargh a b c)\n ; rename AND avoid using keywords\n (defstruct blah :constructor (blah a b c) a b c)\n\nThe option `:conc-name` specifies the slot accessor prefix, which\ndefaults to `name-`.\n\nDefault predicate name (`name?`) can be changed:\n\n ; use \"blargh?\" instead of \"blah?\"\n (defstruct blah :predicate blargh? a b c)" compare "Return -1 if `x` is less than `y`, 0 if equal, and `1` if `y` is\ngreater than `x`.\n\nExamples:\n\n (compare 'a 'b) → -1\n (compare 1 1) → 0\n (compare \"b\" \"a\") → 1" buffer "Return an in-memory buffer for I/O, of `io` type.\n\nA buffer can be used for both reading and writing at the same\ntime." num? "Return `T` if `v` is of a numerical type, `NIL` otherwise.\n\nNumerical types include floating point, fixnum, bignum, etc.\nNote: ironically, a NaN value is considered a number by this function\nsince it's only testing the _type_ of the value." add-exit-hook "Puts an one-argument function on top of the list of exit hooks.\n\nOn shutdown each exit hook is called with the exit status as a\nsingle argument, which is (usually) `0` on success and any other\nnumber on error." rand-float "Return a random float on [0.0, 1.0] interval." builtin? "Return `T` if `v` is a built-in function, `NIL` otherwise." cons? "Return `T` if the value is a cons cell, `NIL` otherwise." 1+ "Equivalent to `(+ n 1)`." aref "Return the sequence element by the subscripts. The sequence can be an\narray, vector or a list.\n\nExamples:\n\n (def a '((1 (2 (3)) 4)))\n (aref a 0) → (1 (2 (3)) 4)\n (aref a 1) → index 1 out of bounds\n (aref a 0 0) → 1\n (aref a 0 1 0) → 2\n (aref a 0 2) → 4" *properties* "All properties of symbols recorded with `putprop` are recorded in this table." zero? "Return `T` if `x` is zero." >= "Return `T` if the arguments are in non-increasing order (previous\none is greater than or equal to the next one)." void? "Return `T` if `x` is `#<void>`, `NIL` otherwise." length= "Perform
\ No newline at end of file
+ key val)) getprop ((symbol key (def NIL))) aref ((seq subscript…)) io->str ((io))) *doc* #table(io->str "Return an in-memory `io` buffer converted to a string." bound? "Return `T` if `symbol` has a value associated with it, `NIL` otherwise." io-eof? "Return `T` if `io` is currently in the \"end of file\" state, `NIL`\notherwise." sym "Convert terms to a symbol.\n\nThis is equivalent to `(sym (str terms…))`." nan? "Return `T` if `v` is a floating point representation of NaN, either\nnegative or positive, `NIL` otherwise." for "Call the function `fn` with a single integer argument, starting from\n`min` and ending with `max`.\n\nExamples:\n\n (for 0 2 (λ (i) (print (- 2 i)))) → 210" fixnum? "Return `T` if `v` is of a fixnum type, `NIL` otherwise." exit "Terminate the process with the specified status. Does not return." > "Return `T` if the arguments are in strictly decreasing order (previous\none is greater than the next one)." + "Return sum of the numbers or `0` with no arguments." __finish "A function called right before exit by the VM." lz-unpack "Return decompressed data previously compressed using lz-pack.\n\nEither destination for the decompressed data or the expected size of\nthe decompressed data must be specified. In the latter case a new\narray is allocated." defstruct "Defines a structure type with a specific name and slots.\n\nThe default underlying type is a \"named\" vector (`:type vec`),\nwhere the first element is the name of the structure's type, the\nrest are the slot values. If the name as the first element isn't\nrequired, `:named NIL` should be used. A list can be used instead\nof a vector by adding `:type list` option.\n\nAn example of a default constructor signature, based on structure\ndefinition:\n\n (defstruct blah a b c) →\n (make-blah (:a NIL) (:b NIL) (:c NIL))\n\nIt can be customized in several ways. For example:\n\n ; disable the constructor altogether\n (defstruct blah :constructor NIL a b c)\n ; only change its name\n (defstruct blah :constructor blargh a b c)\n ; rename AND avoid using keywords\n (defstruct blah :constructor (blah a b c) a b c)\n\nThe option `:conc-name` specifies the slot accessor prefix, which\ndefaults to `name-`.\n\nDefault predicate name (`name?`) can be changed:\n\n ; use \"blargh?\" instead of \"blah?\"\n (defstruct blah :predicate blargh? a b c)" compare "Return -1 if `x` is less than `y`, 0 if equal, and `1` if `y` is\ngreater than `x`.\n\nExamples:\n\n (compare 'a 'b) → -1\n (compare 1 1) → 0\n (compare \"b\" \"a\") → 1" buffer "Return an in-memory buffer for I/O, of `io` type.\n\nA buffer can be used for both reading and writing at the same\ntime." num? "Return `T` if `v` is of a numerical type, `NIL` otherwise.\n\nNumerical types include floating point, fixnum, bignum, etc.\nNote: ironically, a NaN value is considered a number by this function\nsince it's only testing the _type_ of the value." add-exit-hook "Puts an one-argument function on top of the list of exit hooks.\n\nOn shutdown each exit hook is called with the exit status as a\nsingle argument, which is (usually) `0` on success and any other\nnumber on error." rand-float "Return a random float on [0.0, 1.0] interval." builtin? "Return `T` if `v` is a built-in function, `NIL` otherwise." cons? "Return `T` if the value is a cons cell, `NIL` otherwise." 1+ "Equivalent to `(+ n 1)`." aref "Return the sequence element by the subscripts. The sequence can be an\narray, vector or a list.\n\nExamples:\n\n (def a '((1 (2 (3)) 4)))\n (aref a 0) → (1 (2 (3)) 4)\n (aref a 1) → index 1 out of bounds\n (aref a 0 0) → 1\n (aref a 0 1 0) → 2\n (aref a 0 2) → 4" *properties* "All properties of symbols recorded with `putprop` are recorded in this table." zero? "Return `T` if `x` is zero." >= "Return `T` if the arguments are in non-increasing order (previous\none is greater than or equal to the next one)." void? "Return `T` if `x` is `#<void>`, `NIL` otherwise." length= "Perf
\ No newline at end of file
a bounded length test.\n\nUse this instead of `(= (length lst) n)`, since it avoids unnecessary\nwork and always terminates." positive? "Return `T` if `x` is greater than zero." doc-for "Define documentation for a top level term.\n\nIf `term` is a function signature and `doc` is not specified, just\nthe signature will be included in the documentation, without\nreplacing any previously defined." car "Return the first element of a list or `NIL` if not available." *builtins* "VM instructions as closures." str "Convert terms to a concatenated string.\n\nThis is equivalent to `(princ terms…)`, except the string is\nreturned, rather than printed." remprop "Remove a property value associated with a symbol." <= "Return `T` if the arguments are in non-decreasing order (previous\none is less than or equal to the next one)." negative? "Return `T` if `x` is negative." rand "Return a random non-negative fixnum on its maximum range." void "Return the constant `#<void>` while ignoring any arguments.\n\n`#<void>` is mainly used when a function has side effects but does not\nproduce any meaningful value to return, so even though `T` or `NIL` could\nbe returned instead, in case of `#<void>` alone, REPL will not print\nit." Instructions "VM instructions mapped to their encoded byte representation." file "Open a file for I/O.\n\nAn `io` object is returned. Without any modes specified the file\nis opened in read-only mode." rand-double "Return a random double on interval [0.0, 1.0]." 1- "Equivalent to `(- n 1)`." cdr "Return the tail of a list or `NIL` if not available." T "A boolean \"true\".\n\n(not T) → NIL\n(if T 'yes 'no) → 'yes" vec? "Return `T` if `v` is a vector, `NIL` otherwise." io? "Return `T` if `term` is of `io` type, `NIL` otherwise." eof-object? "Return `T` if `term` is `#<eof>`, `NIL` otherwise.\n\nThis object is returned by I/O functions to signal end of file,\nwhere applicable." help "Display documentation for the specified term, if available." rand-u32 "Return a random integer on interval [0, 2³²-1]." = "Numerical equality test. Return `T` if all numbers are equal," rand-u64 "Return a random integer on interval [0, 2⁶⁴-1]." NIL "An empty list. Also used as the opposite of T.\n\n(not NIL) → T\n(if NIL 'yes 'no) → 'no\n(car NIL) → NIL\n(cdr NIL) → NIL" /= "Return `T` if not all arguments are equal. Shorthand for `(not (= …))`." fn? "Return `T` if `v` is a function, `NIL` otherwise." lz-pack "Return data compressed using Lempel-Ziv.\n\nThe data must be an array, returned value will have the same type.\nThe optional `level` is between `0` and `10`. With `level` set to\n`0` a simple LZSS using hashing will be performed. Levels between\n`1` and `9` offer a trade-off between time/space and ratio. Level\n`10` is optimal but very slow." arg-counts "VM instructions mapped to their expected arguments count." *prompt* "Function called by REPL to signal the user input is required.\n\nDefault function prints `#;> `." getprop "Get a property value associated with a symbol or `def` if missing." vm-stats "Print various VM-related information, such as the number of GC\ncalls so far, heap and stack size, etc." * "Return product of the numbers or `1` with no arguments." putprop "Associate a property value with a symbol." identity "Return `x`."))
*syntax-environment* #table(bcode:nconst #fn("n1200r2e3:" #(aref)) doc-for #fn("\x8710002000W1000J60q?140B86;35040<;J404086;35040=863H020212287e212288e2e4e2:20212287e21e3e2:" #(void sym-set-doc quote)) with-input-from #fn("z12021e1220e2e1e12315163:" #(#fn(nconc) with-bindings--- a/src/plan9/lsd.lsp
+++ b/src/plan9/lsd.lsp
@@ -47,7 +47,7 @@
(def (stop) (writectl "stop") (readnote))
(def (follow addr)
- "Returns a list of the next possible executing instructions."
+ "Return a list of the next possible executing instructions."
(lsd-follow addr))
(def (io-pread f off rest)
@@ -109,6 +109,7 @@
"Set a breakpoint.
The location can be one of the following:
+
1. A sym, in which case the address will be retrieved from
the global text symbols of the process,
2. A num which is the address at which to place the break.
@@ -117,14 +118,16 @@
file of source code.
Examples:
- `(bpset 'strcpy)` ; breakpoint on strcpy function.
- `(bpset (readreg PC))` ; breakpoint on current instruction.
- `(bpset \"/sys/src/cmd/cat.c:26\")` ; breakpoint on line 26.")
+ `(bpset 'strcpy)` ; breakpoint on strcpy function.
+ `(bpset (readreg PC))` ; breakpoint on current instruction.
+ `(bpset \"/sys/src/cmd/cat.c:26\")` ; breakpoint on line 26.")
+
(doc-for (bpdel loc)
"Delete a breakpoint.
The location can be one of the following:
+
1. A sym, in which case the address will be retrieved from
the global text symbols of the process,
2. A num which is the address at which to place the break.
@@ -133,10 +136,11 @@
file of source code.
Examples:
- `(bpdel 'strcpy)` ; remove breakpoint on strcpy function.
- `(bpdel (readreg PC))` ; remove breakpoint on current instruction.
- `(bpdel \"/sys/src/cmd/cat.c:26\")` ; remove breakpoint on line 26.")
+ `(bpdel 'strcpy)` ; remove breakpoint on strcpy function.
+ `(bpdel (readreg PC))` ; remove breakpoint on current instruction.
+ `(bpdel \"/sys/src/cmd/cat.c:26\")` ; remove breakpoint on line 26.")
+
(def (detach)
(when regsf (io-close regsf))
(when fpregsf (io-close fpregsf))
@@ -191,7 +195,7 @@
(def (curPC) (and (>= pid 0) (readreg PC)))
(def (step (n 1))
- "Step `n` assembly instructions. Returns the next instruction
+ "Step `n` assembly instructions. Return the next instruction
address to be executed or `NIL` if the program has exited."
(if (= n 0)
(curPC)
@@ -207,7 +211,7 @@
(step (1- n))))))
(def (cont)
- "Continue program execution. Returns the next instruction
+ "Continue program execution. Return the next instruction
address to be executed or `NIL` if the program has exited."
(let ((addr (readreg PC)))
(when (has? bptbl addr) (step))
@@ -215,7 +219,7 @@
(curPC)))
(def (asmlist (n 5) (addr (readreg PC)))
- "Returns a list of the next `n` disassembled instructions starting at `addr`.
+ "Return a list of the next `n` disassembled instructions starting at `addr`.
Each element in the list has the form `(address . instr)` where `instr`
is the disassembled instruction at the `address`.
@@ -235,19 +239,20 @@
"Print the next `n` disassembled instructions at addr.
Examples:
- `(asm)` ; print out 5 from current program instruction.
- `(asm 10)` ; print out 10 from current program instruction.
- `(asm 5 (step))` ; step and then print out 5."
+
+ `(asm)` ; print out 5 from current program instruction.
+ `(asm 10)` ; print out 10 from current program instruction.
+ `(asm 5 (step))` ; step and then print out 5."
(for-each (λ (i) (princ (car i) "\t" (cdr i) "\n"))
(asmlist n addr)))
(def (src (addr (readreg PC)))
- "Returns a string of the filename and line number corresponding
+ "Return a string of the filename and line number corresponding
to the instruction address."
(lsd-fileline addr))
(def (Bsrc (addr (readreg PC)))
- "Sends a plumb message of the filename and line number so
+ "Send a plumb message of the filename and line number so
the source code corresponding to the instruction address
can be viewed in your text editor.
--- a/tools/gen.lsp
+++ b/tools/gen.lsp
@@ -154,7 +154,7 @@
Examples:
- (for 0 2 (λ (i) (print (- 2 i)))) → 210"]})
+ (for 0 2 (λ (i) (print (- 2 i)))) → 210"]})
(op tapply)
(op sub2)
(op argc.l)