ref: d45ce3691d4cb85aa9c047b5e498a9aa601dcd94
parent: 4ba6e67e51377bf0824573f6445c4714b41d8e7a
author: Sigrid Solveig Haflínudóttir <sigrid@ftrv.se>
date: Mon Mar 24 23:50:09 EDT 2025
use verbatim strings where it makes sense
--- a/boot/sl.boot
+++ b/boot/sl.boot
@@ -30,7 +30,7 @@
(doc NIL))) set-cdr! ((cell new-second)) fn? ((v)) help-print-header ((term sigs (:kind NIL)
(:lpad ""))) lz-pack ((data
(level 0))) *prompt* (NIL) eq? ((a b)) getprop ((symbol key (def NIL))) vm-stats (NIL) * (rest) putprop ((symbol
- key val)) io->str ((io))) *doc* #table(identity "Return `x`." (doc group vm) "VM-related functions." bound? "Return `T` if `symbol` has a value associated with it, `NIL` otherwise." sym-set-doc "Set the documentation for the symbol." io-eof? "Return `T` if `io` is currently in the \"end of file\" state, `NIL`\notherwise." < "Return `T` if the arguments are in strictly increasing order (next\none is greater than the previous one). With a single argument\nthe result is always `T`." cadr "Shorthand for `(car (cdr cell))`, that is, \"first element of the\nsecond element\".\n\nExamples:\n\n (cadr '(1 2 3)) → 2\n (cadr '(1)) → NIL\n (cadr NIL) → NIL" 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.\nThe status is expected to be a string in case of an error.\n\nExamples:\n\n (exit) ; exit with status 0 (nil on Plan 9)\n (exit \"error\") ; exit with status 1 (\"error\" on Plan 9)" (doc
+ key val)) io->str ((io))) *doc* #table(identity "Return `x`." (doc group vm) "VM-related functions." bound? "Return `T` if `symbol` has a value associated with it, `NIL` otherwise." sym-set-doc "Set the documentation for the symbol." io-eof? "Return `T` if `io` is currently in the \"end of file\" state, `NIL`\notherwise." < "Return `T` if the arguments are in strictly increasing order (next\none is greater than the previous one). With a single argument\nthe result is always `T`." cadr "Shorthand for `(car (cdr cell))`, that is, _first element of the\nsecond element_.\n\nExamples:\n\n (cadr '(1 2 3)) → 2\n (cadr '(1)) → NIL\n (cadr NIL) → NIL" 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.\nThe status is expected to be a string in case of an error.\n\nExamples:\n\n (exit) ; exit with status 0 (nil on Plan 9)\n (exit \"error\") ; exit with status 1 (\"error\" on Plan 9)" (doc
group compare) "Comparison operators." (doc group compress) "Compression." + "Return sum of the arguments or `0` when none specified." (doc
group builtin) "Built-in operators." div0 "Return the quotient of two numbers. For non-integers this is\nequivalent to `(div0 (floor a) (floor b))`. The result is always an\ninteger.\n\nExamples:\n\n (div0 7 2) → 3\n (div0 10 -2) → -5\n (div0 6.9 1.9) → 6" 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." > "Return `T` if the arguments are in strictly decreasing order (previous\none is greater than the next one)." __finish "A function called right before exit by the VM." 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 \"Return stuff.\" :doc-group stuff 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 :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)" (doc
group io) "I/O functionality." 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 single\nargument, which is (usually) `NIL` on success and a string describing\nan error otherwise." rand-float "Return a random float on [0.0, 1.0] interval." builtin? "Return `T` if `v` is a built-in function implemented in C, `NIL`\notherwise.\n\nExamples:\n\n (builtin? map) → T\n (builtin? macroexpand) → NIL" set-car! "Modify a cons cell (a list) in-place by putting `new-first` as its\nfirst element (head of the list). Return the modified cons\ncell (list).\n\nExamples:\n\n (def q '(1 2 3 4 5))\n (set-car! q 0) → (0 6 7)\n q → (0 6 7)" doc-group "Define documentation for a group." cons? "Return `T` if `v` is a cons cell, `NIL` otherwise.\n\nExamples:\n\n (cons? 0) → NIL\n (cons? NIL) → NIL\n (cons? '(1)) → T" 1+ "Equivalent to `(+ n 1)`." aref "Return the sequence element specified by the subscripts. The sequence\ncan be an array, vector, a list. Multi-dimensional sequences\nof variating types are also supported.\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." vec "Return a vector constructed of the arguments.\n\nExamples:\n\n (vec) → #() ; empty vector\n (vec 1 2.5 \"a\" 'b) → #(1 2.5 \"a\" b)" >= "Return `T` if the arguments are in non-increasing order (previous\none is greater than or equal to the next one)." sym? "Return `T` if `v` is a symbol, `NIL` otherwise." (doc
--- a/src/docs.sl
+++ b/src/docs.sl
@@ -1,5 +1,5 @@
(defmacro (doc-for term . doc)
- "Define documentation for a top level term.
+ «Define documentation for a top level term.
If `term` is a function signature and `doc` is not specified, just
the signature will be included in the documentation, without
@@ -7,7 +7,7 @@
First `doc` argument is supposed to be a string with the description
of the term. The following arguments are expected to be optional tag
- pairings that provide grouping for multiple symbols and \"see also\"
+ pairings that provide grouping for multiple symbols and "see also"
references.
Useful in cases where setting the documentation for a term can't
@@ -18,7 +18,7 @@
Examples:
(doc-for (func arg (arg2 0))
- \"Return something about the `arg` and `arg2`. This is a short
+ "Return something about the `arg` and `arg2`. This is a short
description.
This is the longer description, following the short one.
@@ -26,10 +26,10 @@
Examples:
(func 0) → T
- (func 1 3) → NIL\"
+ (func 1 3) → NIL"
:doc-group stuff
:doc-see func2)
- (doc-for (func arg (:another-variant NIL)))"
+ (doc-for (func arg (:another-variant NIL)))»
:doc-group doc
(let* {[call (cons? term)][sym (or (and call (car term))
@@ -109,13 +109,13 @@
"OS-specific functions.")
(doc-for (exit (status NIL))
- "Terminate the process with the specified status. Does not return.
+ «Terminate the process with the specified status. Does not return.
The status is expected to be a string in case of an error.
Examples:
(exit) ; exit with status 0 (nil on Plan 9)
- (exit \"error\") ; exit with status 1 (\"error\" on Plan 9)"
+ (exit "error") ; exit with status 1 ("error" on Plan 9)»:doc-group sys)
(doc-group io
@@ -141,8 +141,8 @@
:doc-group io)
(doc-for (io-eof? io)
- "Return `T` if `io` is currently in the \"end of file\" state, `NIL`
- otherwise."
+ «Return `T` if `io` is currently in the "end of file" state, `NIL`
+ otherwise.»
:doc-group io)
(doc-for (eof-object? term)
@@ -172,12 +172,12 @@
:doc-see T)
(doc-for T
- "A boolean \"true\".
+ «A boolean "true".
Examples:
(not T) → NIL
- (if T 'yes 'no) → yes"
+ (if T 'yes 'no) → yes»
:doc-see NIL)
(doc-group string
@@ -184,7 +184,7 @@
"String-related functionality.")
(doc-for (str . term)
- "Return concatenation of terms formatted as strings.
+ «Return concatenation of terms formatted as strings.
This is equivalent to `(princ terms…)`, except the string is
returned, rather than printed.
@@ -191,11 +191,11 @@
Examples:
- (str \"a\" 'b 1 #(0)) → \"ab1#(0)\""
+ (str "a" 'b 1 #(0)) → "ab1#(0)"»
:doc-group string)
(doc-for (sym . term)
- "Return a symbol with the name being the concatenation of terms
+ «Return a symbol with the name being the concatenation of terms
formatted as strings.
This is equivalent to `(sym (str terms…))`.
@@ -202,4 +202,4 @@
Examples:
- (sym \"a\" 'b 1) → ab1")
+ (sym "a" 'b 1) → ab1»)
--- a/src/system.sl
+++ b/src/system.sl
@@ -1031,9 +1031,9 @@
(:conc-name NIL)
(:predicate NIL)
. slots)
- "Defines a structure type with a specific name and slots.
+ «Defines a structure type with a specific name and slots.
- The default underlying type is a \"named\" vector (`:type vec`),
+ The default underlying type is a "named" vector (`:type vec`),
where the first element is the name of the structure's type, the
rest are the slot values. If the name as the first element isn't
required, `:named NIL` should be used. A list can be used instead
@@ -1042,7 +1042,7 @@
An example of a default constructor signature, based on structure
definition:
- (defstruct blah \"Return stuff.\" :doc-group stuff a b c) →
+ (defstruct blah "Return stuff." :doc-group stuff a b c) →
(make-blah (:a NIL) (:b NIL) (:c NIL))
It can be customized in several ways. For example:
@@ -1059,8 +1059,8 @@
Default predicate name (`name?`) can be changed:
- ; use \"blargh?\" instead of \"blah?\"
- (defstruct blah :predicate blargh? a b c)"
+ ; use "blargh?" instead of "blah?"
+ (defstruct blah :predicate blargh? a b c)»
(def (slot-opts slot)
; check whether slot options, if any, are valid
(let ((opts (cddr slot)))
--- a/test/unittest.sl
+++ b/test/unittest.sl
@@ -531,7 +531,7 @@
(let ((b (buffer)))
(write "a\x0a\x09\\\x07\x08\x1b\x0c\x0d\x0b" b)
- (assert (equal? (io->str b) "\"a\\n\\t\\\\\\a\\b\\e\\f\\r\\v\"")))
+ (assert (equal? (io->str b) «"a\n\t\\\a\b\e\f\r\v"»)))
(assert (= 10 (str-width s)))
(assert (= 0 (str-width "")))
--- a/tools/gen.sl
+++ b/tools/gen.sl
@@ -78,16 +78,16 @@
(op aref2)
(op atom? 1 (λ (x) (atom? x))
{[(value)- "Return `T` if `v` is a _not_ a cons cell, `NIL` otherwise. This is
+ «Return `T` if `v` is a _not_ a cons cell, `NIL` otherwise. This is
the opposite of `cons?`.
- The term \"atom\" comes from the idea of being indivisible.
+ The term "atom" comes from the idea of being indivisible.
Examples:
- (atom? \"a\") → T
+ (atom? "a") → T
(atom? NIL) → T
- (atom? '(1)) → NIL"]})
+ (atom? '(1)) → NIL»]})
(op loadvoid)
(op brnn)
(op load1)
@@ -124,18 +124,18 @@
:doc-group list]})
(op eq? 2 (λ (x y) (eq? x y))
{[(a b)- "Return `T` if `a` and `b` are the same object, `NIL` otherwise.
+ «Return `T` if `a` and `b` are the same object, `NIL` otherwise.
Examples:
(eq? 0.0 0) → NIL
(eq? 0 0) → T
- (def a \"1\")
- (def b \"1\")
+ (def a "1")
+ (def b "1")
(eq? a b) → NIL
(def a '(1))
(def b '(1))
- (eq? a b) → NIL"
+ (eq? a b) → NIL»
:doc-group compare]})
(op sym? 1 (λ (x) (sym? x))
{[(v)@@ -145,14 +145,14 @@
"Return `T` if `v` is `NIL`, `T` otherwise."]})
(op cadr 1 (λ (x) (cadr x))
{[(cell)- "Shorthand for `(car (cdr cell))`, that is, \"first element of the
- second element\".
+ «Shorthand for `(car (cdr cell))`, that is, _first element of the
+ second element_.
Examples:
(cadr '(1 2 3)) → 2
(cadr '(1)) → NIL
- (cadr NIL) → NIL"
+ (cadr NIL) → NIL»
:doc-group list]})
(op neg)
(op nan? 1 (λ (x) (nan? x))
@@ -211,7 +211,7 @@
(op box)
(op eqv? 2 (λ (x y) (eqv? x y))
{[(a b)- "Return `T` if both `a` and `b` are of the same value and primitive
+ «Return `T` if both `a` and `b` are of the same value and primitive
(leaf) type, `NIL` otherwise. Neither cons cell nor vector are not
considered primitive types as they may define deep structures.
@@ -219,16 +219,16 @@
(eqv? 0.0 0) → NIL
(eqv? 0 0) → T
- (def a \"1\")
- (def b \"1\")
+ (def a "1")
+ (def b "1")
(eqv? a b) → T
(def a '(1))
(def b '(1))
- (eqv? a b) → NIL"
+ (eqv? a b) → NIL»
:doc-group compare]})
(op equal? 2 (λ (x y) (equal? x y))
{[(a b)- "Return `T` if both `a` and `b` are of the same value. For non-leaf
+ «Return `T` if both `a` and `b` are of the same value. For non-leaf
types (cons cell and vector), the equality test is performed
throughout the whole structure of the values.
@@ -236,21 +236,21 @@
(equal? 0.0 0) → NIL
(equal? 0 0) → T
- (def a \"1\")
- (def b \"1\")
+ (def a "1")
+ (def b "1")
(equal? a b) → T
(def a '(1))
(def b '(1))
- (equal? a b) → T"
+ (equal? a b) → T»
:doc-group compare]})
(op list T (λ rest rest)
{[rest- "Return a list constructed of the arguments.
+ «Return a list constructed of the arguments.
Examples:
(list) → NIL ; empty list
- (list 1 2.5 \"a\" 'b) → (1 2.5 \"a\" b)"]})
+ (list 1 2.5 "a" 'b) → (1 2.5 "a" b)»]})
(op apply -2 (λ rest (apply apply rest))
{[(fn arg . rest)"Return the result of applying a function to a list of arguments.
@@ -313,7 +313,7 @@
:cname "NUMEQP")
(op compare 2 (λ (x y) (compare x y))
{[(x y)- "Return -1 if `x` is less than `y`, 0 if equal, and `1` if `y` is
+ «Return -1 if `x` is less than `y`, 0 if equal, and `1` if `y` is
greater than `x`.
Examples:
@@ -320,16 +320,16 @@
(compare 'a 'b) → -1
(compare 1 1) → 0
- (compare \"b\" \"a\") → 1"]})
+ (compare "b" "a") → 1»]})
(op argc)
(op vec T (λ rest (apply vec rest))
{[rest- "Return a vector constructed of the arguments.
+ «Return a vector constructed of the arguments.
Examples:
(vec) → #() ; empty vector
- (vec 1 2.5 \"a\" 'b) → #(1 2.5 \"a\" b)"]})
+ (vec 1 2.5 "a" 'b) → #(1 2.5 "a" b)»]})
(op aset! -3 (λ rest (apply aset! rest))
{[(sequence subscripts… new-value)"Modify the sequence element specified by the subscripts and return the
@@ -438,9 +438,9 @@
(io-write c-code "const Builtin builtins[N_OPCODES] = {\n")(for-each
(λ (c la) (begin (io-write c-code (str "\t[" c))
- (io-write c-code "] = {\"")+ (io-write c-code «] = {"»)(write (car la) c-code)
- (io-write c-code "\", ")
+ (io-write c-code «", »)
(write (cadr la) c-code)
(io-write c-code "},\n")))
c-op-to-op-arg)