shithub: sl

Info  •  Files  •  Log  •  Branches

docs: a bit more documentation for io

--- a/boot/sl.boot

+++ b/boot/sl.boot

@@ -12,17 +12,20 @@

               #fn("n201m:" #()) NIL #fn("z0700}2:" #(vec))

               #fn("z0700}2:" #(aset!)) NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL NIL #fn("n3012082>1|:" #(#fn("n1A061:" #())))

               NIL NIL NIL NIL NIL NIL NIL NIL #fn("z0700}2:" #(aref)) NIL NIL NIL)

-            *properties* #table(*funvars* #table(identity ((x))  >= ((a . rest))  void? ((x))  length= ((lst

+            *properties* #table(*funvars* #table(zero? ((x))  >= ((a . rest))  void? ((x))  identity ((x))  length= ((lst

   n))  positive? ((x))  doc-for ((term (doc NIL)))  car ((lst))  <= ((a . rest))  remprop ((symbol

-  key))  negative? ((x))  rand (NIL)  void (rest)  nan? ((x))  rand-double (NIL)  1- ((n))  > ((a . rest))  cdr ((lst))  + ((num…))  __finish ((status))  lz-unpack ((data

-  :to destination)

-  (data :size decompressed-bytes))  defstruct ((name doc options… (slot-1 DEFAULT) slot-2 (slot-3

-  :read-only))

-                                               (name (:type vec) (:named T) (:constructor T) (:conc-name

+  key))  negative? ((x))  rand (NIL)  void (rest)  nan? ((x))  file ((path (:read NIL) (:write NIL)

+                                                                           (:create NIL) (:truncate

   NIL)

-                                                     (:predicate NIL) . slots))  help ((term))  rand-u32 (NIL)  = ((a . rest))  rand-u64 (NIL)  add-exit-hook ((fun))  /= ((a . rest))  lz-pack ((data

-  (level 0)))  rand-float (NIL)  *prompt* (NIL)  getprop ((symbol key (def NIL)))  cons? ((value))  vm-stats (NIL)  * ((num…))  putprop ((symbol

-  key val))  1+ ((n))  zero? ((x)))  *doc* #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."  identity "Return `x`."  length= "Perform 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."  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."  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."  rand "Return a random non-negative fixnum on its maximum range."  nan? "Return `T` if the argument is *NaN*, regardless of the sign."  Instructions "VM instructions mapped to their encoded byte representation."  rand-double "Return a random double on interval [0.0, 1.0]."  1- "Equivalent to `(- n 1)`."  > "Return `T` if the arguments are in strictly decreasing order (previous\none is greater than the next one)."  cdr "Return the tail of a list or `NIL` if not available."  + "Return sum of the numbers or `0` with no arguments."  T "A boolean \"true\".\n\n(not T)         → NIL\n(if T 'yes 'no) → 'yes"  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."  __finish "A function called right before exit by the VM."  help "Display documentation for the specified term, if available."  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)"  rand-u32 "Return a random integer on interval [0, 2³²-1]."  = "Return `T` if the arguments 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"  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."  /= "Return `T` if not all arguments are equal. Shorthand for `(not (= …))`."  lz-pack "Return data compressed using Lempel-Ziv.\n\

\ No newline at end of file

+                                                                           (:append NIL)))  rand-double (NIL)  exit ((status))  1- ((n))  cdr ((lst))  + ((num…))  > ((a . rest))  __finish ((status))  lz-unpack ((data

+  :to destination)

+  (data :size decompressed-bytes))  io? ((term))  defstruct ((name doc options… (slot-1 DEFAULT)

+                                                                   slot-2 (slot-3 :read-only))

+                                                             (name (:type vec) (:named T) (:constructor

+  T)

+                                                                   (:conc-name NIL) (:predicate NIL) . slots))  eof-object? ((term))  help ((term))  rand-u32 (NIL)  = ((a . rest))  rand-u64 (NIL)  buffer (NIL)  add-exit-hook ((fun))  /= ((a . rest))  lz-pack ((data

+  (level 0)))  rand-float (NIL)  *prompt* (NIL)  getprop ((symbol key (def NIL)))  putprop ((symbol

+  key val))  * ((num…))  vm-stats (NIL)  cons? ((value))  1+ ((n))  io->str ((io)))  *doc* #table(*properties* "All properties of symbols recorded with `putprop` are recorded in this table."  >= "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."  zero? "Return `T` if `x` is zero."  identity "Return `x`."  length= "Perform 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."  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."  nan? "Return `T` if the argument is *NaN*, regardless of the sign."  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]."  exit "Terminate the process with the specified status. Does not return."  1- "Equivalent to `(- n 1)`."  cdr "Return the tail of a list or `NIL` if not available."  + "Return sum of the numbers or `0` with no arguments."  T "A boolean \"true\".\n\n(not T)         → NIL\n(if T 'yes 'no) → 'yes"  > "Return `T` if the arguments are in strictly decreasing order (previous\none is greater than the next one)."  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."  __finish "A function called right before exit by the VM."  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."  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)"  rand-u32 "Return a random integer on interval [0, 2³²-1]."  = "Return `T` if the arguments are equal."  rand-u64 "Return a random int

\ No newline at end of file

 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."  rand-float "Return a random float on [0.0, 1.0] interval."  *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."  putprop "Associate a property value with a symbol."  * "Return product of the numbers or `1` with no arguments."  vm-stats "Print various VM-related information, such as the number of GC\ncalls so far, heap and stack size, etc."  cons? "Return `T` if the value is a cons cell."  1+ "Equivalent to `(+ n 1)`."  *properties* "All properties of symbols recorded with `putprop` are recorded in this table."))

             *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/docs_extra.lsp

+++ b/src/docs_extra.lsp

@@ -54,6 +54,33 @@

 (doc-for (rand-float)

   "Return a random float on [0.0, 1.0] interval.")

+(doc-for (exit status)

+  "Terminate the process with the specified status. Does not return.")

+

+(doc-for (file path (:read NIL) (:write NIL) (:create NIL) (:truncate NIL) (:append NIL))

+  "Open a file for I/O.

+

+   An `io` object is returned.  Without any modes specified the file

+   is opened in read-only mode.")

+

+(doc-for (io? term)

+  "Return `T` if `term` is of `io` type, `NIL` otherwise.")

+

+(doc-for (io->str io)

+  "Return an in-memory `io` buffer converted to a string.")

+

+(doc-for (eof-object? term)

+  "Return `T` if `term` is `#<eof>`, `NIL` otherwise.

+

+   This object is returned by I/O functions to signal end of file,

+   where applicable.")

+

+(doc-for (buffer)

+  "Return an in-memory buffer for I/O, of `io` type.

+

+   A buffer can be used for both reading and writing at the same

+   time.")

+

 (doc-for NIL

   "An empty list. Also used as the opposite of T.