diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2001-03-23 15:05:40 +0000 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2001-03-23 15:05:40 +0000 |
commit | 780ee65e3b04d6253598f4af5e66f6f04d6e893d (patch) | |
tree | 2eccb60839aa6eeacb4adfe5348674a0feefb9ad | |
parent | be54b15d85632c1da64f36cc68623b76efc7239e (diff) | |
download | guile-780ee65e3b04d6253598f4af5e66f6f04d6e893d.tar.gz |
* Automatic docstring updates.
* Commit utilities and tracking files for automatic docstring updates.
-rw-r--r-- | doc/ChangeLog | 8 | ||||
-rw-r--r-- | doc/maint/ChangeLog | 4 | ||||
-rw-r--r-- | doc/maint/README | 16 | ||||
-rw-r--r-- | doc/maint/docstring.el | 563 | ||||
-rw-r--r-- | doc/maint/guile.texi | 7087 | ||||
-rw-r--r-- | doc/new-docstrings.texi | 599 | ||||
-rw-r--r-- | doc/posix.texi | 12 | ||||
-rwxr-xr-x | doc/scheme-data.texi | 462 | ||||
-rw-r--r-- | doc/scheme-evaluation.texi | 47 | ||||
-rw-r--r-- | doc/scheme-io.texi | 40 | ||||
-rw-r--r-- | doc/scheme-memory.texi | 10 |
11 files changed, 8574 insertions, 274 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 26154476b..dfa0f66c3 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,11 @@ +2001-03-23 Neil Jerram <neil@ossau.uklinux.net> + + * posix.texi, scheme-data.texi, scheme-evaluation.texi, + scheme-io.texi, scheme-memory.texi: Automatic docstring updates. + + * new-docstrings.texi: New file. Holds snarfed docstrings that + have not yet been incorporated into the reference manual. + 2001-03-20 Martin Grabmueller <mgrabmue@cs.tu-berlin.de> * scheme-options.texi (Evaluator options): Added evaluator diff --git a/doc/maint/ChangeLog b/doc/maint/ChangeLog new file mode 100644 index 000000000..c8c549ea1 --- /dev/null +++ b/doc/maint/ChangeLog @@ -0,0 +1,4 @@ +2001-03-23 Neil Jerram <neil@ossau.uklinux.net> + + * ChangeLog, README, docstring.el, guile.texi: New files. + diff --git a/doc/maint/README b/doc/maint/README new file mode 100644 index 000000000..0a46418bc --- /dev/null +++ b/doc/maint/README @@ -0,0 +1,16 @@ +README for guile-core/doc/maint -*- text -*- + +The files in this directory are used by the maintainers to automate +the process of updating the Guile reference manual when the docstrings +in the libguile C source change. + +- ChangeLog is the change log for files in this directory. + +- README is this file. + +- docstring.el is a helpful Emacs Lisp library. The usual entry point + is `docstring-process-current-buffer'. + +- guile.texi is a snapshot of the built file + guile-core/libguile/guile.texi, copied last time the reference + manual was determined to be in sync with the libguile source. diff --git a/doc/maint/docstring.el b/doc/maint/docstring.el new file mode 100644 index 000000000..b346b96bd --- /dev/null +++ b/doc/maint/docstring.el @@ -0,0 +1,563 @@ +;;; docstring.el --- utilities for Guile docstring maintenance +;;; +;;; Copyright (C) 2001 Neil Jerram +;;; +;;; This file is not part of GNU Emacs, but the same permissions apply. +;;; +;;; GNU Emacs is free software; you can redistribute it and/or modify +;;; it under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 2, or (at your option) +;;; any later version. +;;; +;;; GNU Emacs is distributed in the hope that it will be useful, +;;; but WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with GNU Emacs; see the file COPYING. If not, write to the +;;; Free Software Foundation, Inc., 59 Temple Place - Suite 330, +;;; Boston, MA 02111-1307, USA. + +;;; Commentary: + +;; The basic premise of these utilities is that - at least in the +;; short term - we can get a lot of reference manual mileage by +;; co-opting the docstrings that are snarfed automatically from +;; Guile's C and Scheme source code. But this leads to problems of +;; synchronization... How do you track when a docstring has been +;; updated in the source and so needs updating in the reference +;; manual. What if a procedure is removed from the Guile source? And +;; so on. To complicate matters, the exact snarfed docstring text +;; will probably need to be modified so that it fits into the flow of +;; the manual section in which it appears. Can we design solutions to +;; synchronization problems that continue to work even when the manual +;; text has been enhanced in this way? +;; +;; This file implements an approach to this problem that I have found +;; useful. It involves keeping track of three copies of each +;; docstring: +;; +;; "MANUAL" = the docstring as it appears in the reference manual. +;; +;; "SNARFED" = the docstring as snarfed from the current C or Scheme +;; source. +;; +;; "TRACKING" = the docstring as it appears in a tracking file whose +;; purpose is to record the most recent snarfed docstrings +;; that are known to be in sync with the reference manual. +;; +;; The approaches are as follows. +;; +;; 1. Comparison of MANUAL-DOC, SOURCE-DOC and TRACK-DOC, to produce a +;; summary output buffer in which keystrokes are defined to bring up +;; detailed comparisons. +;; +;; 2. Comparison of MANUAL-DOC, SOURCE-DOC and TRACK-DOC using Ediff. + +;;; Code: + +(defvar docstring-manual-directory (expand-file-name "~/Guile/cvs/guile-core/doc") + "*The directory containing the Texinfo source for the Guile reference manual.") + +(defvar docstring-tracking-root (expand-file-name "~/Guile/cvs/guile-core/doc/maint") + "*Root directory for docstring tracking files. The tracking file +for module (a b c) is expected to be in the file +<docstring-tracking-root>/a/b/c.texi.") + +(defvar docstring-snarfed-roots (list (expand-file-name "~/Guile/cvs/guile-core/libguile") + (expand-file-name "~/Guile/cvs/guile-core/ice-9") + (expand-file-name "~/Guile/cvs/guile-core/oop")) + "*List of possible root directories for snarfed docstring files. +For each entry in this list, the snarfed docstring file for module (a +b c) is looked for in the file <entry>/a/b/c.texi.") + +(defvar docstring-manual-files '("appendices.texi" + "deprecated.texi" + "expect.texi" + "gh.texi" + "goops.texi" + "guile.texi" + "indices.texi" + "intro.texi" + "posix.texi" + "scheme-binding.texi" + "scheme-control.texi" + "scheme-data.texi" + "scheme-debug.texi" + "scheme-evaluation.texi" + "scheme-ideas.texi" + "scheme-indices.texi" + "scheme-intro.texi" + "scheme-io.texi" + "scheme-memory.texi" + "scheme-modules.texi" + "scheme-options.texi" + "scheme-procedures.texi" + "scheme-reading.texi" + "scheme-scheduling.texi" + "scheme-translation.texi" + "scheme-utility.texi" + "scm.texi" + "scripts.texi" + "scsh.texi" + "slib.texi" + "tcltk.texi") + "List of Texinfo source files that comprise the Guile reference manual.") + +(defvar docstring-new-docstrings-file "new-docstrings.texi" + "The name of a file in the Guile reference manual source directory +to which new docstrings should be added.") + +;; Apply FN in turn to each element in the list CANDIDATES until the +;; first application that returns non-nil. +(defun or-map (fn candidates args) + (let ((result nil)) + (while candidates + (setq result (apply fn (car candidates) args)) + (if result + (setq result (cons (car candidates) result) + candidates nil) + (setq candidates (cdr candidates)))) + result)) + +;; Return t if the current buffer position is in the scope of the +;; specified MODULE, as determined by "@c module ..." comments in the +;; buffer. DEFAULT-OK specifies the return value in the case that +;; there are no preceding module comments at all. +(defun docstring-in-module (module default-ok) + (save-excursion + (if (re-search-backward "^@c module " nil t) + (progn + (search-forward "@c module ") + (equal module (read (current-buffer)))) + default-ok))) + +;; Find a docstring in the specified FILE-NAME for the item in module +;; MODULE and with description DESCRIPTION. MODULE should be a list +;; of symbols, Guile-style, for example: '(ice-9 session). +;; DESCRIPTION should be the string that is expected after the @deffn, +;; for example "primitive acons" or "syntax let*". +(defun find-docstring (file-name module description) + (and (file-exists-p file-name) + (let ((buf (find-file-noselect file-name)) + (deffn-regexp (concat "^@deffnx? " + (regexp-quote description) + "[ \n\t]")) + found + result) + (save-excursion + (set-buffer buf) + (goto-char (point-min)) + (while (and (not found) + (re-search-forward deffn-regexp nil t)) + (save-excursion + (goto-char (match-beginning 0)) + (beginning-of-line) + (if (docstring-in-module module t) + (setq found t)))) + (if found + (setq result + (list (current-buffer) + (progn + (re-search-backward "^@deffn ") + (beginning-of-line) + (point)) + (progn + (re-search-forward "^@end deffn") + (forward-line 1) + (point)))))) + result))) + +;; Find the reference manual version of the specified docstring. +;; MODULE and DESCRIPTION specify the docstring as per +;; `find-docstring'. The set of files that `find-manual-docstring' +;; searches is determined by the value of the `docstring-manual-files' +;; variable. +(defun find-manual-docstring (module description) + (let* ((result + (or-map 'find-docstring + (mapcar (function (lambda (file-name) + (concat docstring-manual-directory + "/" + file-name))) + (cons docstring-new-docstrings-file + docstring-manual-files)) + (list module + description))) + (matched-file-name (and (cdr result) + (file-name-nondirectory (car result))))) + (if matched-file-name + (setq docstring-manual-files + (cons matched-file-name + (delete matched-file-name docstring-manual-files)))) + (cdr result))) + +;; Convert MODULE to a directory subpath. +(defun module-to-path (module) + (mapconcat (function (lambda (component) + (symbol-name component))) + module + "/")) + +;; Find the current snarfed version of the specified docstring. +;; MODULE and DESCRIPTION specify the docstring as per +;; `find-docstring'. The file that `find-snarfed-docstring' looks in +;; is automatically generated from MODULE. +(defun find-snarfed-docstring (module description) + (let ((modpath (module-to-path module))) + (cdr (or-map (function (lambda (root) + (find-docstring (concat root + "/" + modpath + ".texi") + module + description))) + docstring-snarfed-roots + nil)))) + +;; Find the tracking version of the specified docstring. MODULE and +;; DESCRIPTION specify the docstring as per `find-docstring'. The +;; file that `find-tracking-docstring' looks in is automatically +;; generated from MODULE. +(defun find-tracking-docstring (module description) + (find-docstring (concat docstring-tracking-root + "/" + (module-to-path module) + ".texi") + module + description)) + +;; Extract an alist of modules and descriptions from the current +;; buffer. +(defun make-module-description-list () + (let ((alist nil) + (module '(guile))) + (save-excursion + (goto-char (point-min)) + (while (re-search-forward "^\\(@c module \\|@deffnx? \\({[^}]+}\\|[^ ]+\\) \\([^ \n]+\\)\\)" + nil + t) + (let ((matched (buffer-substring (match-beginning 1) + (match-end 1)))) + (if (string-equal matched "@c module ") + (setq module (read (current-buffer))) + (setq matched + (concat (buffer-substring (match-beginning 2) + (match-end 2)) + " " + (buffer-substring (match-beginning 3) + (match-end 3)))) + (message "Found docstring: %S: %s" module matched) + (let ((descriptions (assoc module alist))) + (setq alist + (cons (cons module (cons matched (cdr-safe descriptions))) + (if descriptions + (delete descriptions alist) + alist)))))))) + alist)) + +;; Return the docstring from the specified LOCATION. LOCATION is a +;; list of three elements: buffer, start position and end position. +(defun location-to-docstring (location) + (and location + (save-excursion + (set-buffer (car location)) + (buffer-substring (cadr location) (caddr location))))) + +;; Perform a comparison of the specified docstring. MODULE and +;; DESCRIPTION are as per usual. +(defun docstring-compare (module description) + (let* ((manual-location (find-manual-docstring module description)) + (snarf-location (find-snarfed-docstring module description)) + (track-location (find-tracking-docstring module description)) + + (manual-docstring (location-to-docstring manual-location)) + (snarf-docstring (location-to-docstring snarf-location)) + (track-docstring (location-to-docstring track-location)) + + action + issue) + + ;; Decide what to do. + (cond ((null snarf-location) + (setq action nil + issue (if manual-location + 'consider-removal + nil))) + + ((null manual-location) + (setq action 'add-to-manual issue nil)) + + ((null track-location) + (setq action nil + issue (if (string-equal manual-docstring snarf-docstring) + nil + 'check-needed))) + + ((string-equal track-docstring snarf-docstring) + (setq action nil issue nil)) + + ((string-equal track-docstring manual-docstring) + (setq action 'auto-update-manual issue nil)) + + (t + (setq action nil issue 'update-needed))) + + ;; Return a pair indicating any automatic action that can be + ;; taken, and any issue for resolution. + (cons action issue))) + +;; Add the specified docstring to the manual. +(defun docstring-add-to-manual (module description) + (let ((buf (find-file-noselect (concat docstring-manual-directory + "/" + docstring-new-docstrings-file)))) + (save-excursion + (set-buffer buf) + (goto-char (point-max)) + (or (docstring-in-module module nil) + (insert "\n@c module " (prin1-to-string module) "\n")) + (insert "\n" (location-to-docstring (find-snarfed-docstring module + description)))))) + +;; Auto-update the specified docstring in the manual. +(defun docstring-auto-update-manual (module description) + (let ((manual-location (find-manual-docstring module description)) + (track-location (find-tracking-docstring module description))) + (save-excursion + (set-buffer (car manual-location)) + (goto-char (cadr manual-location)) + (delete-region (cadr manual-location) (caddr manual-location)) + (insert (location-to-docstring (find-snarfed-docstring module + description)))))) + +;; Process an alist of modules and descriptions, and produce a summary +;; buffer describing actions taken and issues to be resolved. +(defun docstring-process-alist (alist) + (let (check-needed-list + update-needed-list + consider-removal-list + added-to-manual-list + auto-updated-manual-list) + + (mapcar + (function (lambda (module-list) + (let ((module (car module-list))) + (message "Module: %S" module) + (mapcar + (function (lambda (description) + (message "Comparing docstring: %S: %s" module description) + (let* ((ai (docstring-compare module description)) + (action (car ai)) + (issue (cdr ai))) + + (cond ((eq action 'add-to-manual) + (docstring-add-to-manual module description) + (setq added-to-manual-list + (cons (cons module description) + added-to-manual-list))) + + ((eq action 'auto-update-manual) + (docstring-auto-update-manual module description) + (setq auto-updated-manual-list + (cons (cons module description) + auto-updated-manual-list)))) + + (cond ((eq issue 'check-needed) + (setq check-needed-list + (cons (cons module description) + check-needed-list))) + + ((eq issue 'update-needed) + (setq update-needed-list + (cons (cons module description) + update-needed-list))) + + ((eq issue 'consider-removal) + (setq consider-removal-list + (cons (cons module description) + consider-removal-list))))))) + (cdr module-list))))) + alist) + + ;; Prepare a buffer describing the results. + (set-buffer (get-buffer-create "*Docstring Results*")) + (erase-buffer) + + (insert " +The following items have been automatically added to the manual in +file `" docstring-manual-directory "/" docstring-new-docstrings-file "'.\n\n") + (if added-to-manual-list + (mapcar (function (lambda (moddesc) + (insert (prin1-to-string (car moddesc)) + ": " + (cdr moddesc) + "\n"))) + added-to-manual-list) + (insert "(none)\n")) + + (insert " +The following items have been automatically updated in the manual.\n\n") + (if auto-updated-manual-list + (mapcar (function (lambda (moddesc) + (insert (prin1-to-string (car moddesc)) + ": " + (cdr moddesc) + "\n"))) + auto-updated-manual-list) + (insert "(none)\n")) + + (insert " +The following items are already documented in the manual but are not +mentioned in the reference copy of the snarfed docstrings file. +You should check that the manual documentation matches the docstring +in the current snarfed docstrings file.\n\n") + (if check-needed-list + (mapcar (function (lambda (moddesc) + (insert (prin1-to-string (car moddesc)) + ": " + (cdr moddesc) + "\n"))) + check-needed-list) + (insert "(none)\n")) + + (insert " +The following items have manual documentation that is different from +the docstring in the reference copy of the snarfed docstrings file, +and the snarfed docstring has changed. You need to update the manual +documentation by hand with reference to the snarfed docstring changes.\n\n") + (if update-needed-list + (mapcar (function (lambda (moddesc) + (insert (prin1-to-string (car moddesc)) + ": " + (cdr moddesc) + "\n"))) + update-needed-list) + (insert "(none)\n")) + + (insert " +The following items are documented in the manual but are no longer +present in the snarfed docstrings file. You should consider whether +the existing manual documentation is still pertinent. If it is, its +docstring module comment may need updating, to connect it with a +new snarfed docstring file.\n\n") + (if consider-removal-list + (mapcar (function (lambda (moddesc) + (insert (prin1-to-string (car moddesc)) + ": " + (cdr moddesc) + "\n"))) + consider-removal-list) + (insert "(none)\n")) + (insert "\n") + + (goto-char (point-min)) + + ;; Popup the issues buffer. + (let ((pop-up-frames t)) + (set-window-point (display-buffer (current-buffer)) + (point-min))))) + +(defun docstring-process-current-buffer () + (interactive) + (docstring-process-alist (make-module-description-list))) + +(defun docstring-process-current-region (beg end) + (interactive "r") + (narrow-to-region beg end) + (unwind-protect + (save-excursion + (docstring-process-alist (make-module-description-list))) + (widen))) + +(defun docstring-process-module (module) + (interactive "xModule: ") + (let ((modpath (module-to-path module)) + (mdlist nil)) + (mapcar (function (lambda (root) + (let ((fn (concat root + "/" + modpath + ".texi"))) + (if (file-exists-p fn) + (save-excursion + (find-file fn) + (message "Getting docstring list from %s" fn) + (setq mdlist + (append mdlist + (make-module-description-list)))))))) + docstring-snarfed-roots) + (docstring-process-alist mdlist))) + +(defun docstring-ediff-this-line () + (interactive) + (let (module + description) + (save-excursion + (beginning-of-line) + (setq module (read (current-buffer))) + (forward-char 2) + (setq description (buffer-substring (point) + (progn + (end-of-line) + (point))))) + + (message "Ediff docstring: %S: %s" module description) + + (let ((track-location (or (find-tracking-docstring module description) + (docstring-temp-location "No docstring in tracking file"))) + (snarf-location (or (find-snarfed-docstring module description) + (docstring-temp-location "No docstring in snarfed file"))) + (manual-location (or (find-manual-docstring module description) + (docstring-temp-location "No docstring in manual")))) + + (setq docstring-ediff-buffers + (list (car track-location) + (car snarf-location) + (car manual-location))) + + (docstring-narrow-to-location track-location) + (docstring-narrow-to-location snarf-location) + (docstring-narrow-to-location manual-location) + + (add-hook 'ediff-quit-hook 'docstring-widen-ediff-buffers) + + (ediff-buffers3 (nth 0 docstring-ediff-buffers) + (nth 1 docstring-ediff-buffers) + (nth 2 docstring-ediff-buffers))))) + +(defun docstring-narrow-to-location (location) + (save-excursion + (set-buffer (car location)) + (narrow-to-region (cadr location) (caddr location)))) + +(defun docstring-temp-location (str) + (let ((buf (generate-new-buffer "*Docstring Temp*"))) + (save-excursion + (set-buffer buf) + (erase-buffer) + (insert str "\n") + (list buf (point-min) (point-max))))) + +(require 'ediff) + +(defvar docstring-ediff-buffers '()) + +(defun docstring-widen-ediff-buffers () + (remove-hook 'ediff-quit-hook 'docstring-widen-ediff-buffers) + (save-excursion + (mapcar (function (lambda (buffer) + (set-buffer buffer) + (widen))) + docstring-ediff-buffers))) + + +;;; Tests: + +;(find-docstring "/home/neil/Guile/cvs/guile-core/doc/maint/guile.texi" nil "primitive sloppy-assq") +;(find-manual-docstring '(guile) "primitive sloppy-assq") +;(find-tracking-docstring '(guile) "primitive sloppy-assq") +;(find-snarfed-docstring '(guile) "primitive sloppy-assq") + +(provide 'docstring) diff --git a/doc/maint/guile.texi b/doc/maint/guile.texi new file mode 100644 index 000000000..bb7dd4522 --- /dev/null +++ b/doc/maint/guile.texi @@ -0,0 +1,7087 @@ +@paragraphindent 0 + +acons +@c snarfed from alist.c:60 +@deffn primitive acons key value alist +Adds a new key-value pair to @var{alist}. A new pair is +created whose car is @var{key} and whose cdr is @var{value}, and the +pair is consed onto @var{alist}, and the new list is returned. This +function is @emph{not} destructive; @var{alist} is not modified. +@end deffn + +sloppy-assq +@c snarfed from alist.c:83 +@deffn primitive sloppy-assq key alist +Behaves like @code{assq} but does not do any error checking. +Recommended only for use in Guile internals. +@end deffn + +sloppy-assv +@c snarfed from alist.c:101 +@deffn primitive sloppy-assv key alist +Behaves like @code{assv} but does not do any error checking. +Recommended only for use in Guile internals. +@end deffn + +sloppy-assoc +@c snarfed from alist.c:119 +@deffn primitive sloppy-assoc key alist +Behaves like @code{assoc} but does not do any error checking. +Recommended only for use in Guile internals. +@end deffn + +assq +@c snarfed from alist.c:146 +@deffn primitive assq key alist +@deffnx primitive assv key alist +@deffnx primitive assoc key alist +Fetches the entry in @var{alist} that is associated with @var{key}. To +decide whether the argument @var{key} matches a particular entry in +@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv} +uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key} +cannot be found in @var{alist} (according to whichever equality +predicate is in use), then @code{#f} is returned. These functions +return the entire alist entry found (i.e. both the key and the value). +@end deffn + +assv +@c snarfed from alist.c:167 +@deffn primitive assv key alist +Behaves like @code{assq} but uses @code{eqv?} for key comparison. +@end deffn + +assoc +@c snarfed from alist.c:188 +@deffn primitive assoc key alist +Behaves like @code{assq} but uses @code{equal?} for key comparison. +@end deffn + +assq-ref +@c snarfed from alist.c:232 +@deffn primitive assq-ref alist key +@deffnx primitive assv-ref alist key +@deffnx primitive assoc-ref alist key +Like @code{assq}, @code{assv} and @code{assoc}, except that only the +value associated with @var{key} in @var{alist} is returned. These +functions are equivalent to + +@lisp +(let ((ent (@var{associator} @var{key} @var{alist}))) + (and ent (cdr ent))) +@end lisp + +where @var{associator} is one of @code{assq}, @code{assv} or @code{assoc}. +@end deffn + +assv-ref +@c snarfed from alist.c:249 +@deffn primitive assv-ref alist key +Behaves like @code{assq-ref} but uses @code{eqv?} for key comparison. +@end deffn + +assoc-ref +@c snarfed from alist.c:266 +@deffn primitive assoc-ref alist key +Behaves like @code{assq-ref} but uses @code{equal?} for key comparison. +@end deffn + +assq-set! +@c snarfed from alist.c:295 +@deffn primitive assq-set! alist key val +@deffnx primitive assv-set! alist key value +@deffnx primitive assoc-set! alist key value +Reassociate @var{key} in @var{alist} with @var{value}: find any existing +@var{alist} entry for @var{key} and associate it with the new +@var{value}. If @var{alist} does not contain an entry for @var{key}, +add a new one. Return the (possibly new) alist. + +These functions do not attempt to verify the structure of @var{alist}, +and so may cause unusual results if passed an object that is not an +association list. +@end deffn + +assv-set! +@c snarfed from alist.c:313 +@deffn primitive assv-set! alist key val +Behaves like @code{assq-set!} but uses @code{eqv?} for key comparison. +@end deffn + +assoc-set! +@c snarfed from alist.c:331 +@deffn primitive assoc-set! alist key val +Behaves like @code{assq-set!} but uses @code{equal?} for key comparison. +@end deffn + +assq-remove! +@c snarfed from alist.c:355 +@deffn primitive assq-remove! alist key +@deffnx primitive assv-remove! alist key +@deffnx primitive assoc-remove! alist key +Delete the first entry in @var{alist} associated with @var{key}, and return +the resulting alist. +@end deffn + +assv-remove! +@c snarfed from alist.c:371 +@deffn primitive assv-remove! alist key +Behaves like @code{assq-remove!} but uses @code{eqv?} for key comparison. +@end deffn + +assoc-remove! +@c snarfed from alist.c:387 +@deffn primitive assoc-remove! alist key +Behaves like @code{assq-remove!} but uses @code{equal?} for key comparison. +@end deffn + +make-arbiter +@c snarfed from arbiters.c:84 +@deffn primitive make-arbiter name +Return an object of type arbiter and name @var{name}. Its +state is initially unlocked. Arbiters are a way to achieve +process synchronization. +@end deffn + +try-arbiter +@c snarfed from arbiters.c:94 +@deffn primitive try-arbiter arb +Return @code{#t} and lock the arbiter @var{arb} if the arbiter +was unlocked. Otherwise, return @code{#f}. +@end deffn + +release-arbiter +@c snarfed from arbiters.c:115 +@deffn primitive release-arbiter arb +Return @code{#t} and unlock the arbiter @var{arb} if the +arbiter was locked. Otherwise, return @code{#f}. +@end deffn + +async +@c snarfed from async.c:290 +@deffn primitive async thunk +Create a new async for the procedure @var{thunk}. +@end deffn + +system-async +@c snarfed from async.c:300 +@deffn primitive system-async thunk +Create a new async for the procedure @var{thunk}. Also +add it to the system's list of active async objects. +@end deffn + +async-mark +@c snarfed from async.c:317 +@deffn primitive async-mark a +Mark the async @var{a} for future execution. +@end deffn + +system-async-mark +@c snarfed from async.c:333 +@deffn primitive system-async-mark a +Mark the async @var{a} for future execution. +@end deffn + +run-asyncs +@c snarfed from async.c:353 +@deffn primitive run-asyncs list_of_a +Execute all thunks from the asyncs of the list @var{list_of_a}. +@end deffn + +noop +@c snarfed from async.c:387 +@deffn primitive noop . args +Do nothing. When called without arguments, return @code{#f}, +otherwise return the first argument. +@end deffn + +unmask-signals +@c snarfed from async.c:439 +@deffn primitive unmask-signals +Unmask signals. The returned value is not specified. +@end deffn + +mask-signals +@c snarfed from async.c:450 +@deffn primitive mask-signals +Mask signals. The returned value is not specified. +@end deffn + +display-error +@c snarfed from backtrace.c:262 +@deffn primitive display-error stack port subr message args rest +Display an error message to the output port @var{port}. +@var{stack} is the saved stack for the error, @var{subr} is +the name of the procedure in which the error occured and +@var{message} is the actual error message, which may contain +formatting instructions. These will format the arguments in +the list @var{args} accordingly. @var{rest} is currently +ignored. +@end deffn + +display-application +@c snarfed from backtrace.c:399 +@deffn primitive display-application frame [port [indent]] +Display a procedure application @var{frame} to the output port +@var{port}. @var{indent} specifies the indentation of the +output. +@end deffn + +display-backtrace +@c snarfed from backtrace.c:617 +@deffn primitive display-backtrace stack port [first [depth]] +Display a backtrace to the output port @var{port}. @var{stack} +is the stack to take the backtrace from, @var{first} specifies +where in the stack to start and @var{depth} how much frames +to display. Both @var{first} and @var{depth} can be @code{#f}, +which means that default values will be used. +@end deffn + +backtrace +@c snarfed from backtrace.c:640 +@deffn primitive backtrace +Display a backtrace of the stack saved by the last error +to the current output port. +@end deffn + +not +@c snarfed from boolean.c:56 +@deffn primitive not x +Return @code{#t} iff @var{x} is @code{#f}, else return @code{#f}. +@end deffn + +boolean? +@c snarfed from boolean.c:66 +@deffn primitive boolean? obj +Return @code{#t} iff @var{obj} is either @code{#t} or @code{#f}. +@end deffn + +char? +@c snarfed from chars.c:56 +@deffn primitive char? x +Return @code{#t} iff @var{x} is a character, else @code{#f}. +@end deffn + +char=? +@c snarfed from chars.c:65 +@deffn primitive char=? x y +Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}. +@end deffn + +char<? +@c snarfed from chars.c:78 +@deffn primitive char<? x y +Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence, +else @code{#f}. +@end deffn + +char<=? +@c snarfed from chars.c:90 +@deffn primitive char<=? x y +Return @code{#t} iff @var{x} is less than or equal to @var{y} in the +ASCII sequence, else @code{#f}. +@end deffn + +char>? +@c snarfed from chars.c:102 +@deffn primitive char>? x y +Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII +sequence, else @code{#f}. +@end deffn + +char>=? +@c snarfed from chars.c:114 +@deffn primitive char>=? x y +Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the +ASCII sequence, else @code{#f}. +@end deffn + +char-ci=? +@c snarfed from chars.c:126 +@deffn primitive char-ci=? x y +Return @code{#t} iff @var{x} is the same character as @var{y} ignoring +case, else @code{#f}. +@end deffn + +char-ci<? +@c snarfed from chars.c:138 +@deffn primitive char-ci<? x y +Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence +ignoring case, else @code{#f}. +@end deffn + +char-ci<=? +@c snarfed from chars.c:150 +@deffn primitive char-ci<=? x y +Return @code{#t} iff @var{x} is less than or equal to @var{y} in the +ASCII sequence ignoring case, else @code{#f}. +@end deffn + +char-ci>? +@c snarfed from chars.c:162 +@deffn primitive char-ci>? x y +Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII +sequence ignoring case, else @code{#f}. +@end deffn + +char-ci>=? +@c snarfed from chars.c:174 +@deffn primitive char-ci>=? x y +Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the +ASCII sequence ignoring case, else @code{#f}. +@end deffn + +char-alphabetic? +@c snarfed from chars.c:187 +@deffn primitive char-alphabetic? chr +Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. +Alphabetic means the same thing as the isalpha C library function. +@end deffn + +char-numeric? +@c snarfed from chars.c:198 +@deffn primitive char-numeric? chr +Return @code{#t} iff @var{chr} is numeric, else @code{#f}. +Numeric means the same thing as the isdigit C library function. +@end deffn + +char-whitespace? +@c snarfed from chars.c:209 +@deffn primitive char-whitespace? chr +Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. +Whitespace means the same thing as the isspace C library function. +@end deffn + +char-upper-case? +@c snarfed from chars.c:222 +@deffn primitive char-upper-case? chr +Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. +Uppercase means the same thing as the isupper C library function. +@end deffn + +char-lower-case? +@c snarfed from chars.c:234 +@deffn primitive char-lower-case? chr +Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. +Lowercase means the same thing as the islower C library function. +@end deffn + +char-is-both? +@c snarfed from chars.c:248 +@deffn primitive char-is-both? chr +Return @code{#t} iff @var{chr} is either uppercase or lowercase, else @code{#f}. +Uppercase and lowercase are as defined by the isupper and islower +C library functions. +@end deffn + +char->integer +@c snarfed from chars.c:262 +@deffn primitive char->integer chr +Return the number corresponding to ordinal position of @var{chr} in the +ASCII sequence. +@end deffn + +integer->char +@c snarfed from chars.c:274 +@deffn primitive integer->char n +Return the character at position @var{n} in the ASCII sequence. +@end deffn + +char-upcase +@c snarfed from chars.c:285 +@deffn primitive char-upcase chr +Return the uppercase character version of @var{chr}. +@end deffn + +char-downcase +@c snarfed from chars.c:296 +@deffn primitive char-downcase chr +Return the lowercase character version of @var{chr}. +@end deffn + +debug-options-interface +@c snarfed from debug.c:80 +@deffn primitive debug-options-interface [setting] +Option interface for the debug options. Instead of using +this procedure directly, use the procedures @code{debug-enable}, +@code{debug-disable}, @code{debug-set!} and @var{debug-options}. +@end deffn + +with-traps +@c snarfed from debug.c:128 +@deffn primitive with-traps thunk +Call @var{thunk} with traps enabled. +@end deffn + +memoized? +@c snarfed from debug.c:170 +@deffn primitive memoized? obj +Return @code{#t} if @var{obj} is memoized. +@end deffn + +unmemoize +@c snarfed from debug.c:376 +@deffn primitive unmemoize m +Unmemoize the memoized expression @var{m}, +@end deffn + +memoized-environment +@c snarfed from debug.c:386 +@deffn primitive memoized-environment m +Return the environment of the memoized expression @var{m}. +@end deffn + +procedure-name +@c snarfed from debug.c:396 +@deffn primitive procedure-name proc +Return the name of the procedure @var{proc} +@end deffn + +procedure-source +@c snarfed from debug.c:422 +@deffn primitive procedure-source proc +Return the source of the procedure @var{proc}. +@end deffn + +procedure-environment +@c snarfed from debug.c:456 +@deffn primitive procedure-environment proc +Return the environment of the procedure @var{proc}. +@end deffn + +local-eval +@c snarfed from debug.c:488 +@deffn primitive local-eval exp [env] +Evaluate @var{exp} in its environment. If @var{env} is supplied, +it is the environment in which to evaluate @var{exp}. Otherwise, +@var{exp} must be a memoized code object (in which case, its environment +is implicit). +@end deffn + +debug-object? +@c snarfed from debug.c:576 +@deffn primitive debug-object? obj +Return @code{#t} if @var{obj} is a debug object. +@end deffn + +c-registered-modules +@c snarfed from dynl.c:183 +@deffn primitive c-registered-modules +Return a list of the object code modules that have been imported into +the current Guile process. Each element of the list is a pair whose +car is the name of the module, and whose cdr is the function handle +for that module's initializer function. The name is the string that +has been passed to scm_register_module_xxx. +@end deffn + +c-clear-registered-modules +@c snarfed from dynl.c:204 +@deffn primitive c-clear-registered-modules +Destroy the list of modules registered with the current Guile process. +The return value is unspecified. @strong{Warning:} this function does +not actually unlink or deallocate these modules, but only destroys the +records of which modules have been loaded. It should therefore be used +only by module bookkeeping operations. +@end deffn + +dynamic-link +@c snarfed from dynl.c:356 +@deffn primitive dynamic-link fname +Open the dynamic library @var{library-file}. A library handle +representing the opened library is returned; this handle should be used +as the @var{lib} argument to the following functions. +@end deffn + +dynamic-object? +@c snarfed from dynl.c:372 +@deffn primitive dynamic-object? obj +Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f} +otherwise. +@end deffn + +dynamic-unlink +@c snarfed from dynl.c:388 +@deffn primitive dynamic-unlink dobj +Unlink the library represented by @var{library-handle}, +and remove any imported symbols from the address space. +GJB:FIXME:DOC: 2nd version below: +Unlink the indicated object file from the application. The +argument @var{dynobj} must have been obtained by a call to +@code{dynamic-link}. After @code{dynamic-unlink} has been +called on @var{dynobj}, its content is no longer accessible. +@end deffn + +dynamic-func +@c snarfed from dynl.c:415 +@deffn primitive dynamic-func name dobj +Search the dynamic object @var{dobj} for the C function +indicated by the string @var{name} and return some Scheme +handle that can later be used with @code{dynamic-call} to +actually call the function. + +Regardless whether your C compiler prepends an underscore @samp{_} to +the global names in a program, you should @strong{not} include this +underscore in @var{function}. Guile knows whether the underscore is +needed or not and will add it when necessary. +@end deffn + +dynamic-call +@c snarfed from dynl.c:460 +@deffn primitive dynamic-call func dobj +Call @var{lib-thunk}, a procedure of no arguments. If @var{lib-thunk} +is a string, it is assumed to be a symbol found in the dynamic library +@var{lib} and is fetched with @code{dynamic-func}. Otherwise, it should +be a function handle returned by a previous call to @code{dynamic-func}. +The return value is unspecified. +GJB:FIXME:DOC 2nd version below +Call the C function indicated by @var{function} and @var{dynobj}. The +function is passed no arguments and its return value is ignored. When +@var{function} is something returned by @code{dynamic-func}, call that +function and ignore @var{dynobj}. When @var{function} is a string (or +symbol, etc.), look it up in @var{dynobj}; this is equivalent to + +@smallexample +(dynamic-call (dynamic-func @var{function} @var{dynobj} #f)) +@end smallexample + +Interrupts are deferred while the C function is executing (with +@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). +@end deffn + +dynamic-args-call +@c snarfed from dynl.c:494 +@deffn primitive dynamic-args-call func dobj args +Call @var{proc}, a dynamically loaded function, passing it the argument +list @var{args} (a list of strings). As with @code{dynamic-call}, +@var{proc} should be either a function handle or a string, in which case +it is first fetched from @var{lib} with @code{dynamic-func}. + +@var{proc} is assumed to return an integer, which is used as the return +value from @code{dynamic-args-call}. + +GJB:FIXME:DOC 2nd version below +Call the C function indicated by @var{function} and @var{dynobj}, just +like @code{dynamic-call}, but pass it some arguments and return its +return value. The C function is expected to take two arguments and +return an @code{int}, just like @code{main}: + +@smallexample +int c_func (int argc, char **argv); +@end smallexample + +The parameter @var{args} must be a list of strings and is converted into +an array of @code{char *}. The array is passed in @var{argv} and its +size in @var{argc}. The return value is converted to a Scheme number +and returned from the call to @code{dynamic-args-call}. +@end deffn + +dynamic-wind +@c snarfed from dynwind.c:115 +@deffn primitive dynamic-wind thunk1 thunk2 thunk3 +All three arguments must be 0-argument procedures. + +@var{in-guard} is called, then @var{thunk}, then @var{out-guard}. + +If, any time during the execution of @var{thunk}, the continuation +of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard} +is called. If the continuation of the dynamic-wind is re-entered, +@var{in-guard} is called. Thus @var{in-guard} and @var{out-guard} may +be called any number of times. + +@example +(define x 'normal-binding) +@result{} x + +(define a-cont (call-with-current-continuation + (lambda (escape) + (let ((old-x x)) + (dynamic-wind + ;; in-guard: + ;; + (lambda () (set! x 'special-binding)) + + ;; thunk + ;; + (lambda () (display x) (newline) + (call-with-current-continuation escape) + (display x) (newline) + x) + + ;; out-guard: + ;; + (lambda () (set! x old-x))))))) + +;; Prints: +special-binding +;; Evaluates to: +@result{} a-cont + +x +@result{} normal-binding + +(a-cont #f) +;; Prints: +special-binding +;; Evaluates to: +@result{} a-cont ;; the value of the (define a-cont...) + +x +@result{} normal-binding + +a-cont +@result{} special-binding +@end example +@end deffn + +environment? +@c snarfed from environments.c:135 +@deffn primitive environment? obj +Return @code{#t} if @var{obj} is an environment, or @code{#f} +otherwise. +@end deffn + +environment-bound? +@c snarfed from environments.c:146 +@deffn primitive environment-bound? env sym +Return @code{#t} if @var{sym} is bound in @var{env}, or +@code{#f} otherwise. +@end deffn + +environment-ref +@c snarfed from environments.c:161 +@deffn primitive environment-ref env sym +Return the value of the location bound to @var{sym} in +@var{env}. If @var{sym} is unbound in @var{env}, signal an +@code{environment:unbound} error. +@end deffn + +environment-fold +@c snarfed from environments.c:231 +@deffn primitive environment-fold env proc init +Iterate over all the bindings in @var{env}, accumulating some +value. +For each binding in @var{env}, apply @var{proc} to the symbol +bound, its value, and the result from the previous application +of @var{proc}. +Use @var{init} as @var{proc}'s third argument the first time +@var{proc} is applied. +If @var{env} contains no bindings, this function simply returns +@var{init}. +If @var{env} binds the symbol sym1 to the value val1, sym2 to +val2, and so on, then this procedure computes: +@example + (proc sym1 val1 + (proc sym2 val2 + ... + (proc symn valn + init))) +@end example +Each binding in @var{env} will be processed exactly once. +@code{environment-fold} makes no guarantees about the order in +which the bindings are processed. +Here is a function which, given an environment, constructs an +association list representing that environment's bindings, +using environment-fold: +@example + (define (environment->alist env) + (environment-fold env + (lambda (sym val tail) + (cons (cons sym val) tail)) + '())) +@end example +@end deffn + +environment-define +@c snarfed from environments.c:266 +@deffn primitive environment-define env sym val +Bind @var{sym} to a new location containing @var{val} in +@var{env}. If @var{sym} is already bound to another location +in @var{env} and the binding is mutable, that binding is +replaced. The new binding and location are both mutable. The +return value is unspecified. +If @var{sym} is already bound in @var{env}, and the binding is +immutable, signal an @code{environment:immutable-binding} error. +@end deffn + +environment-undefine +@c snarfed from environments.c:292 +@deffn primitive environment-undefine env sym +Remove any binding for @var{sym} from @var{env}. If @var{sym} +is unbound in @var{env}, do nothing. The return value is +unspecified. +If @var{sym} is already bound in @var{env}, and the binding is +immutable, signal an @code{environment:immutable-binding} error. +@end deffn + +environment-set! +@c snarfed from environments.c:320 +@deffn primitive environment-set! env sym val +If @var{env} binds @var{sym} to some location, change that +location's value to @var{val}. The return value is +unspecified. +If @var{sym} is not bound in @var{env}, signal an +@code{environment:unbound} error. If @var{env} binds @var{sym} +to an immutable location, signal an +@code{environment:immutable-location} error. +@end deffn + +environment-cell +@c snarfed from environments.c:355 +@deffn primitive environment-cell env sym for_write +Return the value cell which @var{env} binds to @var{sym}, or +@code{#f} if the binding does not live in a value cell. +The argument @var{for-write} indicates whether the caller +intends to modify the variable's value by mutating the value +cell. If the variable is immutable, then +@code{environment-cell} signals an +@code{environment:immutable-location} error. +If @var{sym} is unbound in @var{env}, signal an +@code{environment:unbound} error. +If you use this function, you should consider using +@code{environment-observe}, to be notified when @var{sym} gets +re-bound to a new value cell, or becomes undefined. +@end deffn + +environment-observe +@c snarfed from environments.c:407 +@deffn primitive environment-observe env proc +Whenever @var{env}'s bindings change, apply @var{proc} to +@var{env}. +This function returns an object, token, which you can pass to +@code{environment-unobserve} to remove @var{proc} from the set +of procedures observing @var{env}. The type and value of +token is unspecified. +@end deffn + +environment-observe-weak +@c snarfed from environments.c:424 +@deffn primitive environment-observe-weak env proc +This function is the same as environment-observe, except that +the reference @var{env} retains to @var{proc} is a weak +reference. This means that, if there are no other live, +non-weak references to @var{proc}, it will be +garbage-collected, and dropped from @var{env}'s +list of observing procedures. +@end deffn + +environment-unobserve +@c snarfed from environments.c:460 +@deffn primitive environment-unobserve token +Cancel the observation request which returned the value +@var{token}. The return value is unspecified. +If a call @code{(environment-observe env proc)} returns +@var{token}, then the call @code{(environment-unobserve token)} +will cause @var{proc} to no longer be called when @var{env}'s +bindings change. +@end deffn + +make-leaf-environment +@c snarfed from environments.c:1040 +@deffn primitive make-leaf-environment +Create a new leaf environment, containing no bindings. +All bindings and locations created in the new environment +will be mutable. +@end deffn + +leaf-environment? +@c snarfed from environments.c:1063 +@deffn primitive leaf-environment? object +Return @code{#t} if object is a leaf environment, or @code{#f} +otherwise. +@end deffn + +make-eval-environment +@c snarfed from environments.c:1429 +@deffn primitive make-eval-environment local imported +Return a new environment object eval whose bindings are the +union of the bindings in the environments @var{local} and +@var{imported}, with bindings from @var{local} taking +precedence. Definitions made in eval are placed in @var{local}. +Applying @code{environment-define} or +@code{environment-undefine} to eval has the same effect as +applying the procedure to @var{local}. +Note that eval incorporates @var{local} and @var{imported} by +reference: +If, after creating eval, the program changes the bindings of +@var{local} or @var{imported}, those changes will be visible +in eval. +Since most Scheme evaluation takes place in eval environments, +they transparently cache the bindings received from @var{local} +and @var{imported}. Thus, the first time the program looks up +a symbol in eval, eval may make calls to @var{local} or +@var{imported} to find their bindings, but subsequent +references to that symbol will be as fast as references to +bindings in finite environments. +In typical use, @var{local} will be a finite environment, and +@var{imported} will be an import environment +@end deffn + +eval-environment? +@c snarfed from environments.c:1466 +@deffn primitive eval-environment? object +Return @code{#t} if object is an eval environment, or @code{#f} +otherwise. +@end deffn + +eval-environment-local +@c snarfed from environments.c:1476 +@deffn primitive eval-environment-local env +Return the local environment of eval environment @var{env}. +@end deffn + +eval-environment-set-local! +@c snarfed from environments.c:1488 +@deffn primitive eval-environment-set-local! env local +Change @var{env}'s local environment to @var{local}. +@end deffn + +eval-environment-imported +@c snarfed from environments.c:1514 +@deffn primitive eval-environment-imported env +Return the imported environment of eval environment @var{env}. +@end deffn + +eval-environment-set-imported! +@c snarfed from environments.c:1526 +@deffn primitive eval-environment-set-imported! env imported +Change @var{env}'s imported environment to @var{imported}. +@end deffn + +make-import-environment +@c snarfed from environments.c:1846 +@deffn primitive make-import-environment imports conflict_proc +Return a new environment @var{imp} whose bindings are the union +of the bindings from the environments in @var{imports}; +@var{imports} must be a list of environments. That is, +@var{imp} binds a symbol to a location when some element of +@var{imports} does. +If two different elements of @var{imports} have a binding for +the same symbol, the @var{conflict-proc} is called with the +following parameters: the import environment, the symbol and +the list of the imported environments that bind the symbol. +If the @var{conflict-proc} returns an environment @var{env}, +the conflict is considered as resolved and the binding from +@var{env} is used. If the @var{conflict-proc} returns some +non-environment object, the conflict is considered unresolved +and the symbol is treated as unspecified in the import +environment. +The checking for conflicts may be performed lazily, i. e. at +the moment when a value or binding for a certain symbol is +requested instead of the moment when the environment is +created or the bindings of the imports change. +All bindings in @var{imp} are immutable. If you apply +@code{environment-define} or @code{environment-undefine} to +@var{imp}, Guile will signal an + @code{environment:immutable-binding} error. However, +notice that the set of bindings in @var{imp} may still change, +if one of its imported environments changes. +@end deffn + +import-environment? +@c snarfed from environments.c:1875 +@deffn primitive import-environment? object +Return @code{#t} if object is an import environment, or +@code{#f} otherwise. +@end deffn + +import-environment-imports +@c snarfed from environments.c:1886 +@deffn primitive import-environment-imports env +Return the list of environments imported by the import +environment @var{env}. +@end deffn + +import-environment-set-imports! +@c snarfed from environments.c:1899 +@deffn primitive import-environment-set-imports! env imports +Change @var{env}'s list of imported environments to +@var{imports}, and check for conflicts. +@end deffn + +make-export-environment +@c snarfed from environments.c:2164 +@deffn primitive make-export-environment private signature +Return a new environment @var{exp} containing only those +bindings in private whose symbols are present in +@var{signature}. The @var{private} argument must be an +environment. + +The environment @var{exp} binds symbol to location when +@var{env} does, and symbol is exported by @var{signature}. + +@var{signature} is a list specifying which of the bindings in +@var{private} should be visible in @var{exp}. Each element of +@var{signature} should be a list of the form: + (symbol attribute ...) +where each attribute is one of the following: +@table @asis +@item the symbol @code{mutable-location} + @var{exp} should treat the + location bound to symbol as mutable. That is, @var{exp} + will pass calls to @code{environment-set!} or + @code{environment-cell} directly through to private. +@item the symbol @code{immutable-location} + @var{exp} should treat + the location bound to symbol as immutable. If the program + applies @code{environment-set!} to @var{exp} and symbol, or + calls @code{environment-cell} to obtain a writable value + cell, @code{environment-set!} will signal an + @code{environment:immutable-location} error. Note that, even + if an export environment treats a location as immutable, the + underlying environment may treat it as mutable, so its + value may change. +@end table +It is an error for an element of signature to specify both +@code{mutable-location} and @code{immutable-location}. If +neither is specified, @code{immutable-location} is assumed. + +As a special case, if an element of signature is a lone +symbol @var{sym}, it is equivalent to an element of the form +@code{(sym)}. + +All bindings in @var{exp} are immutable. If you apply +@code{environment-define} or @code{environment-undefine} to +@var{exp}, Guile will signal an +@code{environment:immutable-binding} error. However, +notice that the set of bindings in @var{exp} may still change, +if the bindings in private change. +@end deffn + +export-environment? +@c snarfed from environments.c:2199 +@deffn primitive export-environment? object +Return @code{#t} if object is an export environment, or +@code{#f} otherwise. +@end deffn + +export-environment-private +@c snarfed from environments.c:2209 +@deffn primitive export-environment-private env +Return the private environment of export environment @var{env}. +@end deffn + +export-environment-set-private! +@c snarfed from environments.c:2221 +@deffn primitive export-environment-set-private! env private +Change the private environment of export environment @var{env}. +@end deffn + +export-environment-signature +@c snarfed from environments.c:2243 +@deffn primitive export-environment-signature env +Return the signature of export environment @var{env}. +@end deffn + +export-environment-set-signature! +@c snarfed from environments.c:2317 +@deffn primitive export-environment-set-signature! env signature +Change the signature of export environment @var{env}. +@end deffn + +eq? +@c snarfed from eq.c:64 +@deffn primitive eq? x y +Return @code{#t} iff @var{x} references the same object as @var{y}. +@code{eq?} is similar to @code{eqv?} except that in some cases it is +capable of discerning distinctions finer than those detectable by +@code{eqv?}. +@end deffn + +eqv? +@c snarfed from eq.c:78 +@deffn primitive eqv? x y +The @code{eqv?} procedure defines a useful equivalence relation on objects. +Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be +regarded as the same object. This relation is left slightly open to +interpretation, but works for comparing immediate integers, characters, +and inexact numbers. +@end deffn + +equal? +@c snarfed from eq.c:127 +@deffn primitive equal? x y +Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent. +@code{equal?} recursively compares the contents of pairs, +vectors, and strings, applying @code{eqv?} on other objects such as +numbers and symbols. A rule of thumb is that objects are generally +@code{equal?} if they print the same. @code{equal?} may fail to +terminate if its arguments are circular data structures. +@end deffn + +scm-error +@c snarfed from error.c:112 +@deffn primitive scm-error key subr message args rest +Raise an error with key @var{key}. @var{subr} can be a string naming +the procedure associated with the error, or @code{#f}. @var{message} +is the error message string, possibly containing @code{~S} and @code{~A} +escapes. When an error is reported, these are replaced by formating the +corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display} +and @code{~S} (was @code{%S}) formats using @code{write}. @var{data} is a +list or @code{#f} depending on @var{key}: if @var{key} is +@code{system-error} then it should be a list +containing the Unix @code{errno} value; If @var{key} is @code{signal} then +it should be a list containing the Unix signal number; otherwise it +will usually be @code{#f}. +@end deffn + +strerror +@c snarfed from error.c:153 +@deffn primitive strerror err +Returns the Unix error message corresponding to @var{err}, an integer. +@end deffn + +apply:nconc2last +@c snarfed from eval.c:3221 +@deffn primitive apply:nconc2last lst +Given a list (@var{arg1} @dots{} @var{args}), this function +conses the @var{arg1} @dots{} arguments onto the front of +@var{args}, and returns the resulting list. Note that +@var{args} is a list; thus, the argument to this function is +a list whose last element is a list. +Note: Rather than do new consing, @code{apply:nconc2last} +destroys its argument, so use with care. +@end deffn + +force +@c snarfed from eval.c:3754 +@deffn primitive force x +If the promise @var{x} has not been computed yet, compute and +return @var{x}, otherwise just return the previously computed +value. +@end deffn + +promise? +@c snarfed from eval.c:3777 +@deffn primitive promise? obj +Return true if @var{obj} is a promise, i.e. a delayed computation +(@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}). +@end deffn + +cons-source +@c snarfed from eval.c:3789 +@deffn primitive cons-source xorig x y +Create and return a new pair whose car and cdr are @var{x} and @var{y}. +Any source properties associated with @var{xorig} are also associated +with the new pair. +@end deffn + +copy-tree +@c snarfed from eval.c:3811 +@deffn primitive copy-tree obj +Recursively copy the data tree that is bound to @var{obj}, and return a +pointer to the new data structure. @code{copy-tree} recurses down the +contents of both pairs and vectors (since both cons cells and vector +cells may point to arbitrary objects), and stops recursing when it hits +any other object. +@end deffn + +primitive-eval +@c snarfed from eval.c:3912 +@deffn primitive primitive-eval exp +Evaluate @var{exp} in the top-level environment specified by +the current module. +@end deffn + +eval +@c snarfed from eval.c:3977 +@deffn primitive eval exp module +Evaluate @var{exp}, a list representing a Scheme expression, +in the top-level environment specified by @var{module}. +While @var{exp} is evaluated (using @var{primitive-eval}), +@var{module} is made the current module. The current module +is reset to its previous value when @var{eval} returns. +@end deffn + +eval2 +@c snarfed from eval.c:4020 +@deffn primitive eval2 obj env_thunk +Evaluate @var{exp}, a Scheme expression, in the environment +designated by @var{lookup}, a symbol-lookup function." +Do not use this version of eval, it does not play well +with the module system. Use @code{eval} or +@code{primitive-eval} instead. +@end deffn + +eval-options-interface +@c snarfed from eval.c:1685 +@deffn primitive eval-options-interface [setting] +Option interface for the evaluation options. Instead of using +this procedure directly, use the procedures @code{eval-enable}, +@code{eval-disable}, @code{eval-set!} and @var{eval-options}. +@end deffn + +evaluator-traps-interface +@c snarfed from eval.c:1702 +@deffn primitive evaluator-traps-interface [setting] +Option interface for the evaluator trap options. +@end deffn + +defined? +@c snarfed from evalext.c:74 +@deffn primitive defined? sym [env] +Return @code{#t} if @var{sym} is defined in the top-level environment. +@end deffn + +map-in-order +@c snarfed from evalext.c:146 +@deffn primitive map-in-order +scm_map +@end deffn + +program-arguments +@c snarfed from feature.c:79 +@deffn primitive program-arguments +@deffnx procedure command-line +Return the list of command line arguments passed to Guile, as a list of +strings. The list includes the invoked program name, which is usually +@code{"guile"}, but excludes switches and parameters for command line +options like @code{-e} and @code{-l}. +@end deffn + +chown +@c snarfed from filesys.c:140 +@deffn primitive chown object owner group +Change the ownership and group of the file referred to by @var{object} to +the integer values @var{owner} and @var{group}. @var{object} can be +a string containing a file name or, if the platform +supports fchown, a port or integer file descriptor +which is open on the file. The return value +is unspecified. + +If @var{object} is a symbolic link, either the +ownership of the link or the ownership of the referenced file will be +changed depending on the operating system (lchown is +unsupported at present). If @var{owner} or @var{group} is specified +as @code{-1}, then that ID is not changed. +@end deffn + +chmod +@c snarfed from filesys.c:180 +@deffn primitive chmod object mode +Changes the permissions of the file referred to by @var{obj}. +@var{obj} can be a string containing a file name or a port or integer file +descriptor which is open on a file (in which case @code{fchmod} is used +as the underlying system call). +@var{mode} specifies +the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}. +The return value is unspecified. +@end deffn + +umask +@c snarfed from filesys.c:214 +@deffn primitive umask [mode] +If @var{mode} is omitted, retuns a decimal number representing the current +file creation mask. Otherwise the file creation mask is set to +@var{mode} and the previous value is returned. + +E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18. +@end deffn + +open-fdes +@c snarfed from filesys.c:237 +@deffn primitive open-fdes path flags [mode] +Similar to @code{open} but returns a file descriptor instead of a +port. +@end deffn + +open +@c snarfed from filesys.c:280 +@deffn primitive open path flags [mode] +Open the file named by @var{path} for reading and/or writing. +@var{flags} is an integer specifying how the file should be opened. +@var{mode} is an integer specifying the permission bits of the file, if +it needs to be created, before the umask is applied. The default is 666 +(Unix itself has no default). + +@var{flags} can be constructed by combining variables using @code{logior}. +Basic flags are: + +@defvar O_RDONLY +Open the file read-only. +@end defvar +@defvar O_WRONLY +Open the file write-only. +@end defvar +@defvar O_RDWR +Open the file read/write. +@end defvar +@defvar O_APPEND +Append to the file instead of truncating. +@end defvar +@defvar O_CREAT +Create the file if it does not already exist. +@end defvar + +See the Unix documentation of the @code{open} system call +for additional flags. +@end deffn + +close +@c snarfed from filesys.c:318 +@deffn primitive close fd_or_port +Similar to close-port (@pxref{Generic Port Operations, close-port}), +but also works on file descriptors. A side +effect of closing a file descriptor is that any ports using that file +descriptor are moved to a different file descriptor and have +their revealed counts set to zero. +@end deffn + +close-fdes +@c snarfed from filesys.c:346 +@deffn primitive close-fdes fd +A simple wrapper for the @code{close} system call. +Close file descriptor @var{fd}, which must be an integer. +Unlike close (@pxref{Ports and File Descriptors, close}), +the file descriptor will be closed even if a port is using it. +The return value is unspecified. +@end deffn + +stat +@c snarfed from filesys.c:518 +@deffn primitive stat object +Returns an object containing various information +about the file determined by @var{obj}. +@var{obj} can be a string containing a file name or a port or integer file +descriptor which is open on a file (in which case @code{fstat} is used +as the underlying system call). + +The object returned by @code{stat} can be passed as a single parameter +to the following procedures, all of which return integers: + +@table @code +@item stat:dev +The device containing the file. +@item stat:ino +The file serial number, which distinguishes this file from all other +files on the same device. +@item stat:mode +The mode of the file. This includes file type information +and the file permission bits. See @code{stat:type} and @code{stat:perms} +below. +@item stat:nlink +The number of hard links to the file. +@item stat:uid +The user ID of the file's owner. +@item stat:gid +The group ID of the file. +@item stat:rdev +Device ID; this entry is defined only for character or block +special files. +@item stat:size +The size of a regular file in bytes. +@item stat:atime +The last access time for the file. +@item stat:mtime +The last modification time for the file. +@item stat:ctime +The last modification time for the attributes of the file. +@item stat:blksize +The optimal block size for reading or writing the file, in bytes. +@item stat:blocks +The amount of disk space that the file occupies measured in units of +512 byte blocks. +@end table + +In addition, the following procedures return the information +from stat:mode in a more convenient form: + +@table @code +@item stat:type +A symbol representing the type of file. Possible values are +regular, directory, symlink, block-special, char-special, +fifo, socket and unknown +@item stat:perms +An integer representing the access permission bits. +@end table +@end deffn + +link +@c snarfed from filesys.c:564 +@deffn primitive link oldpath newpath +Creates a new name @var{newpath} in the file system for the +file named by @var{oldpath}. If @var{oldpath} is a symbolic +link, the link may or may not be followed depending on the +system. +@end deffn + +rename-file +@c snarfed from filesys.c:586 +@deffn primitive rename-file oldname newname +Renames the file specified by @var{oldname} to @var{newname}. +The return value is unspecified. +@end deffn + +delete-file +@c snarfed from filesys.c:615 +@deffn primitive delete-file str +Deletes (or "unlinks") the file specified by @var{path}. +@end deffn + +mkdir +@c snarfed from filesys.c:634 +@deffn primitive mkdir path [mode] +Create a new directory named by @var{path}. If @var{mode} is omitted +then the permissions of the directory file are set using the current +umask. Otherwise they are set to the decimal value specified with +@var{mode}. The return value is unspecified. +@end deffn + +rmdir +@c snarfed from filesys.c:663 +@deffn primitive rmdir path +Remove the existing directory named by @var{path}. The directory must +be empty for this to succeed. The return value is unspecified. +@end deffn + +directory-stream? +@c snarfed from filesys.c:689 +@deffn primitive directory-stream? obj +Returns a boolean indicating whether @var{object} is a directory stream +as returned by @code{opendir}. +@end deffn + +opendir +@c snarfed from filesys.c:700 +@deffn primitive opendir dirname +Open the directory specified by @var{path} and return a directory +stream. +@end deffn + +readdir +@c snarfed from filesys.c:718 +@deffn primitive readdir port +Return (as a string) the next directory entry from the directory stream +@var{stream}. If there is no remaining entry to be read then the +end of file object is returned. +@end deffn + +rewinddir +@c snarfed from filesys.c:741 +@deffn primitive rewinddir port +Reset the directory port @var{stream} so that the next call to +@code{readdir} will return the first directory entry. +@end deffn + +closedir +@c snarfed from filesys.c:758 +@deffn primitive closedir port +Close the directory stream @var{stream}. +The return value is unspecified. +@end deffn + +chdir +@c snarfed from filesys.c:808 +@deffn primitive chdir str +Change the current working directory to @var{path}. +The return value is unspecified. +@end deffn + +getcwd +@c snarfed from filesys.c:825 +@deffn primitive getcwd +Returns the name of the current working directory. +@end deffn + +select +@c snarfed from filesys.c:1022 +@deffn primitive select reads writes excepts [secs [usecs]] +This procedure has a variety of uses: waiting for the ability +to provide input, accept output, or the existance of +exceptional conditions on a collection of ports or file +descriptors, or waiting for a timeout to occur. +It also returns if interrupted by a signal. + +@var{reads}, @var{writes} and @var{excepts} can be lists or +vectors, with each member a port or a file descriptor. +The value returned is a list of three corresponding +lists or vectors containing only the members which meet the +specified requirement. The ability of port buffers to +provide input or accept output is taken into account. +Ordering of the input lists or vectors is not preserved. + +The optional arguments @var{secs} and @var{usecs} specify the +timeout. Either @var{secs} can be specified alone, as +either an integer or a real number, or both @var{secs} and +@var{usecs} can be specified as integers, in which case +@var{usecs} is an additional timeout expressed in +microseconds. If @var{secs} is omitted or is @code{#f} then +select will wait for as long as it takes for one of the other +conditions to be satisfied. + +The scsh version of @code{select} differs as follows: +Only vectors are accepted for the first three arguments. +The @var{usecs} argument is not supported. +Multiple values are returned instead of a list. +Duplicates in the input vectors appear only once in output. +An additional @code{select!} interface is provided. +@end deffn + +fcntl +@c snarfed from filesys.c:1167 +@deffn primitive fcntl object cmd [value] +Apply @var{command} to the specified file descriptor or the underlying +file descriptor of the specified port. @var{value} is an optional +integer argument. + +Values for @var{command} are: + +@table @code +@item F_DUPFD +Duplicate a file descriptor +@item F_GETFD +Get flags associated with the file descriptor. +@item F_SETFD +Set flags associated with the file descriptor to @var{value}. +@item F_GETFL +Get flags associated with the open file. +@item F_SETFL +Set flags associated with the open file to @var{value} +@item F_GETOWN +Get the process ID of a socket's owner, for @code{SIGIO} signals. +@item F_SETOWN +Set the process that owns a socket to @var{value}, for @code{SIGIO} signals. +@item FD_CLOEXEC +The value used to indicate the "close on exec" flag with @code{F_GETFL} or +@code{F_SETFL}. +@end table +@end deffn + +fsync +@c snarfed from filesys.c:1203 +@deffn primitive fsync object +Copies any unwritten data for the specified output file descriptor to disk. +If @var{port/fd} is a port, its buffer is flushed before the underlying +file descriptor is fsync'd. +The return value is unspecified. +@end deffn + +symlink +@c snarfed from filesys.c:1230 +@deffn primitive symlink oldpath newpath +Create a symbolic link named @var{path-to} with the value (i.e., pointing to) +@var{path-from}. The return value is unspecified. +@end deffn + +readlink +@c snarfed from filesys.c:1252 +@deffn primitive readlink path +Returns the value of the symbolic link named by +@var{path} (a string), i.e., the +file that the link points to. +@end deffn + +lstat +@c snarfed from filesys.c:1282 +@deffn primitive lstat str +Similar to @code{stat}, but does not follow symbolic links, i.e., +it will return information about a symbolic link itself, not the +file it points to. @var{path} must be a string. +@end deffn + +copy-file +@c snarfed from filesys.c:1307 +@deffn primitive copy-file oldfile newfile +Copy the file specified by @var{path-from} to @var{path-to}. +The return value is unspecified. +@end deffn + +dirname +@c snarfed from filesys.c:1354 +@deffn primitive dirname filename +Return the directory name component of the file name +@var{filename}. If @var{filename} does not contain a directory +component, @code{.} is returned. +@end deffn + +basename +@c snarfed from filesys.c:1387 +@deffn primitive basename filename [suffix] +Return the base name of the file name @var{filename}. The +base name is the file name without any directory components. +If @var{suffix} is privided, and is equal to the end of +@var{basename}, it is removed also. +@end deffn + +make-fluid +@c snarfed from fluids.c:128 +@deffn primitive make-fluid +Return a newly created fluid. +Fluids are objects of a certain type (a smob) that can hold one SCM +value per dynamic root. That is, modifications to this value are +only visible to code that executes within the same dynamic root as +the modifying code. When a new dynamic root is constructed, it +inherits the values from its parent. Because each thread executes +in its own dynamic root, you can use fluids for thread local storage. +@end deffn + +fluid? +@c snarfed from fluids.c:141 +@deffn primitive fluid? obj +Return #t iff @var{obj} is a fluid; otherwise, return #f. +@end deffn + +fluid-ref +@c snarfed from fluids.c:151 +@deffn primitive fluid-ref fluid +Return the value associated with @var{fluid} in the current dynamic root. +If @var{fluid} has not been set, then this returns #f. +@end deffn + +fluid-set! +@c snarfed from fluids.c:168 +@deffn primitive fluid-set! fluid value +Set the value associated with @var{fluid} in the current dynamic root. +@end deffn + +with-fluids* +@c snarfed from fluids.c:227 +@deffn primitive with-fluids* fluids values thunk +Set @var{fluids} to @var{values} temporary, and call @var{thunk}. +@var{fluids} must be a list of fluids and @var{values} must be the same +number of their values to be applied. Each substitution is done +one after another. @var{thunk} must be a procedure with no argument. +@end deffn + +setvbuf +@c snarfed from fports.c:148 +@deffn primitive setvbuf port mode [size] +Set the buffering mode for @var{port}. @var{mode} can be: +@table @code +@item _IONBF +non-buffered +@item _IOLBF +line buffered +@item _IOFBF +block buffered, using a newly allocated buffer of @var{size} bytes. +If @var{size} is omitted, a default size will be used. +@end table +@end deffn + +file-port? +@c snarfed from fports.c:229 +@deffn primitive file-port? obj +Determine whether @var{obj} is a port that is related to a file. +@end deffn + +open-file +@c snarfed from fports.c:282 +@deffn primitive open-file filename modes +Open the file whose name is @var{string}, and return a port +representing that file. The attributes of the port are +determined by the @var{mode} string. The way in +which this is interpreted is similar to C stdio: + +The first character must be one of the following: + +@table @samp +@item r +Open an existing file for input. +@item w +Open a file for output, creating it if it doesn't already exist +or removing its contents if it does. +@item a +Open a file for output, creating it if it doesn't already exist. +All writes to the port will go to the end of the file. +The "append mode" can be turned off while the port is in use +@pxref{Ports and File Descriptors, fcntl} +@end table + +The following additional characters can be appended: + +@table @samp +@item + +Open the port for both input and output. E.g., @code{r+}: open +an existing file for both input and output. +@item 0 +Create an "unbuffered" port. In this case input and output operations +are passed directly to the underlying port implementation without +additional buffering. This is likely to slow down I/O operations. +The buffering mode can be changed while a port is in use +@pxref{Ports and File Descriptors, setvbuf} +@item l +Add line-buffering to the port. The port output buffer will be +automatically flushed whenever a newline character is written. +@end table + +In theory we could create read/write ports which were buffered in one +direction only. However this isn't included in the current interfaces. + +If a file cannot be opened with the access requested, +@code{open-file} throws an exception. +@end deffn + +gc-stats +@c snarfed from gc.c:742 +@deffn primitive gc-stats +Returns an association list of statistics about Guile's current use of storage. +@end deffn + +object-address +@c snarfed from gc.c:839 +@deffn primitive object-address obj +Return an integer that for the lifetime of @var{obj} is uniquely +returned by this function for @var{obj} +@end deffn + +gc +@c snarfed from gc.c:850 +@deffn primitive gc +Scans all of SCM objects and reclaims for further use those that are +no longer accessible. +@end deffn + +unhash-name +@c snarfed from gc.c:2291 +@deffn primitive unhash-name name +Flushes the glocs for @var{name}, or all glocs if @var{name} +is @code{#t}. +@end deffn + +%compute-slots +@c snarfed from goops.c:290 +@deffn primitive %compute-slots class +Return a list consisting of the names of all slots belonging to +class @var{class}, i. e. the slots of @var{class} and of all of +its superclasses. +@end deffn + +get-keyword +@c snarfed from goops.c:375 +@deffn primitive get-keyword key l default_value +Determine an associated value for the keyword @var{key} from +the list @var{l}. The list @var{l} has to consist of an even +number of elements, where, starting with the first, every +second element is a keyword, followed by its associated value. +If @var{l} does not hold a value for @var{key}, the value +@var{default_value} is returned. +@end deffn + +%initialize-object +@c snarfed from goops.c:398 +@deffn primitive %initialize-object obj initargs +Initialize the object @var{obj} with the given arguments +@var{initargs}. +@end deffn + +%prep-layout! +@c snarfed from goops.c:479 +@deffn primitive %prep-layout! class +@end deffn + +%inherit-magic! +@c snarfed from goops.c:542 +@deffn primitive %inherit-magic! class dsupers +@end deffn + +instance? +@c snarfed from goops.c:783 +@deffn primitive instance? obj +Return @code{#t} if @var{obj} is an instance. +@end deffn + +class-name +@c snarfed from goops.c:798 +@deffn primitive class-name obj +Return the class name of @var{obj}. +@end deffn + +class-direct-supers +@c snarfed from goops.c:808 +@deffn primitive class-direct-supers obj +Return the direct superclasses of the class @var{obj}. +@end deffn + +class-direct-slots +@c snarfed from goops.c:818 +@deffn primitive class-direct-slots obj +Return the direct slots of the class @var{obj}. +@end deffn + +class-direct-subclasses +@c snarfed from goops.c:828 +@deffn primitive class-direct-subclasses obj +Return the direct subclasses of the class @var{obj}. +@end deffn + +class-direct-methods +@c snarfed from goops.c:838 +@deffn primitive class-direct-methods obj +Return the direct methods of the class @var{obj} +@end deffn + +class-precedence-list +@c snarfed from goops.c:848 +@deffn primitive class-precedence-list obj +Return the class precedence list of the class @var{obj}. +@end deffn + +class-slots +@c snarfed from goops.c:858 +@deffn primitive class-slots obj +Return the slot list of the class @var{obj}. +@end deffn + +class-environment +@c snarfed from goops.c:868 +@deffn primitive class-environment obj +Return the environment of the class @var{obj}. +@end deffn + +generic-function-name +@c snarfed from goops.c:879 +@deffn primitive generic-function-name obj +Return the name of the generic function @var{obj}. +@end deffn + +generic-function-methods +@c snarfed from goops.c:889 +@deffn primitive generic-function-methods obj +Return the methods of the generic function @var{obj}. +@end deffn + +method-generic-function +@c snarfed from goops.c:900 +@deffn primitive method-generic-function obj +Return the generic function fot the method @var{obj}. +@end deffn + +method-specializers +@c snarfed from goops.c:910 +@deffn primitive method-specializers obj +Return specializers of the method @var{obj}. +@end deffn + +method-procedure +@c snarfed from goops.c:920 +@deffn primitive method-procedure obj +Return the procedure of the method @var{obj}. +@end deffn + +accessor-method-slot-definition +@c snarfed from goops.c:930 +@deffn primitive accessor-method-slot-definition obj +Return the slot definition of the accessor @var{obj}. +@end deffn + +%tag-body +@c snarfed from goops.c:940 +@deffn primitive %tag-body body +Internal GOOPS magic---don't use this function! +@end deffn + +make-unbound +@c snarfed from goops.c:955 +@deffn primitive make-unbound +Return the unbound value. +@end deffn + +unbound? +@c snarfed from goops.c:964 +@deffn primitive unbound? obj +Return @code{#t} if @var{obj} is unbound. +@end deffn + +assert-bound +@c snarfed from goops.c:974 +@deffn primitive assert-bound value obj +Return @var{value} if it is bound, and invoke the +@var{slot-unbound} method of @var{obj} if it is not. +@end deffn + +@@assert-bound-ref +@c snarfed from goops.c:986 +@deffn primitive @@assert-bound-ref obj index +Like @code{assert-bound}, but use @var{index} for accessing +the value from @var{obj}. +@end deffn + +%fast-slot-ref +@c snarfed from goops.c:998 +@deffn primitive %fast-slot-ref obj index +Return the slot value with index @var{index} from @var{obj}. +@end deffn + +%fast-slot-set! +@c snarfed from goops.c:1015 +@deffn primitive %fast-slot-set! obj index value +Set the slot with index @var{index} in @var{obj} to +@var{value}. +@end deffn + +slot-ref-using-class +@c snarfed from goops.c:1143 +@deffn primitive slot-ref-using-class class obj slot_name +@end deffn + +slot-set-using-class! +@c snarfed from goops.c:1162 +@deffn primitive slot-set-using-class! class obj slot_name value +@end deffn + +slot-bound-using-class? +@c snarfed from goops.c:1176 +@deffn primitive slot-bound-using-class? class obj slot_name +@end deffn + +slot-exists-using-class? +@c snarfed from goops.c:1191 +@deffn primitive slot-exists-using-class? class obj slot_name +@end deffn + +slot-ref +@c snarfed from goops.c:1207 +@deffn primitive slot-ref obj slot_name +Return the value from @var{obj}'s slot with the name +@var{slot_name}. +@end deffn + +slot-set! +@c snarfed from goops.c:1224 +@deffn primitive slot-set! obj slot_name value +Set the slot named @var{slot_name} of @var{obj} to @var{value}. +@end deffn + +slot-bound? +@c snarfed from goops.c:1241 +@deffn primitive slot-bound? obj slot_name +Return @code{#t} if the slot named @var{slot_name} of @var{obj} +is bound. +@end deffn + +slot-exists? +@c snarfed from goops.c:1259 +@deffn primitive slot-exists? obj slot_name +Return @code{#t} if @var{obj} has a slot named @var{slot_name}. +@end deffn + +%allocate-instance +@c snarfed from goops.c:1302 +@deffn primitive %allocate-instance class initargs +Create a new instance of class @var{class} and initialize it +from the arguments @var{initargs}. +@end deffn + +%set-object-setter! +@c snarfed from goops.c:1375 +@deffn primitive %set-object-setter! obj setter +@end deffn + +%modify-instance +@c snarfed from goops.c:1400 +@deffn primitive %modify-instance old new +@end deffn + +%modify-class +@c snarfed from goops.c:1426 +@deffn primitive %modify-class old new +@end deffn + +%invalidate-class +@c snarfed from goops.c:1450 +@deffn primitive %invalidate-class class +@end deffn + +%invalidate-method-cache! +@c snarfed from goops.c:1571 +@deffn primitive %invalidate-method-cache! gf +@end deffn + +generic-capability? +@c snarfed from goops.c:1597 +@deffn primitive generic-capability? proc +@end deffn + +enable-primitive-generic! +@c snarfed from goops.c:1610 +@deffn primitive enable-primitive-generic! . subrs +@end deffn + +primitive-generic-generic +@c snarfed from goops.c:1630 +@deffn primitive primitive-generic-generic subr +@end deffn + +make +@c snarfed from goops.c:1989 +@deffn primitive make . args +Make a new object. @var{args} must contain the class and +all necessary initialization information. +@end deffn + +find-method +@c snarfed from goops.c:2082 +@deffn primitive find-method . l +@end deffn + +%method-more-specific? +@c snarfed from goops.c:2102 +@deffn primitive %method-more-specific? m1 m2 targs +@end deffn + +%goops-loaded +@c snarfed from goops.c:2634 +@deffn primitive %goops-loaded +Announce that GOOPS is loaded and perform initialization +on the C level which depends on the loaded GOOPS modules. +@end deffn + +make-guardian +@c snarfed from guardians.c:336 +@deffn primitive make-guardian [greedy_p] +Create a new guardian. +A guardian protects a set of objects from garbage collection, +allowing a program to apply cleanup or other actions. + +@code{make-guardian} returns a procedure representing the guardian. +Calling the guardian procedure with an argument adds the +argument to the guardian's set of protected objects. +Calling the guardian procedure without an argument returns +one of the protected objects which are ready for garbage +collection, or @code{#f} if no such object is available. +Objects which are returned in this way are removed from +the guardian. + +@code{make-guardian} takes one optional argument that says whether the +new guardian should be greedy or sharing. If there is any chance +that any object protected by the guardian may be resurrected, +then you should make the guardian greedy (this is the default). + +See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) +"Guardians in a Generation-Based Garbage Collector". +ACM SIGPLAN Conference on Programming Language Design +and Implementation, June 1993. + +(the semantics are slightly different at this point, but the +paper still (mostly) accurately describes the interface). +@end deffn + +guardian-destroyed? +@c snarfed from guardians.c:364 +@deffn primitive guardian-destroyed? guardian +Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}. +@end deffn + +guardian-greedy? +@c snarfed from guardians.c:382 +@deffn primitive guardian-greedy? guardian +Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}. +@end deffn + +destroy-guardian! +@c snarfed from guardians.c:393 +@deffn primitive destroy-guardian! guardian +Destroys @var{guardian}, by making it impossible to put any more +objects in it or get any objects from it. It also unguards any +objects guarded by @var{guardian}. +@end deffn + +hashq +@c snarfed from hash.c:202 +@deffn primitive hashq key size +Determine a hash value for @var{key} that is suitable for +lookups in a hashtable of size @var{size}, where @code{eq?} is +used as the equality predicate. The function returns an +integer in the range 0 to @var{size} - 1. Note that +@code{hashq} may use internal addresses. Thus two calls to +hashq where the keys are @code{eq?} are not guaranteed to +deliver the same value if the key object gets garbage collected +in between. This can happen, for example with symbols: +@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two +different values, since @code{foo} will be garbage collected. +@end deffn + +hashv +@c snarfed from hash.c:238 +@deffn primitive hashv key size +Determine a hash value for @var{key} that is suitable for +lookups in a hashtable of size @var{size}, where @code{eqv?} is +used as the equality predicate. The function returns an +integer in the range 0 to @var{size} - 1. Note that +@code{(hashv key)} may use internal addresses. Thus two calls +to hashv where the keys are @code{eqv?} are not guaranteed to +deliver the same value if the key object gets garbage collected +in between. This can happen, for example with symbols: +@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two +different values, since @code{foo} will be garbage collected. +@end deffn + +hash +@c snarfed from hash.c:261 +@deffn primitive hash key size +Determine a hash value for @var{key} that is suitable for +lookups in a hashtable of size @var{size}, where @code{equal?} +is used as the equality predicate. The function returns an +integer in the range 0 to @var{size} - 1. +@end deffn + +hashq-get-handle +@c snarfed from hashtab.c:174 +@deffn primitive hashq-get-handle table obj +This procedure is similar to its @code{-ref} cousin, but returns a +@dfn{handle} from the hash table rather than the value associated with +@var{key}. By convention, a handle in a hash table is the pair which +associates a key with a value. Where @code{hashq-ref table key} returns +only a @code{value}, @code{hashq-get-handle table key} returns the pair +@code{(key . value)}. +@end deffn + +hashq-create-handle! +@c snarfed from hashtab.c:186 +@deffn primitive hashq-create-handle! table key init +This function looks up @var{key} in @var{table} and returns its handle. +If @var{key} is not already present, a new handle is created which +associates @var{key} with @var{init}. +@end deffn + +hashq-ref +@c snarfed from hashtab.c:199 +@deffn primitive hashq-ref table obj [dflt] +Look up @var{key} in the hash table @var{table}, and return the +value (if any) associated with it. If @var{key} is not found, +return @var{default} (or @code{#f} if no @var{default} argument +is supplied). Uses @code{eq?} for equality testing. +@end deffn + +hashq-set! +@c snarfed from hashtab.c:213 +@deffn primitive hashq-set! table obj val +Find the entry in @var{table} associated with @var{key}, and +store @var{value} there. Uses @code{eq?} for equality testing. +@end deffn + +hashq-remove! +@c snarfed from hashtab.c:225 +@deffn primitive hashq-remove! table obj +Remove @var{key} (and any value associated with it) from +@var{table}. Uses @code{eq?} for equality tests. +@end deffn + +hashv-get-handle +@c snarfed from hashtab.c:242 +@deffn primitive hashv-get-handle table obj +This procedure is similar to its @code{-ref} cousin, but returns a +@dfn{handle} from the hash table rather than the value associated with +@var{key}. By convention, a handle in a hash table is the pair which +associates a key with a value. Where @code{hashv-ref table key} returns +only a @code{value}, @code{hashv-get-handle table key} returns the pair +@code{(key . value)}. +@end deffn + +hashv-create-handle! +@c snarfed from hashtab.c:254 +@deffn primitive hashv-create-handle! table key init +This function looks up @var{key} in @var{table} and returns its handle. +If @var{key} is not already present, a new handle is created which +associates @var{key} with @var{init}. +@end deffn + +hashv-ref +@c snarfed from hashtab.c:267 +@deffn primitive hashv-ref table obj [dflt] +Look up @var{key} in the hash table @var{table}, and return the +value (if any) associated with it. If @var{key} is not found, +return @var{default} (or @code{#f} if no @var{default} argument +is supplied). Uses @code{eqv?} for equality testing. +@end deffn + +hashv-set! +@c snarfed from hashtab.c:281 +@deffn primitive hashv-set! table obj val +Find the entry in @var{table} associated with @var{key}, and +store @var{value} there. Uses @code{eqv?} for equality testing. +@end deffn + +hashv-remove! +@c snarfed from hashtab.c:292 +@deffn primitive hashv-remove! table obj +Remove @var{key} (and any value associated with it) from +@var{table}. Uses @code{eqv?} for equality tests. +@end deffn + +hash-get-handle +@c snarfed from hashtab.c:308 +@deffn primitive hash-get-handle table obj +This procedure is similar to its @code{-ref} cousin, but returns a +@dfn{handle} from the hash table rather than the value associated with +@var{key}. By convention, a handle in a hash table is the pair which +associates a key with a value. Where @code{hash-ref table key} returns +only a @code{value}, @code{hash-get-handle table key} returns the pair +@code{(key . value)}. +@end deffn + +hash-create-handle! +@c snarfed from hashtab.c:320 +@deffn primitive hash-create-handle! table key init +This function looks up @var{key} in @var{table} and returns its handle. +If @var{key} is not already present, a new handle is created which +associates @var{key} with @var{init}. +@end deffn + +hash-ref +@c snarfed from hashtab.c:333 +@deffn primitive hash-ref table obj [dflt] +Look up @var{key} in the hash table @var{table}, and return the +value (if any) associated with it. If @var{key} is not found, +return @var{default} (or @code{#f} if no @var{default} argument +is supplied). Uses @code{equal?} for equality testing. +@end deffn + +hash-set! +@c snarfed from hashtab.c:348 +@deffn primitive hash-set! table obj val +Find the entry in @var{table} associated with @var{key}, and +store @var{value} there. Uses @code{equal?} for equality +testing. +@end deffn + +hash-remove! +@c snarfed from hashtab.c:360 +@deffn primitive hash-remove! table obj +Remove @var{key} (and any value associated with it) from +@var{table}. Uses @code{equal?} for equality tests. +@end deffn + +hashx-get-handle +@c snarfed from hashtab.c:429 +@deffn primitive hashx-get-handle hash assoc table obj +This behaves the same way as the corresponding @code{-get-handle} +function, but uses @var{hasher} as a +hash function and @var{assoc} to compare keys. @code{hasher} must +be a function that takes two arguments, a key to be hashed and a +table size. @code{assoc} must be an associator function, like +@code{assoc}, @code{assq} or @code{assv}. +@end deffn + +hashx-create-handle! +@c snarfed from hashtab.c:447 +@deffn primitive hashx-create-handle! hash assoc table obj init +This behaves the same way as the corresponding @code{-create-handle} +function, but uses @var{hasher} as a +hash function and @var{assoc} to compare keys. @code{hasher} must +be a function that takes two arguments, a key to be hashed and a +table size. @code{assoc} must be an associator function, like +@code{assoc}, @code{assq} or @code{assv}. +@end deffn + +hashx-ref +@c snarfed from hashtab.c:468 +@deffn primitive hashx-ref hash assoc table obj [dflt] +This behaves the same way as the corresponding @code{ref} +function, but uses @var{hasher} as a +hash function and @var{assoc} to compare keys. @code{hasher} must +be a function that takes two arguments, a key to be hashed and a +table size. @code{assoc} must be an associator function, like +@code{assoc}, @code{assq} or @code{assv}. + +By way of illustration, @code{hashq-ref table key} is equivalent +to @code{hashx-ref hashq assq table key}. +@end deffn + +hashx-set! +@c snarfed from hashtab.c:492 +@deffn primitive hashx-set! hash assoc table obj val +This behaves the same way as the corresponding @code{set!} +function, but uses @var{hasher} as a +hash function and @var{assoc} to compare keys. @code{hasher} must +be a function that takes two arguments, a key to be hashed and a +table size. @code{assoc} must be an associator function, like +@code{assoc}, @code{assq} or @code{assv}. + +By way of illustration, @code{hashq-set! table key} is equivalent +to @code{hashx-set! hashq assq table key}. +@end deffn + +hash-fold +@c snarfed from hashtab.c:529 +@deffn primitive hash-fold proc init table +An iterator over hash-table elements. +Accumulates and returns a result by applying PROC successively. +The arguments to PROC are "(key value prior-result)" where key +and value are successive pairs from the hash table TABLE, and +prior-result is either INIT (for the first application of PROC) +or the return value of the previous application of PROC. +For example, @code{(hash-fold acons () tab)} will convert a hash +table into an a-list of key-value pairs. +@end deffn + +make-hook-with-name +@c snarfed from hooks.c:216 +@deffn primitive make-hook-with-name name [n_args] +Create a named hook with the name @var{name} for storing +procedures of arity @var{n_args}. +@end deffn + +make-hook +@c snarfed from hooks.c:230 +@deffn primitive make-hook [n_args] +Create a hook for storing procedure of arity @var{n_args}. +@end deffn + +hook? +@c snarfed from hooks.c:240 +@deffn primitive hook? x +Return @code{#t} if @var{x} is a hook. +@end deffn + +hook-empty? +@c snarfed from hooks.c:250 +@deffn primitive hook-empty? hook +Return @code{#t} if @var{hook} is an empty hook. +@end deffn + +add-hook! +@c snarfed from hooks.c:263 +@deffn primitive add-hook! hook proc [append_p] +Add the procedure @var{proc} to the hook @var{hook}. The +procedure is added to the end if @var{append_p} is true, +otherwise it is added to the front. +@end deffn + +remove-hook! +@c snarfed from hooks.c:289 +@deffn primitive remove-hook! hook proc +Remove the procedure @var{proc} from the hook @var{hook}. +@end deffn + +reset-hook! +@c snarfed from hooks.c:302 +@deffn primitive reset-hook! hook +Remove all procedures from the hook @var{hook}. +@end deffn + +run-hook +@c snarfed from hooks.c:315 +@deffn primitive run-hook hook . args +Apply all procedures from the hook @var{hook} to the arguments +@var{args}. +@end deffn + +hook->list +@c snarfed from hooks.c:342 +@deffn primitive hook->list hook +Convert the procedure list of @var{hook} to a list. +@end deffn + +read-string!/partial +@c snarfed from ioext.c:114 +@deffn primitive read-string!/partial str [port_or_fdes [start [end]]] +Read characters from an fport or file descriptor into a +string @var{str}. This procedure is scsh-compatible +and can efficiently read large strings. It will: + +@itemize +@item +attempt to fill the entire string, unless the @var{start} +and/or @var{end} arguments are supplied. i.e., @var{start} +defaults to 0 and @var{end} defaults to +@code{(string-length str)} +@item +use the current input port if @var{port_or_fdes} is not +supplied. +@item +read any characters that are currently available, +without waiting for the rest (short reads are possible). + +@item +wait for as long as it needs to for the first character to +become available, unless the port is in non-blocking mode +@item +return @code{#f} if end-of-file is encountered before reading +any characters, otherwise return the number of characters +read. +@item +return 0 if the port is in non-blocking mode and no characters +are immediately available. +@item +return 0 if the request is for 0 bytes, with no +end-of-file check +@end itemize +@end deffn + +ftell +@c snarfed from ioext.c:173 +@deffn primitive ftell object +Returns an integer representing the current position of @var{fd/port}, +measured from the beginning. Equivalent to: +@smalllisp +(seek port 0 SEEK_CUR) +@end smalllisp +@end deffn + +fseek +@c snarfed from ioext.c:186 +@deffn primitive fseek object offset whence +Obsolete. Almost the same as seek, above, but the return value is +unspecified. +@end deffn + +redirect-port +@c snarfed from ioext.c:208 +@deffn primitive redirect-port old new +This procedure takes two ports and duplicates the underlying file +descriptor from @var{old-port} into @var{new-port}. The +current file descriptor in @var{new-port} will be closed. +After the redirection the two ports will share a file position +and file status flags. + +The return value is unspecified. + +Unexpected behaviour can result if both ports are subsequently used +and the original and/or duplicate ports are buffered. + +This procedure does not have any side effects on other ports or +revealed counts. +@end deffn + +dup->fdes +@c snarfed from ioext.c:245 +@deffn primitive dup->fdes fd_or_port [fd] +Returns an integer file descriptor. +@end deffn + +dup2 +@c snarfed from ioext.c:292 +@deffn primitive dup2 oldfd newfd +A simple wrapper for the @code{dup2} system call. +Copies the file descriptor @var{oldfd} to descriptor +number @var{newfd}, replacing the previous meaning +of @var{newfd}. Both @var{oldfd} and @var{newfd} must +be integers. +Unlike for dup->fdes or primitive-move->fdes, no attempt +is made to move away ports which are using @var{newfd}. +The return value is unspecified. +@end deffn + +fileno +@c snarfed from ioext.c:311 +@deffn primitive fileno port +Returns the integer file descriptor underlying @var{port}. +Does not change its revealed count. +@end deffn + +isatty? +@c snarfed from ioext.c:327 +@deffn primitive isatty? port +Returns @code{#t} if @var{port} is using a serial +non-file device, otherwise @code{#f}. +@end deffn + +fdopen +@c snarfed from ioext.c:349 +@deffn primitive fdopen fdes modes +Returns a new port based on the file descriptor @var{fdes}. +Modes are given by the string @var{modes}. The revealed count of the port +is initialized to zero. The modes string is the same as that accepted +by @ref{File Ports, open-file}. +@end deffn + +primitive-move->fdes +@c snarfed from ioext.c:374 +@deffn primitive primitive-move->fdes port fd +Moves the underlying file descriptor for @var{port} to the integer +value @var{fdes} without changing the revealed count of @var{port}. +Any other ports already using this descriptor will be automatically +shifted to new descriptors and their revealed counts reset to zero. +The return value is @code{#f} if the file descriptor already had the +required value or @code{#t} if it was moved. +@end deffn + +fdes->ports +@c snarfed from ioext.c:407 +@deffn primitive fdes->ports fd +Returns a list of existing ports which have @var{fdes} as an +underlying file descriptor, without changing their revealed counts. +@end deffn + +make-keyword-from-dash-symbol +@c snarfed from keywords.c:71 +@deffn primitive make-keyword-from-dash-symbol symbol +Make a keyword object from a @var{symbol} that starts with a dash. +@end deffn + +keyword? +@c snarfed from keywords.c:112 +@deffn primitive keyword? obj +Returns @code{#t} if the argument @var{obj} is a keyword, else @code{#f}. +@end deffn + +keyword-dash-symbol +@c snarfed from keywords.c:123 +@deffn primitive keyword-dash-symbol keyword +Return the dash symbol for @var{keyword}. +This is the inverse of @code{make-keyword-from-dash-symbol}. +@end deffn + +nil-cons +@c snarfed from lang.c:71 +@deffn primitive nil-cons x y +Create a new cons cell with @var{x} as the car and @var{y} as +the cdr, but convert @var{y} to Scheme's end-of-list if it is +a LISP nil. +@end deffn + +nil-car +@c snarfed from lang.c:86 +@deffn primitive nil-car x +Return the car of @var{x}, but convert it to LISP nil if it +is Scheme's end-of-list. +@end deffn + +nil-cdr +@c snarfed from lang.c:99 +@deffn primitive nil-cdr x +Return the cdr of @var{x}, but convert it to LISP nil if it +is Scheme's end-of-list. +@end deffn + +null +@c snarfed from lang.c:114 +@deffn primitive null x +Return LISP's @code{t} if @var{x} is nil in the LISP sense, +return LISP's nil otherwise. +@end deffn + +nil-eq +@c snarfed from lang.c:143 +@deffn primitive nil-eq x y +Compare @var{x} and @var{y} and return LISP's t if they are +@code{eq?}, return LISP's nil otherwise. +@end deffn + +list +@c snarfed from list.c:84 +@deffn primitive list . objs +Return a list containing @var{objs}, the arguments to +@code{list}. +@end deffn + +list* +@c snarfed from list.c:94 +@deffn primitive list* +scm_cons_star +@end deffn + +cons* +@c snarfed from list.c:105 +@deffn primitive cons* arg . rest +Like @code{list}, but the last arg provides the tail of the +constructed list, returning @code{(cons @var{arg1} (cons +@var{arg2} (cons @dots{} @var{argn}))). Requires at least one +argument. If given one argument, that argument is returned as +result. This function is called @code{list*} in some other +Schemes and in Common LISP. +@end deffn + +null? +@c snarfed from list.c:129 +@deffn primitive null? x +Return @code{#t} iff @var{x} is the empty list, else @code{#f}. +@end deffn + +list? +@c snarfed from list.c:139 +@deffn primitive list? x +Return @code{#t} iff @var{x} is a proper list, else @code{#f}. +@end deffn + +length +@c snarfed from list.c:180 +@deffn primitive length lst +Return the number of elements in list @var{lst}. +@end deffn + +append +@c snarfed from list.c:209 +@deffn primitive append . args +Return a list consisting of the elements the lists passed as +arguments. +@example +(append '(x) '(y)) @result{} (x y) +(append '(a) '(b c d)) @result{} (a b c d) +(append '(a (b)) '((c))) @result{} (a (b) (c)) +@end example +The resulting list is always newly allocated, except that it +shares structure with the last list argument. The last +argument may actually be any object; an improper list results +if the last argument is not a proper list. +@example +(append '(a b) '(c . d)) @result{} (a b c . d) +(append '() 'a) @result{} a +@end example +@end deffn + +append! +@c snarfed from list.c:242 +@deffn primitive append! . args +A destructive version of @code{append} (@pxref{Pairs and Lists,,,r4rs, +The Revised^4 Report on Scheme}). The cdr field of each list's final +pair is changed to point to the head of the next list, so no consing is +performed. Return a pointer to the mutated list. +@end deffn + +last-pair +@c snarfed from list.c:268 +@deffn primitive last-pair lst +Return a pointer to the last pair in @var{lst}, signalling an error if +@var{lst} is circular. +@end deffn + +reverse +@c snarfed from list.c:298 +@deffn primitive reverse lst +Return a new list that contains the elements of @var{lst} but +in reverse order. +@end deffn + +reverse! +@c snarfed from list.c:332 +@deffn primitive reverse! lst [new_tail] +A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs, +The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is +modified to point to the previous list element. Return a pointer to the +head of the reversed list. + +Caveat: because the list is modified in place, the tail of the original +list now becomes its head, and the head of the original list now becomes +the tail. Therefore, the @var{lst} symbol to which the head of the +original list was bound now points to the tail. To ensure that the head +of the modified list is not lost, it is wise to save the return value of +@code{reverse!} +@end deffn + +list-ref +@c snarfed from list.c:358 +@deffn primitive list-ref list k +Return the @var{k}th element from @var{list}. +@end deffn + +list-set! +@c snarfed from list.c:382 +@deffn primitive list-set! list k val +Set the @var{k}th element of @var{list} to @var{val}. +@end deffn + +list-cdr-ref +@c snarfed from list.c:405 +@deffn primitive list-cdr-ref +scm_list_tail +@end deffn + +list-tail +@c snarfed from list.c:414 +@deffn primitive list-tail lst k +@deffnx primitive list-cdr-ref lst k +Return the "tail" of @var{lst} beginning with its @var{k}th element. +The first element of the list is considered to be element 0. + +@code{list-tail} and @code{list-cdr-ref} are identical. It may help to +think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list, +or returning the results of cdring @var{k} times down @var{lst}. +@end deffn + +list-cdr-set! +@c snarfed from list.c:430 +@deffn primitive list-cdr-set! list k val +Set the @var{k}th cdr of @var{list} to @var{val}. +@end deffn + +list-head +@c snarfed from list.c:459 +@deffn primitive list-head lst k +Copy the first @var{k} elements from @var{lst} into a new list, and +return it. +@end deffn + +list-copy +@c snarfed from list.c:483 +@deffn primitive list-copy lst +Return a (newly-created) copy of @var{lst}. +@end deffn + +sloppy-memq +@c snarfed from list.c:517 +@deffn primitive sloppy-memq x lst +This procedure behaves like @code{memq}, but does no type or error checking. +Its use is recommended only in writing Guile internals, +not for high-level Scheme programs. +@end deffn + +sloppy-memv +@c snarfed from list.c:534 +@deffn primitive sloppy-memv x lst +This procedure behaves like @code{memv}, but does no type or error checking. +Its use is recommended only in writing Guile internals, +not for high-level Scheme programs. +@end deffn + +sloppy-member +@c snarfed from list.c:551 +@deffn primitive sloppy-member x lst +This procedure behaves like @code{member}, but does no type or error checking. +Its use is recommended only in writing Guile internals, +not for high-level Scheme programs. +@end deffn + +memq +@c snarfed from list.c:591 +@deffn primitive memq x lst +Return the first sublist of @var{lst} whose car is @code{eq?} +to @var{x} where the sublists of @var{lst} are the non-empty +lists returned by @code{(list-tail @var{lst} @var{k})} for +@var{k} less than the length of @var{lst}. If @var{x} does not +occur in @var{lst}, then @code{#f} (not the empty list) is +returned. +@end deffn + +memv +@c snarfed from list.c:608 +@deffn primitive memv x lst +Return the first sublist of @var{lst} whose car is @code{eqv?} +to @var{x} where the sublists of @var{lst} are the non-empty +lists returned by @code{(list-tail @var{lst} @var{k})} for +@var{k} less than the length of @var{lst}. If @var{x} does not +occur in @var{lst}, then @code{#f} (not the empty list) is +returned. +@end deffn + +member +@c snarfed from list.c:629 +@deffn primitive member x lst +Return the first sublist of @var{lst} whose car is +@code{equal?} to @var{x} where the sublists of @var{lst} are +the non-empty lists returned by @code{(list-tail @var{lst} +@var{k})} for @var{k} less than the length of @var{lst}. If +@var{x} does not occur in @var{lst}, then @code{#f} (not the +empty list) is returned. +@end deffn + +delq! +@c snarfed from list.c:655 +@deffn primitive delq! item lst +@deffnx primitive delv! item lst +@deffnx primitive delete! item lst +These procedures are destructive versions of @code{delq}, @code{delv} +and @code{delete}: they modify the pointers in the existing @var{lst} +rather than creating a new list. Caveat evaluator: Like other +destructive list functions, these functions cannot modify the binding of +@var{lst}, and so cannot be used to delete the first element of +@var{lst} destructively. +@end deffn + +delv! +@c snarfed from list.c:679 +@deffn primitive delv! item lst +Destructively remove all elements from @var{lst} that are +@code{eqv?} to @var{item}. +@end deffn + +delete! +@c snarfed from list.c:704 +@deffn primitive delete! item lst +Destructively remove all elements from @var{lst} that are +@code{equal?} to @var{item}. +@end deffn + +delq +@c snarfed from list.c:733 +@deffn primitive delq item lst +Return a newly-created copy of @var{lst} with elements +@code{eq?} to @var{item} removed. This procedure mirrors +@code{memq}: @code{delq} compares elements of @var{lst} against +@var{item} with @code{eq?}. +@end deffn + +delv +@c snarfed from list.c:746 +@deffn primitive delv item lst +Return a newly-created copy of @var{lst} with elements +@code{eqv?} to @var{item} removed. This procedure mirrors +@code{memv}: @code{delv} compares elements of @var{lst} against +@var{item} with @code{eqv?}. +@end deffn + +delete +@c snarfed from list.c:759 +@deffn primitive delete item lst +Return a newly-created copy of @var{lst} with elements +@code{equal?} to @var{item} removed. This procedure mirrors +@code{member}: @code{delete} compares elements of @var{lst} +against @var{item} with @code{equal?}. +@end deffn + +delq1! +@c snarfed from list.c:772 +@deffn primitive delq1! item lst +Like @code{delq!}, but only deletes the first occurrence of +@var{item} from @var{lst}. Tests for equality using +@code{eq?}. See also @code{delv1!} and @code{delete1!}. +@end deffn + +delv1! +@c snarfed from list.c:800 +@deffn primitive delv1! item lst +Like @code{delv!}, but only deletes the first occurrence of +@var{item} from @var{lst}. Tests for equality using +@code{eqv?}. See also @code{delq1!} and @code{delete1!}. +@end deffn + +delete1! +@c snarfed from list.c:828 +@deffn primitive delete1! item lst +Like @code{delete!}, but only deletes the first occurrence of +@var{item} from @var{lst}. Tests for equality using +@code{equal?}. See also @code{delq1!} and @code{delv1!}. +@end deffn + +primitive-load +@c snarfed from load.c:112 +@deffn primitive primitive-load filename +Load the file named @var{filename} and evaluate its contents in +the top-level environment. The load paths are not searched; +@var{filename} must either be a full pathname or be a pathname +relative to the current directory. If the variable +@code{%load-hook} is defined, it should be bound to a procedure +that will be called before any code is loaded. See the +documentation for @code{%load-hook} later in this section. +@end deffn + +%package-data-dir +@c snarfed from load.c:147 +@deffn primitive %package-data-dir +Return the name of the directory where Scheme packages, modules and +libraries are kept. On most Unix systems, this will be +@samp{/usr/local/share/guile}. +@end deffn + +%library-dir +@c snarfed from load.c:159 +@deffn primitive %library-dir +Return the directory where the Guile Scheme library files are installed. +E.g., may return "/usr/share/guile/1.3.5". +@end deffn + +%site-dir +@c snarfed from load.c:171 +@deffn primitive %site-dir +Return the directory where the Guile site files are installed. +E.g., may return "/usr/share/guile/site". +@end deffn + +parse-path +@c snarfed from load.c:223 +@deffn primitive parse-path path [tail] +Parse @var{path}, which is expected to be a colon-separated +string, into a list and return the resulting list with +@var{tail} appended. If @var{path} is @code{#f}, @var{tail} +is returned. +@end deffn + +search-path +@c snarfed from load.c:273 +@deffn primitive search-path path filename [extensions] +Search @var{path} for a directory containing a file named +@var{filename}. The file must be readable, and not a directory. +If we find one, return its full filename; otherwise, return +@code{#f}. If @var{filename} is absolute, return it unchanged. +If given, @var{extensions} is a list of strings; for each +directory in @var{path}, we search for @var{filename} +concatenated with each @var{extension}. +@end deffn + +%search-load-path +@c snarfed from load.c:420 +@deffn primitive %search-load-path filename +Search @var{%load-path} for the file named @var{filename}, +which must be readable by the current user. If @var{filename} +is found in the list of paths to search or is an absolute +pathname, return its full pathname. Otherwise, return +@code{#f}. Filenames may have any of the optional extensions +in the @code{%load-extensions} list; @code{%search-load-path} +will try each extension automatically. +@end deffn + +primitive-load-path +@c snarfed from load.c:441 +@deffn primitive primitive-load-path filename +Search @var{%load-path} for the file named @var{filename} and +load it into the top-level environment. If @var{filename} is a +relative pathname and is not found in the list of search paths, +an error is signalled. +@end deffn + +read-and-eval! +@c snarfed from load.c:476 +@deffn primitive read-and-eval! [port] +Read a form from @var{port} (standard input by default), and evaluate it +(memoizing it in the process) in the top-level environment. If no data +is left to be read from @var{port}, an @code{end-of-file} error is +signalled. +@end deffn + +procedure->syntax +@c snarfed from macros.c:60 +@deffn primitive procedure->syntax code +Returns a @dfn{macro} which, when a symbol defined to this value +appears as the first symbol in an expression, returns the result +of applying @var{code} to the expression and the environment. +@end deffn + +procedure->macro +@c snarfed from macros.c:82 +@deffn primitive procedure->macro code +Returns a @dfn{macro} which, when a symbol defined to this value +appears as the first symbol in an expression, evaluates the result +of applying @var{code} to the expression and the environment. +The value returned from @var{code} which has been passed to +@code{procedure->memoizing-macro} replaces the form passed to +@var{code}. For example: + +@example +(define trace + (procedure->macro + (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) + +(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})). +@end example +@end deffn + +procedure->memoizing-macro +@c snarfed from macros.c:104 +@deffn primitive procedure->memoizing-macro code +Returns a @dfn{macro} which, when a symbol defined to this value +appears as the first symbol in an expression, evaluates the result +of applying @var{proc} to the expression and the environment. +The value returned from @var{proc} which has been passed to +@code{procedure->memoizing-macro} replaces the form passed to +@var{proc}. For example: + +@example +(define trace + (procedure->macro + (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) + +(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})). +@end example +@end deffn + +macro? +@c snarfed from macros.c:116 +@deffn primitive macro? obj +Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a +syntax transformer. +@end deffn + +macro-type +@c snarfed from macros.c:133 +@deffn primitive macro-type m +Return one of the symbols @code{syntax}, @code{macro} or @code{macro!}, +depending on whether @var{obj} is a syntax tranformer, a regular macro, +or a memoizing macro, respectively. If @var{obj} is not a macro, +@code{#f} is returned. +@end deffn + +macro-name +@c snarfed from macros.c:151 +@deffn primitive macro-name m +Return the name of the macro @var{m}. +@end deffn + +macro-transformer +@c snarfed from macros.c:162 +@deffn primitive macro-transformer m +Return the transformer of the macro @var{m}. +@end deffn + +interaction-environment +@c snarfed from modules.c:102 +@deffn primitive interaction-environment +This procedure returns a specifier for the environment that contains +implementation-defined bindings, typically a superset of those listed in +the report. The intent is that this procedure will return the +environment in which the implementation would evaluate expressions +dynamically typed by the user. +@end deffn + +standard-eval-closure +@c snarfed from modules.c:271 +@deffn primitive standard-eval-closure module +Return an eval closure for the module @var{module}. +@end deffn + +inet-aton +@c snarfed from net_db.c:96 +@deffn primitive inet-aton address +Converts a string containing an Internet host address in the traditional +dotted decimal notation into an integer. + +@smalllisp +(inet-aton "127.0.0.1") @result{} 2130706433 + +@end smalllisp +@end deffn + +inet-ntoa +@c snarfed from net_db.c:116 +@deffn primitive inet-ntoa inetid +Converts an integer Internet host address into a string with the +traditional dotted decimal representation. + +@smalllisp +(inet-ntoa 2130706433) @result{} "127.0.0.1" +@end smalllisp +@end deffn + +inet-netof +@c snarfed from net_db.c:135 +@deffn primitive inet-netof address +Returns the network number part of the given integer Internet address. + +@smalllisp +(inet-netof 2130706433) @result{} 127 +@end smalllisp +@end deffn + +inet-lnaof +@c snarfed from net_db.c:152 +@deffn primitive inet-lnaof address +Returns the local-address-with-network part of the given Internet +address. + +@smalllisp +(inet-lnaof 2130706433) @result{} 1 +@end smalllisp +@end deffn + +inet-makeaddr +@c snarfed from net_db.c:169 +@deffn primitive inet-makeaddr net lna +Makes an Internet host address by combining the network number @var{net} +with the local-address-within-network number @var{lna}. + +@smalllisp +(inet-makeaddr 127 1) @result{} 2130706433 +@end smalllisp +@end deffn + +gethost +@c snarfed from net_db.c:254 +@deffn primitive gethost [host] +@deffnx procedure gethostbyname hostname +@deffnx procedure gethostbyaddr address +Look up a host by name or address, returning a host object. The +@code{gethost} procedure will accept either a string name or an integer +address; if given no arguments, it behaves like @code{gethostent} (see +below). If a name or address is supplied but the address can not be +found, an error will be thrown to one of the keys: +@code{host-not-found}, @code{try-again}, @code{no-recovery} or +@code{no-data}, corresponding to the equivalent @code{h_error} values. +Unusual conditions may result in errors thrown to the +@code{system-error} or @code{misc_error} keys. +@end deffn + +getnet +@c snarfed from net_db.c:335 +@deffn primitive getnet [net] +@deffnx procedure getnetbyname net-name +@deffnx procedure getnetbyaddr net-number +Look up a network by name or net number in the network database. The +@var{net-name} argument must be a string, and the @var{net-number} +argument must be an integer. @code{getnet} will accept either type of +argument, behaving like @code{getnetent} (see below) if no arguments are +given. +@end deffn + +getproto +@c snarfed from net_db.c:385 +@deffn primitive getproto [protocol] +@deffnx procedure getprotobyname name +@deffnx procedure getprotobynumber number +Look up a network protocol by name or by number. @code{getprotobyname} +takes a string argument, and @code{getprotobynumber} takes an integer +argument. @code{getproto} will accept either type, behaving like +@code{getprotoent} (see below) if no arguments are supplied. +@end deffn + +getserv +@c snarfed from net_db.c:452 +@deffn primitive getserv [name [protocol]] +@deffnx procedure getservbyname name protocol +@deffnx procedure getservbyport port protocol +Look up a network service by name or by service number, and return a +network service object. The @var{protocol} argument specifies the name +of the desired protocol; if the protocol found in the network service +database does not match this name, a system error is signalled. + +The @code{getserv} procedure will take either a service name or number +as its first argument; if given no arguments, it behaves like +@code{getservent} (see below). +@end deffn + +sethost +@c snarfed from net_db.c:491 +@deffn primitive sethost [stayopen] +If @var{stayopen} is omitted, this is equivalent to @code{endhostent}. +Otherwise it is equivalent to @code{sethostent stayopen}. +@end deffn + +setnet +@c snarfed from net_db.c:507 +@deffn primitive setnet [stayopen] +If @var{stayopen} is omitted, this is equivalent to @code{endnetent}. +Otherwise it is equivalent to @code{setnetent stayopen}. +@end deffn + +setproto +@c snarfed from net_db.c:523 +@deffn primitive setproto [stayopen] +If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}. +Otherwise it is equivalent to @code{setprotoent stayopen}. +@end deffn + +setserv +@c snarfed from net_db.c:539 +@deffn primitive setserv [stayopen] +If @var{stayopen} is omitted, this is equivalent to @code{endservent}. +Otherwise it is equivalent to @code{setservent stayopen}. +@end deffn + +exact? +@c snarfed from numbers.c:106 +@deffn primitive exact? x +Return @code{#t} if @var{x} is an exact number, @code{#f} +otherwise. +@end deffn + +odd? +@c snarfed from numbers.c:123 +@deffn primitive odd? n +Return @code{#t} if @var{n} is an odd number, @code{#f} +otherwise. +@end deffn + +even? +@c snarfed from numbers.c:140 +@deffn primitive even? n +Return @code{#t} if @var{n} is an even number, @code{#f} +otherwise. +@end deffn + +logand +@c snarfed from numbers.c:755 +@deffn primitive logand n1 n2 +Returns the integer which is the bit-wise AND of the two integer +arguments. + +Example: +@lisp +(number->string (logand #b1100 #b1010) 2) + @result{} "1000" +@end lisp +@end deffn + +logior +@c snarfed from numbers.c:842 +@deffn primitive logior n1 n2 +Returns the integer which is the bit-wise OR of the two integer +arguments. + +Example: +@lisp +(number->string (logior #b1100 #b1010) 2) + @result{} "1110" +@end lisp +@end deffn + +logxor +@c snarfed from numbers.c:928 +@deffn primitive logxor n1 n2 +Returns the integer which is the bit-wise XOR of the two integer +arguments. + +Example: +@lisp +(number->string (logxor #b1100 #b1010) 2) + @result{} "110" +@end lisp +@end deffn + +logtest +@c snarfed from numbers.c:997 +@deffn primitive logtest n1 n2 +@example +(logtest j k) @equiv{} (not (zero? (logand j k))) + +(logtest #b0100 #b1011) @result{} #f +(logtest #b0100 #b0111) @result{} #t +@end example +@end deffn + +logbit? +@c snarfed from numbers.c:1054 +@deffn primitive logbit? index j +@example +(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j) + +(logbit? 0 #b1101) @result{} #t +(logbit? 1 #b1101) @result{} #f +(logbit? 2 #b1101) @result{} #t +(logbit? 3 #b1101) @result{} #t +(logbit? 4 #b1101) @result{} #f +@end example +@end deffn + +lognot +@c snarfed from numbers.c:1102 +@deffn primitive lognot n +Returns the integer which is the 2s-complement of the integer argument. + +Example: +@lisp +(number->string (lognot #b10000000) 2) + @result{} "-10000001" +(number->string (lognot #b0) 2) + @result{} "-1" +@end lisp +@end deffn + +integer-expt +@c snarfed from numbers.c:1118 +@deffn primitive integer-expt n k +Returns @var{n} raised to the non-negative integer exponent @var{k}. + +Example: +@lisp +(integer-expt 2 5) + @result{} 32 +(integer-expt -3 3) + @result{} -27 +@end lisp +@end deffn + +ash +@c snarfed from numbers.c:1166 +@deffn primitive ash n cnt +The function ash performs an arithmetic shift left by @var{CNT} +bits (or shift right, if @var{cnt} is negative). +'Arithmetic' means, that the function does not guarantee to +keep the bit structure of @var{n}, but rather guarantees that +the result will always be rounded towards minus infinity. +Therefore, the results of ash and a corresponding bitwise +shift will differ if N is negative. + +Formally, the function returns an integer equivalent to +@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}. + +Example: +@lisp +(number->string (ash #b1 3) 2) + @result{} "1000" +(number->string (ash #b1010 -1) 2) + @result{} "101" +@end lisp +@end deffn + +bit-extract +@c snarfed from numbers.c:1219 +@deffn primitive bit-extract n start end +Returns the integer composed of the @var{start} (inclusive) through +@var{end} (exclusive) bits of @var{n}. The @var{start}th bit becomes +the 0-th bit in the result.@refill + +Example: +@lisp +(number->string (bit-extract #b1101101010 0 4) 2) + @result{} "1010" +(number->string (bit-extract #b1101101010 4 9) 2) + @result{} "10110" +@end lisp +@end deffn + +logcount +@c snarfed from numbers.c:1291 +@deffn primitive logcount n +Returns the number of bits in integer @var{n}. If integer is positive, +the 1-bits in its binary representation are counted. If negative, the +0-bits in its two's-complement binary representation are counted. If 0, +0 is returned. + +Example: +@lisp +(logcount #b10101010) + @result{} 4 +(logcount 0) + @result{} 0 +(logcount -2) + @result{} 1 +@end lisp +@end deffn + +integer-length +@c snarfed from numbers.c:1342 +@deffn primitive integer-length n +Returns the number of bits neccessary to represent @var{n}. + +Example: +@lisp +(integer-length #b10101010) + @result{} 8 +(integer-length 0) + @result{} 0 +(integer-length #b1111) + @result{} 4 +@end lisp +@end deffn + +number->string +@c snarfed from numbers.c:2288 +@deffn primitive number->string n [radix] +Return a string holding the external representation of the +number @var{n} in the given @var{radix}. If @var{n} is +inexact, a radix of 10 will be used. +@end deffn + +string->number +@c snarfed from numbers.c:2873 +@deffn primitive string->number string [radix] +Returns a number of the maximally precise representation +expressed by the given @var{string}. @var{radix} must be an +exact integer, either 2, 8, 10, or 16. If supplied, @var{radix} +is a default radix that may be overridden by an explicit radix +prefix in @var{string} (e.g. "#o177"). If @var{radix} is not +supplied, then the default radix is 10. If string is not a +syntactically valid notation for a number, then +@code{string->number} returns @code{#f}. +@end deffn + +number? +@c snarfed from numbers.c:2940 +@deffn primitive number? +scm_number_p +@end deffn + +complex? +@c snarfed from numbers.c:2952 +@deffn primitive complex? x +Return @code{#t} if @var{x} is a complex number, @code{#f} +else. Note that the sets of real, rational and integer +values form subsets of the set of complex numbers, i. e. the +predicate will also be fulfilled if @var{x} is a real, +rational or integer number. +@end deffn + +real? +@c snarfed from numbers.c:2960 +@deffn primitive real? +scm_real_p +@end deffn + +rational? +@c snarfed from numbers.c:2973 +@deffn primitive rational? x +Return @code{#t} if @var{x} is a rational number, @code{#f} +else. Note that the set of integer values forms a subset of +the set of rational numbers, i. e. the predicate will also be +fulfilled if @var{x} is an integer number. Real numbers +will also satisfy this predicate, because of their limited +precision. +@end deffn + +integer? +@c snarfed from numbers.c:2994 +@deffn primitive integer? x +Return @code{#t} if @var{x} is an integer number, @code{#f} +else. +@end deffn + +inexact? +@c snarfed from numbers.c:3019 +@deffn primitive inexact? x +Return @code{#t} if @var{x} is an inexact number, @code{#f} +else. +@end deffn + +$expt +@c snarfed from numbers.c:4071 +@deffn primitive $expt x y +Return @var{x} raised to the power of @var{y}. This +procedure does not accept complex arguments. +@end deffn + +$atan2 +@c snarfed from numbers.c:4087 +@deffn primitive $atan2 x y +Return the arc tangent of the two arguments @var{x} and +@var{y}. This is similar to calculating the arc tangent of +@var{x} / @var{y}, except that the signs of both arguments +are used to determine the quadrant of the result. This +procedure does not accept complex arguments. +@end deffn + +make-rectangular +@c snarfed from numbers.c:4100 +@deffn primitive make-rectangular real imaginary +Return a complex number constructed of the given @var{real} and +@var{imaginary} parts. +@end deffn + +make-polar +@c snarfed from numbers.c:4113 +@deffn primitive make-polar x y +Return the complex number @var{x} * e^(i * @var{y}). +@end deffn + +inexact->exact +@c snarfed from numbers.c:4231 +@deffn primitive inexact->exact z +Returns an exact number that is numerically closest to @var{z}. +@end deffn + +class-of +@c snarfed from objects.c:88 +@deffn primitive class-of x +Return the class of @var{x}. +@end deffn + +entity? +@c snarfed from objects.c:359 +@deffn primitive entity? obj +Return @code{#t} if @var{obj} is an entity. +@end deffn + +operator? +@c snarfed from objects.c:368 +@deffn primitive operator? obj +Return @code{#t} if @var{obj} is an operator. +@end deffn + +set-object-procedure! +@c snarfed from objects.c:380 +@deffn primitive set-object-procedure! obj proc +Return the object procedure of @var{obj} to @var{proc}. +@var{obj} must be either an entity or an operator. +@end deffn + +make-class-object +@c snarfed from objects.c:440 +@deffn primitive make-class-object metaclass layout +Create a new class object of class @var{metaclass}, with the +slot layout specified by @var{layout}. +@end deffn + +make-subclass-object +@c snarfed from objects.c:455 +@deffn primitive make-subclass-object class layout +Create a subclass object of @var{class}, with the slot layout +specified by @var{layout}. +@end deffn + +object-properties +@c snarfed from objprop.c:62 +@deffn primitive object-properties obj +@deffnx primitive procedure-properties obj +Return @var{obj}'s property list. +@end deffn + +set-object-properties! +@c snarfed from objprop.c:73 +@deffn primitive set-object-properties! obj plist +@deffnx primitive set-procedure-properties! obj alist +Set @var{obj}'s property list to @var{alist}. +@end deffn + +object-property +@c snarfed from objprop.c:85 +@deffn primitive object-property obj key +@deffnx primitive procedure-property obj key +Return the property of @var{obj} with name @var{key}. +@end deffn + +set-object-property! +@c snarfed from objprop.c:98 +@deffn primitive set-object-property! obj key val +@deffnx primitive set-procedure-property! obj key value +In @var{obj}'s property list, set the property named @var{key} to +@var{value}. +@end deffn + +cons +@c snarfed from pairs.c:61 +@deffn primitive cons x y +Returns a newly allocated pair whose car is @var{x} and whose cdr is +@var{y}. The pair is guaranteed to be different (in the sense of +@code{eqv?}) from every previously existing object. +@end deffn + +pair? +@c snarfed from pairs.c:93 +@deffn primitive pair? x +Returns @code{#t} if @var{x} is a pair; otherwise returns @code{#f}. +@end deffn + +set-car! +@c snarfed from pairs.c:104 +@deffn primitive set-car! pair value +Stores @var{value} in the car field of @var{pair}. The value returned +by @code{set-car!} is unspecified. +@end deffn + +set-cdr! +@c snarfed from pairs.c:117 +@deffn primitive set-cdr! pair value +Stores @var{value} in the cdr field of @var{pair}. The value returned +by @code{set-cdr!} is unspecified. +@end deffn + +char-ready? +@c snarfed from ports.c:246 +@deffn primitive char-ready? [port] +Returns @code{#t} if a character is ready on input @var{port} and +returns @code{#f} otherwise. If @code{char-ready?} returns @code{#t} +then the next @code{read-char} operation on @var{port} is +guaranteed not to hang. If @var{port} is a file port at end of +file then @code{char-ready?} returns @code{#t}. +@footnote{@code{char-ready?} exists to make it possible for a +program to accept characters from interactive ports without getting +stuck waiting for input. Any input editors associated with such ports +must make sure that characters whose existence has been asserted by +@code{char-ready?} cannot be rubbed out. If @code{char-ready?} were to +return @code{#f} at end of file, a port at end of file would be +indistinguishable from an interactive port that has no ready +characters.} +@end deffn + +drain-input +@c snarfed from ports.c:312 +@deffn primitive drain-input port +Drain @var{port}'s read buffers (including any pushed-back +characters) and returns the content as a single string. +@end deffn + +current-input-port +@c snarfed from ports.c:339 +@deffn primitive current-input-port +Return the current input port. This is the default port used +by many input procedures. Initially, @code{current-input-port} +returns the @dfn{standard input} in Unix and C terminology. +@end deffn + +current-output-port +@c snarfed from ports.c:351 +@deffn primitive current-output-port +Return the current output port. This is the default port used +by many output procedures. Initially, +@code{current-output-port} returns the @dfn{standard output} in +Unix and C terminology. +@end deffn + +current-error-port +@c snarfed from ports.c:361 +@deffn primitive current-error-port +Return the port to which errors and warnings should be sent (the +@dfn{standard error} in Unix and C terminology). +@end deffn + +current-load-port +@c snarfed from ports.c:371 +@deffn primitive current-load-port +Return the current-load-port. +The load port is used internally by @code{primitive-load}. +@end deffn + +set-current-input-port +@c snarfed from ports.c:384 +@deffn primitive set-current-input-port port +@deffnx primitive set-current-output-port port +@deffnx primitive set-current-error-port port +Change the ports returned by @code{current-input-port}, +@code{current-output-port} and @code{current-error-port}, respectively, +so that they use the supplied @var{port} for input or output. +@end deffn + +set-current-output-port +@c snarfed from ports.c:397 +@deffn primitive set-current-output-port port +Set the current default output port to @var{port}. +@end deffn + +set-current-error-port +@c snarfed from ports.c:411 +@deffn primitive set-current-error-port port +Set the current default error port to @var{port}. +@end deffn + +port-revealed +@c snarfed from ports.c:556 +@deffn primitive port-revealed port +Returns the revealed count for @var{port}. +@end deffn + +set-port-revealed! +@c snarfed from ports.c:569 +@deffn primitive set-port-revealed! port rcount +Sets the revealed count for a port to a given value. +The return value is unspecified. +@end deffn + +port-mode +@c snarfed from ports.c:612 +@deffn primitive port-mode port +Returns the port modes associated with the open port @var{port}. These +will not necessarily be identical to the modes used when the port was +opened, since modes such as "append" which are used only during +port creation are not retained. +@end deffn + +close-port +@c snarfed from ports.c:649 +@deffn primitive close-port port +Close the specified port object. Returns @code{#t} if it successfully +closes a port or @code{#f} if it was already +closed. An exception may be raised if an error occurs, for example +when flushing buffered output. +See also @ref{Ports and File Descriptors, close}, for a procedure +which can close file descriptors. +@end deffn + +close-input-port +@c snarfed from ports.c:677 +@deffn primitive close-input-port port +Close the specified input port object. The routine has no effect if +the file has already been closed. An exception may be raised if an +error occurs. The value returned is unspecified. + +See also @ref{Ports and File Descriptors, close}, for a procedure +which can close file descriptors. +@end deffn + +close-output-port +@c snarfed from ports.c:692 +@deffn primitive close-output-port port +Close the specified output port object. The routine has no effect if +the file has already been closed. An exception may be raised if an +error occurs. The value returned is unspecified. + +See also @ref{Ports and File Descriptors, close}, for a procedure +which can close file descriptors. +@end deffn + +port-for-each +@c snarfed from ports.c:709 +@deffn primitive port-for-each proc +Apply @var{proc} to each port in the Guile port table +in turn. The return value is unspecified. More specifically, +@var{proc} is applied exactly once to every port that exists +in the system at the time @var{port-for-each} is invoked. +Changes to the port table while @var{port-for-each} is running +have no effect as far as @var{port-for-each} is concerned. +@end deffn + +close-all-ports-except +@c snarfed from ports.c:752 +@deffn primitive close-all-ports-except . ports +[DEPRECATED] Close all open file ports used by the interpreter +except for those supplied as arguments. This procedure +was intended to be used before an exec call to close file descriptors +which are not needed in the new process. However it has the +undesirable side-effect of flushing buffes, so it's deprecated. +Use port-for-each instead. +@end deffn + +input-port? +@c snarfed from ports.c:791 +@deffn primitive input-port? x +Returns @code{#t} if @var{x} is an input port, otherwise returns +@code{#f}. Any object satisfying this predicate also satisfies +@code{port?}. +@end deffn + +output-port? +@c snarfed from ports.c:804 +@deffn primitive output-port? x +Returns @code{#t} if @var{x} is an output port, otherwise returns +@code{#f}. Any object satisfying this predicate also satisfies +@code{port?}. +@end deffn + +port? +@c snarfed from ports.c:819 +@deffn primitive port? x +Returns a boolean indicating whether @var{x} is a port. +Equivalent to @code{(or (input-port? @var{x}) (output-port? +@var{x}))}. +@end deffn + +port-closed? +@c snarfed from ports.c:828 +@deffn primitive port-closed? port +Returns @code{#t} if @var{port} is closed or @code{#f} if it is open. +@end deffn + +eof-object? +@c snarfed from ports.c:839 +@deffn primitive eof-object? x +Returns @code{#t} if @var{x} is an end-of-file object; otherwise +returns @code{#f}. +@end deffn + +force-output +@c snarfed from ports.c:853 +@deffn primitive force-output [port] +Flush the specified output port, or the current output port if @var{port} +is omitted. The current output buffer contents are passed to the +underlying port implementation (e.g., in the case of fports, the +data will be written to the file and the output buffer will be cleared.) +It has no effect on an unbuffered port. + +The return value is unspecified. +@end deffn + +flush-all-ports +@c snarfed from ports.c:871 +@deffn primitive flush-all-ports +Equivalent to calling @code{force-output} on +all open output ports. The return value is unspecified. +@end deffn + +read-char +@c snarfed from ports.c:889 +@deffn primitive read-char [port] +Returns the next character available from @var{port}, updating +@var{port} to point to the following character. If no more +characters are available, an end-of-file object is returned. +@end deffn + +peek-char +@c snarfed from ports.c:1205 +@deffn primitive peek-char [port] +Returns the next character available from @var{port}, +@emph{without} updating @var{port} to point to the following +character. If no more characters are available, an end-of-file object +is returned.@footnote{The value returned by a call to @code{peek-char} +is the same as the value that would have been returned by a call to +@code{read-char} on the same port. The only difference is that the very +next call to @code{read-char} or @code{peek-char} on that +@var{port} will return the value returned by the preceding call to +@code{peek-char}. In particular, a call to @code{peek-char} on an +interactive port will hang waiting for input whenever a call to +@code{read-char} would have hung.} +@end deffn + +unread-char +@c snarfed from ports.c:1226 +@deffn primitive unread-char cobj [port] +Place @var{char} in @var{port} so that it will be read by the +next read operation. If called multiple times, the unread characters +will be read again in last-in first-out order. If @var{port} is +not supplied, the current input port is used. +@end deffn + +unread-string +@c snarfed from ports.c:1249 +@deffn primitive unread-string str port +Place the string @var{str} in @var{port} so that its characters will be +read in subsequent read operations. If called multiple times, the +unread characters will be read again in last-in first-out order. If +@var{port} is not supplied, the current-input-port is used. +@end deffn + +seek +@c snarfed from ports.c:1285 +@deffn primitive seek object offset whence +Sets the current position of @var{fd/port} to the integer @var{offset}, +which is interpreted according to the value of @var{whence}. + +One of the following variables should be supplied +for @var{whence}: +@defvar SEEK_SET +Seek from the beginning of the file. +@end defvar +@defvar SEEK_CUR +Seek from the current position. +@end defvar +@defvar SEEK_END +Seek from the end of the file. +@end defvar + +If @var{fd/port} is a file descriptor, the underlying system call is +@code{lseek}. @var{port} may be a string port. + +The value returned is the new position in the file. This means that +the current position of a port can be obtained using: +@smalllisp +(seek port 0 SEEK_CUR) +@end smalllisp +@end deffn + +truncate-file +@c snarfed from ports.c:1326 +@deffn primitive truncate-file object [length] +Truncates the object referred to by @var{obj} to at most @var{size} bytes. +@var{obj} can be a string containing a file name or an integer file +descriptor or a port. @var{size} may be omitted if @var{obj} is not +a file name, in which case the truncation occurs at the current port. +position. + +The return value is unspecified. +@end deffn + +port-line +@c snarfed from ports.c:1380 +@deffn primitive port-line port +Return the current line number for @var{port}. +@end deffn + +set-port-line! +@c snarfed from ports.c:1391 +@deffn primitive set-port-line! port line +Set the current line number for @var{port} to @var{line}. +@end deffn + +port-column +@c snarfed from ports.c:1412 +@deffn primitive port-column port +@deffnx primitive port-line port +Return the current column number or line number of @var{port}, +using the current input port if none is specified. If the number is +unknown, the result is #f. Otherwise, the result is a 0-origin integer +- i.e. the first character of the first line is line 0, column 0. +(However, when you display a file position, for example in an error +message, we recommend you add 1 to get 1-origin integers. This is +because lines and column numbers traditionally start with 1, and that is +what non-programmers will find most natural.) +@end deffn + +set-port-column! +@c snarfed from ports.c:1425 +@deffn primitive set-port-column! port column +@deffnx primitive set-port-line! port line +Set the current column or line number of @var{port}, using the +current input port if none is specified. +@end deffn + +port-filename +@c snarfed from ports.c:1440 +@deffn primitive port-filename port +Return the filename associated with @var{port}. This function returns +the strings "standard input", "standard output" and "standard error" +when called on the current input, output and error ports respectively. +@end deffn + +set-port-filename! +@c snarfed from ports.c:1454 +@deffn primitive set-port-filename! port filename +Change the filename associated with @var{port}, using the current input +port if none is specified. Note that this does not change the port's +source of data, but only the value that is returned by +@code{port-filename} and reported in diagnostic output. +@end deffn + +%make-void-port +@c snarfed from ports.c:1546 +@deffn primitive %make-void-port mode +Create and return a new void port. A void port acts like +/dev/null. The @var{mode} argument +specifies the input/output modes for this port: see the +documentation for @code{open-file} in @ref{File Ports}. +@end deffn + +pipe +@c snarfed from posix.c:201 +@deffn primitive pipe +Returns a newly created pipe: a pair of ports which are linked +together on the local machine. The CAR is the input port and +the CDR is the output port. Data written (and flushed) to the +output port can be read from the input port. +Pipes are commonly used for communication with a newly +forked child process. The need to flush the output port +can be avoided by making it unbuffered using @code{setvbuf}. + +Writes occur atomically provided the size of the data in +bytes is not greater than the value of @code{PIPE_BUF} +Note that the output port is likely to block if too much data +(typically equal to @code{PIPE_BUF}) has been written but not +yet read from the input port +@end deffn + +getgroups +@c snarfed from posix.c:221 +@deffn primitive getgroups +Returns a vector of integers representing the current supplimentary group IDs. +@end deffn + +getpw +@c snarfed from posix.c:254 +@deffn primitive getpw [user] +Look up an entry in the user database. @var{obj} can be an integer, +a string, or omitted, giving the behaviour of getpwuid, getpwnam +or getpwent respectively. +@end deffn + +setpw +@c snarfed from posix.c:307 +@deffn primitive setpw [arg] +If called with a true argument, initialize or reset the password data +stream. Otherwise, close the stream. The @code{setpwent} and +@code{endpwent} procedures are implemented on top of this. +@end deffn + +getgr +@c snarfed from posix.c:326 +@deffn primitive getgr [name] +Look up an entry in the group database. @var{obj} can be an integer, +a string, or omitted, giving the behaviour of getgrgid, getgrnam +or getgrent respectively. +@end deffn + +setgr +@c snarfed from posix.c:367 +@deffn primitive setgr [arg] +If called with a true argument, initialize or reset the group data +stream. Otherwise, close the stream. The @code{setgrent} and +@code{endgrent} procedures are implemented on top of this. +@end deffn + +kill +@c snarfed from posix.c:403 +@deffn primitive kill pid sig +Sends a signal to the specified process or group of processes. + +@var{pid} specifies the processes to which the signal is sent: + +@table @r +@item @var{pid} greater than 0 +The process whose identifier is @var{pid}. +@item @var{pid} equal to 0 +All processes in the current process group. +@item @var{pid} less than -1 +The process group whose identifier is -@var{pid} +@item @var{pid} equal to -1 +If the process is privileged, all processes except for some special +system processes. Otherwise, all processes with the current effective +user ID. +@end table + +@var{sig} should be specified using a variable corresponding to +the Unix symbolic name, e.g., + +@defvar SIGHUP +Hang-up signal. +@end defvar + +@defvar SIGINT +Interrupt signal. +@end defvar +@end deffn + +waitpid +@c snarfed from posix.c:451 +@deffn primitive waitpid pid [options] +This procedure collects status information from a child process which +has terminated or (optionally) stopped. Normally it will +suspend the calling process until this can be done. If more than one +child process is eligible then one will be chosen by the operating system. + +The value of @var{pid} determines the behaviour: + +@table @r +@item @var{pid} greater than 0 +Request status information from the specified child process. +@item @var{pid} equal to -1 or WAIT_ANY +Request status information for any child process. +@item @var{pid} equal to 0 or WAIT_MYPGRP +Request status information for any child process in the current process +group. +@item @var{pid} less than -1 +Request status information for any child process whose process group ID +is -@var{PID}. +@end table + +The @var{options} argument, if supplied, should be the bitwise OR of the +values of zero or more of the following variables: + +@defvar WNOHANG +Return immediately even if there are no child processes to be collected. +@end defvar + +@defvar WUNTRACED +Report status information for stopped processes as well as terminated +processes. +@end defvar + +The return value is a pair containing: + +@enumerate +@item +The process ID of the child process, or 0 if @code{WNOHANG} was +specified and no process was collected. +@item +The integer status value. +@end enumerate +@end deffn + +status:exit-val +@c snarfed from posix.c:478 +@deffn primitive status:exit-val status +Returns the exit status value, as would be +set if a process ended normally through a +call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}. +@end deffn + +status:term-sig +@c snarfed from posix.c:498 +@deffn primitive status:term-sig status +Returns the signal number which terminated the +process, if any, otherwise @code{#f}. +@end deffn + +status:stop-sig +@c snarfed from posix.c:516 +@deffn primitive status:stop-sig status +Returns the signal number which stopped the +process, if any, otherwise @code{#f}. +@end deffn + +getppid +@c snarfed from posix.c:533 +@deffn primitive getppid +Returns an integer representing the process ID of the parent process. +@end deffn + +getuid +@c snarfed from posix.c:544 +@deffn primitive getuid +Returns an integer representing the current real user ID. +@end deffn + +getgid +@c snarfed from posix.c:555 +@deffn primitive getgid +Returns an integer representing the current real group ID. +@end deffn + +geteuid +@c snarfed from posix.c:569 +@deffn primitive geteuid +Returns an integer representing the current effective user ID. +If the system does not support effective IDs, then the real ID +is returned. @code{(feature? 'EIDs)} reports whether the system +supports effective IDs. +@end deffn + +getegid +@c snarfed from posix.c:587 +@deffn primitive getegid +Returns an integer representing the current effective group ID. +If the system does not support effective IDs, then the real ID +is returned. @code{(feature? 'EIDs)} reports whether the system +supports effective IDs. +@end deffn + +setuid +@c snarfed from posix.c:603 +@deffn primitive setuid id +Sets both the real and effective user IDs to the integer @var{id}, provided +the process has appropriate privileges. +The return value is unspecified. +@end deffn + +setgid +@c snarfed from posix.c:617 +@deffn primitive setgid id +Sets both the real and effective group IDs to the integer @var{id}, provided +the process has appropriate privileges. +The return value is unspecified. +@end deffn + +seteuid +@c snarfed from posix.c:633 +@deffn primitive seteuid id +Sets the effective user ID to the integer @var{id}, provided the process +has appropriate privileges. If effective IDs are not supported, the +real ID is set instead -- @code{(feature? 'EIDs)} reports whether the +system supports effective IDs. +The return value is unspecified. +@end deffn + +setegid +@c snarfed from posix.c:657 +@deffn primitive setegid id +Sets the effective group ID to the integer @var{id}, provided the process +has appropriate privileges. If effective IDs are not supported, the +real ID is set instead -- @code{(feature? 'EIDs)} reports whether the +system supports effective IDs. +The return value is unspecified. +@end deffn + +getpgrp +@c snarfed from posix.c:679 +@deffn primitive getpgrp +Returns an integer representing the current process group ID. +This is the POSIX definition, not BSD. +@end deffn + +setpgid +@c snarfed from posix.c:695 +@deffn primitive setpgid pid pgid +Move the process @var{pid} into the process group @var{pgid}. @var{pid} or +@var{pgid} must be integers: they can be zero to indicate the ID of the +current process. +Fails on systems that do not support job control. +The return value is unspecified. +@end deffn + +setsid +@c snarfed from posix.c:714 +@deffn primitive setsid +Creates a new session. The current process becomes the session leader +and is put in a new process group. The process will be detached +from its controlling terminal if it has one. +The return value is an integer representing the new process group ID. +@end deffn + +ttyname +@c snarfed from posix.c:728 +@deffn primitive ttyname port +Returns a string with the name of the serial terminal device underlying +@var{port}. +@end deffn + +ctermid +@c snarfed from posix.c:751 +@deffn primitive ctermid +Returns a string containing the file name of the controlling terminal +for the current process. +@end deffn + +tcgetpgrp +@c snarfed from posix.c:773 +@deffn primitive tcgetpgrp port +Returns the process group ID of the foreground +process group associated with the terminal open on the file descriptor +underlying @var{port}. + +If there is no foreground process group, the return value is a +number greater than 1 that does not match the process group ID +of any existing process group. This can happen if all of the +processes in the job that was formerly the foreground job have +terminated, and no other job has yet been moved into the +foreground. +@end deffn + +tcsetpgrp +@c snarfed from posix.c:797 +@deffn primitive tcsetpgrp port pgid +Set the foreground process group ID for the terminal used by the file +descriptor underlying @var{port} to the integer @var{pgid}. +The calling process +must be a member of the same session as @var{pgid} and must have the same +controlling terminal. The return value is unspecified. +@end deffn + +execl +@c snarfed from posix.c:857 +@deffn primitive execl filename . args +Executes the file named by @var{path} as a new process image. +The remaining arguments are supplied to the process; from a C program +they are accessable as the @code{argv} argument to @code{main}. +Conventionally the first @var{arg} is the same as @var{path}. +All arguments must be strings. + +If @var{arg} is missing, @var{path} is executed with a null +argument list, which may have system-dependent side-effects. + +This procedure is currently implemented using the @code{execv} system +call, but we call it @code{execl} because of its Scheme calling interface. +@end deffn + +execlp +@c snarfed from posix.c:878 +@deffn primitive execlp filename . args +Similar to @code{execl}, however if +@var{filename} does not contain a slash +then the file to execute will be located by searching the +directories listed in the @code{PATH} environment variable. + +This procedure is currently implemented using the @code{execvp} system +call, but we call it @code{execlp} because of its Scheme calling interface. +@end deffn + +execle +@c snarfed from posix.c:929 +@deffn primitive execle filename env . args +Similar to @code{execl}, but the environment of the new process is +specified by @var{env}, which must be a list of strings as returned by the +@code{environ} procedure. + +This procedure is currently implemented using the @code{execve} system +call, but we call it @code{execle} because of its Scheme calling interface. +@end deffn + +primitive-fork +@c snarfed from posix.c:953 +@deffn primitive primitive-fork +Creates a new "child" process by duplicating the current "parent" process. +In the child the return value is 0. In the parent the return value is +the integer process ID of the child. + +This procedure has been renamed from @code{fork} to avoid a naming conflict +with the scsh fork. +@end deffn + +uname +@c snarfed from posix.c:968 +@deffn primitive uname +Returns an object with some information about the computer system the +program is running on. +@end deffn + +environ +@c snarfed from posix.c:997 +@deffn primitive environ [env] +If @var{env} is omitted, returns the current environment as a list of strings. +Otherwise it sets the current environment, which is also the +default environment for child processes, to the supplied list of strings. +Each member of @var{env} should be of the form +@code{NAME=VALUE} and values of @code{NAME} should not be duplicated. +If @var{env} is supplied then the return value is unspecified. +@end deffn + +tmpnam +@c snarfed from posix.c:1035 +@deffn primitive tmpnam +tmpnam returns a name in the file system that does not match +any existing file. However there is no guarantee that +another process will not create the file after tmpnam +is called. Care should be taken if opening the file, +e.g., use the O_EXCL open flag or use @code{mkstemp!} instead. +@end deffn + +mkstemp! +@c snarfed from posix.c:1058 +@deffn primitive mkstemp! tmpl +mkstemp creates a new unique file in the file system and +returns a new buffered port open for reading and writing to +the file. @var{tmpl} is a string specifying where the +file should be created: it must end with @code{XXXXXX} +and will be changed in place to return the name of the +temporary file. +@end deffn + +utime +@c snarfed from posix.c:1086 +@deffn primitive utime pathname [actime [modtime]] +@code{utime} sets the access and modification times for +the file named by @var{path}. If @var{actime} or @var{modtime} +is not supplied, then the current time is used. +@var{actime} and @var{modtime} +must be integer time values as returned by the @code{current-time} +procedure. + +E.g., + +@smalllisp +(utime "foo" (- (current-time) 3600)) +@end smalllisp + +will set the access time to one hour in the past and the modification +time to the current time. +@end deffn + +access? +@c snarfed from posix.c:1135 +@deffn primitive access? path how +Returns @code{#t} if @var{path} corresponds to an existing +file and the current process +has the type of access specified by @var{how}, otherwise +@code{#f}. +@var{how} should be specified +using the values of the variables listed below. Multiple values can +be combined using a bitwise or, in which case @code{#t} will only +be returned if all accesses are granted. + +Permissions are checked using the real id of the current process, +not the effective id, although it's the effective id which determines +whether the access would actually be granted. + +@defvar R_OK +test for read permission. +@end defvar +@defvar W_OK +test for write permission. +@end defvar +@defvar X_OK +test for execute permission. +@end defvar +@defvar F_OK +test for existence of the file. +@end defvar +@end deffn + +getpid +@c snarfed from posix.c:1150 +@deffn primitive getpid +Returns an integer representing the current process ID. +@end deffn + +putenv +@c snarfed from posix.c:1167 +@deffn primitive putenv str +Modifies the environment of the current process, which is +also the default environment inherited by child processes. + +If @var{string} is of the form @code{NAME=VALUE} then it will be written +directly into the environment, replacing any existing environment string +with +name matching @code{NAME}. If @var{string} does not contain an equal +sign, then any existing string with name matching @var{string} will +be removed. + +The return value is unspecified. +@end deffn + +setlocale +@c snarfed from posix.c:1198 +@deffn primitive setlocale category [locale] +If @var{locale} is omitted, returns the current value of the specified +locale category +as a system-dependent string. +@var{category} should be specified using the values @code{LC_COLLATE}, +@code{LC_ALL} etc. + +Otherwise the specified locale category is set to +the string @var{locale} +and the new value is returned as a system-dependent string. If @var{locale} +is an empty string, the locale will be set using envirionment variables. +@end deffn + +mknod +@c snarfed from posix.c:1239 +@deffn primitive mknod path type perms dev +Creates a new special file, such as a file corresponding to a device. +@var{path} specifies the name of the file. @var{type} should +be one of the following symbols: +regular, directory, symlink, block-special, char-special, +fifo, or socket. @var{perms} (an integer) specifies the file permissions. +@var{dev} (an integer) specifies which device the special file refers +to. Its exact interpretation depends on the kind of special file +being created. + +E.g., +@example +(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2)) +@end example + +The return value is unspecified. +@end deffn + +nice +@c snarfed from posix.c:1286 +@deffn primitive nice incr +Increment the priority of the current process by @var{incr}. A higher +priority value means that the process runs less often. +The return value is unspecified. +@end deffn + +sync +@c snarfed from posix.c:1301 +@deffn primitive sync +Flush the operating system disk buffers. +The return value is unspecified. +@end deffn + +crypt +@c snarfed from posix.c:1314 +@deffn primitive crypt key salt +Encrypt @var{key} using @var{salt} as the salt value to the +crypt(3) library call +@end deffn + +chroot +@c snarfed from posix.c:1337 +@deffn primitive chroot path +Change the root directory to that specified in @var{path}. +This directory will be used for path names beginning with +@file{/}. The root directory is inherited by all children +of the current process. Only the superuser may change the +root directory. +@end deffn + +getlogin +@c snarfed from posix.c:1355 +@deffn primitive getlogin +Return a string containing the name of the user logged in on +the controlling terminal of the process, or @code{#f} if this +information cannot be obtained. +@end deffn + +cuserid +@c snarfed from posix.c:1373 +@deffn primitive cuserid +Return a string containing a user name associated with the +effective user id of the process. Return @code{#f} if this +information cannot be obtained. +@end deffn + +getpriority +@c snarfed from posix.c:1398 +@deffn primitive getpriority which who +Return the scheduling priority of the process, process group +or user, as indicated by @var{which} and @var{who}. @var{which} +is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} +or @code{PRIO_USER}, and @var{who} is interpreted relative to +@var{which} (a process identifier for @code{PRIO_PROCESS}, +process group identifier for @code{PRIO_PGRP}, and a user +identifier for @code{PRIO_USER}. A zero value of @var{who} +denotes the current process, process group, or user. Return +the highest priority (lowest numerical value) of any of the +specified processes. +@end deffn + +setpriority +@c snarfed from posix.c:1432 +@deffn primitive setpriority which who prio +Set the scheduling priority of the process, process group +or user, as indicated by @var{which} and @var{who}. @var{which} +is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} +or @code{PRIO_USER}, and @var{who} is interpreted relative to +@var{which} (a process identifier for @code{PRIO_PROCESS}, +process group identifier for @code{PRIO_PGRP}, and a user +identifier for @code{PRIO_USER}. A zero value of @var{who} +denotes the current process, process group, or user. +@var{prio} is a value in the range -20 and 20, the default +priority is 0; lower priorities cause more favorable +scheduling. Sets the priority of all of the specified +processes. Only the super-user may lower priorities. +The return value is not specified. +@end deffn + +getpass +@c snarfed from posix.c:1457 +@deffn primitive getpass prompt +Display @var{prompt} to the standard error output and read +a password from @file{/dev/tty}. If this file is not +accessible, it reads from standard input. The password may be +up to 127 characters in length. Additional characters and the +terminating newline character are discarded. While reading +the password, echoing and the generation of signals by special +characters is disabled. +@end deffn + +flock +@c snarfed from posix.c:1496 +@deffn primitive flock file operation +Apply or remove an advisory lock on an open file. +@var{operation} specifies the action to be done: +@table @code +@item LOCK_SH +Shared lock. More than one process may hold a shared lock +for a given file at a given time. +@item LOCK_EX +Exclusive lock. Only one process may hold an exclusive lock +for a given file at a given time. +@item LOCK_UN +Unlock the file. +@item LOCK_NB +Don't block when locking. May be specified by bitwise OR'ing +it to one of the other operations. +@end table +The return value is not specified. @var{file} may be an open +file descriptor or an open file descriptior port. +@end deffn + +sethostname +@c snarfed from posix.c:1522 +@deffn primitive sethostname name +Set the host name of the current processor to @var{name}. May +only be used by the superuser. The return value is not +specified. +@end deffn + +gethostname +@c snarfed from posix.c:1538 +@deffn primitive gethostname +Return the host name of the current processor. +@end deffn + +print-options-interface +@c snarfed from print.c:142 +@deffn primitive print-options-interface [setting] +Option interface for the print options. Instead of using +this procedure directly, use the procedures +@code{print-enable}, @code{print-disable}, @code{print-set!} +and @code{print-options}. +@end deffn + +simple-format +@c snarfed from print.c:980 +@deffn primitive simple-format destination message . args +Write @var{message} to @var{destination}, defaulting to +the current output port. +@var{message} can contain @code{~A} (was @code{%s}) and +@code{~S} (was @code{%S}) escapes. When printed, +the escapes are replaced with corresponding members of +@var{ARGS}: +@code{~A} formats using @code{display} and @code{~S} formats +using @code{write}. +If @var{destination} is @code{#t}, then use the current output +port, if @var{destination} is @code{#f}, then return a string +containing the formatted text. Does not add a trailing newline. +@end deffn + +newline +@c snarfed from print.c:1045 +@deffn primitive newline [port] +Send a newline to @var{port}. +@end deffn + +write-char +@c snarfed from print.c:1060 +@deffn primitive write-char chr [port] +Send character @var{chr} to @var{port}. +@end deffn + +port-with-print-state +@c snarfed from print.c:1114 +@deffn primitive port-with-print-state port pstate +Create a new port which behaves like @var{port}, but with an +included print state @var{pstate}. +@end deffn + +get-print-state +@c snarfed from print.c:1129 +@deffn primitive get-print-state port +Return the print state of the port @var{port}. If @var{port} +has no associated print state, @code{#f} is returned. +@end deffn + +procedure-properties +@c snarfed from procprop.c:180 +@deffn primitive procedure-properties proc +Return @var{obj}'s property list. +@end deffn + +set-procedure-properties! +@c snarfed from procprop.c:193 +@deffn primitive set-procedure-properties! proc new_val +Set @var{obj}'s property list to @var{alist}. +@end deffn + +procedure-property +@c snarfed from procprop.c:206 +@deffn primitive procedure-property p k +Return the property of @var{obj} with name @var{key}. +@end deffn + +set-procedure-property! +@c snarfed from procprop.c:229 +@deffn primitive set-procedure-property! p k v +In @var{obj}'s property list, set the property named @var{key} to +@var{value}. +@end deffn + +procedure? +@c snarfed from procs.c:196 +@deffn primitive procedure? obj +Return @code{#t} if @var{obj} is a procedure. +@end deffn + +closure? +@c snarfed from procs.c:223 +@deffn primitive closure? obj +Return @code{#t} if @var{obj} is a closure. +@end deffn + +thunk? +@c snarfed from procs.c:232 +@deffn primitive thunk? obj +Return @code{#t} if @var{obj} is a thunk. +@end deffn + +procedure-documentation +@c snarfed from procs.c:283 +@deffn primitive procedure-documentation proc +Return the documentation string associated with @code{proc}. By +convention, if a procedure contains more than one expression and the +first expression is a string constant, that string is assumed to contain +documentation for that procedure. +@end deffn + +procedure-with-setter? +@c snarfed from procs.c:319 +@deffn primitive procedure-with-setter? obj +Return @code{#t} if @var{obj} is a procedure with an +associated setter procedure. +@end deffn + +make-procedure-with-setter +@c snarfed from procs.c:329 +@deffn primitive make-procedure-with-setter procedure setter +Create a new procedure which behaves like @var{procedure}, but +with the associated setter @var{setter}. +@end deffn + +procedure +@c snarfed from procs.c:348 +@deffn primitive procedure proc +Return the procedure of @var{proc}, which must be either a +procedure with setter, or an operator struct. +@end deffn + +primitive-make-property +@c snarfed from properties.c:66 +@deffn primitive primitive-make-property not_found_proc +Create a @dfn{property token} that can be used with +@code{primitive-property-ref} and @code{primitive-property-set!}. +See @code{primitive-property-ref} for the significance of +@var{not_found_proc}. +@end deffn + +primitive-property-ref +@c snarfed from properties.c:83 +@deffn primitive primitive-property-ref prop obj +Return the property @var{prop} of @var{obj}. When no value +has yet been associated with @var{prop} and @var{obj}, call +@var{not-found-proc} instead (see @code{primitive-make-property}) +and use its return value. That value is also associated with +@var{obj} via @code{primitive-property-set!}. When +@var{not-found-proc} is @code{#f}, use @code{#f} as the +default value of @var{prop}. +@end deffn + +primitive-property-set! +@c snarfed from properties.c:111 +@deffn primitive primitive-property-set! prop obj val +Associate @var{code} with @var{prop} and @var{obj}. +@end deffn + +primitive-property-del! +@c snarfed from properties.c:131 +@deffn primitive primitive-property-del! prop obj +Remove any value associated with @var{prop} and @var{obj}. +@end deffn + +array-fill! +@c snarfed from ramap.c:467 +@deffn primitive array-fill! ra fill +Stores @var{fill} in every element of @var{array}. The value returned +is unspecified. +@end deffn + +array-copy-in-order! +@c snarfed from ramap.c:832 +@deffn primitive array-copy-in-order! +scm_array_copy_x +@end deffn + +array-copy! +@c snarfed from ramap.c:841 +@deffn primitive array-copy! src dst +@deffnx primitive array-copy-in-order! src dst +Copies every element from vector or array @var{source} to the +corresponding element of @var{destination}. @var{destination} must have +the same rank as @var{source}, and be at least as large in each +dimension. The order is unspecified. +@end deffn + +array-map-in-order! +@c snarfed from ramap.c:1515 +@deffn primitive array-map-in-order! +scm_array_map_x +@end deffn + +array-map! +@c snarfed from ramap.c:1526 +@deffn primitive array-map! ra0 proc . lra +@deffnx primitive array-map-in-order! ra0 proc . lra +@var{array1}, @dots{} must have the same number of dimensions as +@var{array0} and have a range for each index which includes the range +for the corresponding index in @var{array0}. @var{proc} is applied to +each tuple of elements of @var{array1} @dots{} and the result is stored +as the corresponding element in @var{array0}. The value returned is +unspecified. The order of application is unspecified. +@end deffn + +array-for-each +@c snarfed from ramap.c:1673 +@deffn primitive array-for-each proc ra0 . lra +@var{proc} is applied to each tuple of elements of @var{array0} @dots{} +in row-major order. The value returned is unspecified. +@end deffn + +array-index-map! +@c snarfed from ramap.c:1701 +@deffn primitive array-index-map! ra proc +applies @var{proc} to the indices of each element of @var{array} in +turn, storing the result in the corresponding element. The value +returned and the order of application are unspecified. + +One can implement @var{array-indexes} as +@example +(define (array-indexes array) + (let ((ra (apply make-array #f (array-shape array)))) + (array-index-map! ra (lambda x x)) + ra)) +@end example +Another example: +@example +(define (apl:index-generator n) + (let ((v (make-uniform-vector n 1))) + (array-index-map! v (lambda (i) i)) + v)) +@end example +@end deffn + +random +@c snarfed from random.c:370 +@deffn primitive random n [state] +Return a number in [0,N). +Accepts a positive integer or real n and returns a +number of the same type between zero (inclusive) and +N (exclusive). The values returned have a uniform +distribution. +The optional argument @var{state} must be of the type produced +by @code{seed->random-state}. It defaults to the value of the +variable @var{*random-state*}. This object is used to maintain +the state of the pseudo-random-number generator and is altered +as a side effect of the random operation. +@end deffn + +copy-random-state +@c snarfed from random.c:393 +@deffn primitive copy-random-state [state] +Return a copy of the random state @var{state}. +@end deffn + +seed->random-state +@c snarfed from random.c:405 +@deffn primitive seed->random-state seed +Return a new random state using @var{seed}. +@end deffn + +random:uniform +@c snarfed from random.c:418 +@deffn primitive random:uniform [state] +Returns a uniformly distributed inexact real random number in [0,1). +@end deffn + +random:normal +@c snarfed from random.c:433 +@deffn primitive random:normal [state] +Returns an inexact real in a normal distribution. +The distribution used has mean 0 and standard deviation 1. +For a normal distribution with mean m and standard deviation +d use @code{(+ m (* d (random:normal)))}. +@end deffn + +random:solid-sphere! +@c snarfed from random.c:489 +@deffn primitive random:solid-sphere! v [state] +Fills vect with inexact real random numbers +the sum of whose squares is less than 1.0. +Thinking of vect as coordinates in space of +dimension n = (vector-length vect), the coordinates +are uniformly distributed within the unit n-shere. +The sum of the squares of the numbers is returned. +@end deffn + +random:hollow-sphere! +@c snarfed from random.c:512 +@deffn primitive random:hollow-sphere! v [state] +Fills vect with inexact real random numbers +the sum of whose squares is equal to 1.0. +Thinking of vect as coordinates in space of +dimension n = (vector-length vect), the coordinates +are uniformly distributed over the surface of the +unit n-shere. +@end deffn + +random:normal-vector! +@c snarfed from random.c:530 +@deffn primitive random:normal-vector! v [state] +Fills vect with inexact real random numbers that are +independent and standard normally distributed +(i.e., with mean 0 and variance 1). +@end deffn + +random:exp +@c snarfed from random.c:554 +@deffn primitive random:exp [state] +Returns an inexact real in an exponential distribution with mean 1. +For an exponential distribution with mean u use (* u (random:exp)). +@end deffn + +%read-delimited! +@c snarfed from rdelim.c:78 +@deffn primitive %read-delimited! delims str gobble [port [start [end]]] +Read characters from @var{port} into @var{str} until one of the +characters in the @var{delims} string is encountered. If +@var{gobble} is true, discard the delimiter character; +otherwise, leave it in the input stream for the next read. If +@var{port} is not specified, use the value of +@code{(current-input-port)}. If @var{start} or @var{end} are +specified, store data only into the substring of @var{str} +bounded by @var{start} and @var{end} (which default to the +beginning and end of the string, respectively). + Return a pair consisting of the delimiter that terminated the +string and the number of characters read. If reading stopped +at the end of file, the delimiter returned is the +@var{eof-object}; if the string was filled without encountering +a delimiter, this value is @code{#f}. +@end deffn + +%read-line +@c snarfed from rdelim.c:223 +@deffn primitive %read-line [port] +Read a newline-terminated line from @var{port}, allocating storage as +necessary. The newline terminator (if any) is removed from the string, +and a pair consisting of the line and its delimiter is returned. The +delimiter may be either a newline or the @var{eof-object}; if +@code{%read-line} is called at the end of file, it returns the pair +@code{(#<eof> . #<eof>)}. +@end deffn + +write-line +@c snarfed from rdelim.c:277 +@deffn primitive write-line obj [port] +Display @var{obj} and a newline character to @var{port}. If @var{port} +is not specified, @code{(current-output-port)} is used. This function +is equivalent to: + +@smalllisp +(display obj [port]) +(newline [port]) +@end smalllisp +@end deffn + +read-options-interface +@c snarfed from read.c:84 +@deffn primitive read-options-interface [setting] +Option interface for the read options. Instead of using +this procedure directly, use the procedures @code{read-enable}, +@code{read-disable}, @code{read-set!} and @var{read-options}. +@end deffn + +read +@c snarfed from read.c:104 +@deffn primitive read [port] +Read an s-expression from the input port @var{port}, or from +the current input port if @var{port} is not specified. +Any whitespace before the next token is discarded. +@end deffn + +read-hash-extend +@c snarfed from read.c:746 +@deffn primitive read-hash-extend chr proc +Install the procedure @var{proc} for reading expressions +starting with the character sequence @code{#} and @var{chr}. +@var{proc} will be called with two arguments: the character +@var{chr} and the port to read further data from. The object +returned will be the return value of @code{read}. +@end deffn + +regexp? +@c snarfed from regex-posix.c:139 +@deffn primitive regexp? x +Return @code{#t} if @var{obj} is a compiled regular expression, or +@code{#f} otherwise. +@end deffn + +make-regexp +@c snarfed from regex-posix.c:179 +@deffn primitive make-regexp pat . flags +Compile the regular expression described by @var{str}, and return the +compiled regexp structure. If @var{str} does not describe a legal +regular expression, @code{make-regexp} throws a +@code{regular-expression-syntax} error. + +The @var{flag} arguments change the behavior of the compiled regexp. +The following flags may be supplied: + +@table @code +@item regexp/icase +Consider uppercase and lowercase letters to be the same when matching. + +@item regexp/newline +If a newline appears in the target string, then permit the @samp{^} and +@samp{$} operators to match immediately after or immediately before the +newline, respectively. Also, the @samp{.} and @samp{[^...]} operators +will never match a newline character. The intent of this flag is to +treat the target string as a buffer containing many lines of text, and +the regular expression as a pattern that may match a single one of those +lines. + +@item regexp/basic +Compile a basic (``obsolete'') regexp instead of the extended +(``modern'') regexps that are the default. Basic regexps do not +consider @samp{|}, @samp{+} or @samp{?} to be special characters, and +require the @samp{@{...@}} and @samp{(...)} metacharacters to be +backslash-escaped (@pxref{Backslash Escapes}). There are several other +differences between basic and extended regular expressions, but these +are the most significant. + +@item regexp/extended +Compile an extended regular expression rather than a basic regexp. This +is the default behavior; this flag will not usually be needed. If a +call to @code{make-regexp} includes both @code{regexp/basic} and +@code{regexp/extended} flags, the one which comes last will override +the earlier one. +@end table +@end deffn + +regexp-exec +@c snarfed from regex-posix.c:226 +@deffn primitive regexp-exec rx str [start [flags]] +Match the compiled regular expression @var{regexp} against @code{str}. +If the optional integer @var{start} argument is provided, begin matching +from that position in the string. Return a match structure describing +the results of the match, or @code{#f} if no match could be found. +@end deffn + +call-with-dynamic-root +@c snarfed from root.c:358 +@deffn primitive call-with-dynamic-root thunk handler +Evaluate @code{(thunk)} in a new dynamic context, returning its value. + +If an error occurs during evaluation, apply @var{handler} to the +arguments to the throw, just as @code{throw} would. If this happens, +@var{handler} is called outside the scope of the new root -- it is +called in the same dynamic context in which +@code{call-with-dynamic-root} was evaluated. + +If @var{thunk} captures a continuation, the continuation is rooted at +the call to @var{thunk}. In particular, the call to +@code{call-with-dynamic-root} is not captured. Therefore, +@code{call-with-dynamic-root} always returns at most one time. + +Before calling @var{thunk}, the dynamic-wind chain is un-wound back to +the root and a new chain started for @var{thunk}. Therefore, this call +may not do what you expect: + +@example +;; Almost certainly a bug: +(with-output-to-port + some-port + + (lambda () + (call-with-dynamic-root + (lambda () + (display 'fnord) + (newline)) + (lambda (errcode) errcode)))) +@end example + +The problem is, on what port will @samp{fnord} be displayed? You +might expect that because of the @code{with-output-to-port} that +it will be displayed on the port bound to @code{some-port}. But it +probably won't -- before evaluating the thunk, dynamic winds are +unwound, including those created by @code{with-output-to-port}. +So, the standard output port will have been re-set to its default value +before @code{display} is evaluated. + +(This function was added to Guile mostly to help calls to functions in C +libraries that can not tolerate non-local exits or calls that return +multiple times. If such functions call back to the interpreter, it should +be under a new dynamic root.) +@end deffn + +dynamic-root +@c snarfed from root.c:371 +@deffn primitive dynamic-root +Return an object representing the current dynamic root. + +These objects are only useful for comparison using @code{eq?}. +They are currently represented as numbers, but your code should +in no way depend on this. +@end deffn + +sigaction +@c snarfed from scmsigs.c:201 +@deffn primitive sigaction signum [handler [flags]] +Install or report the signal handler for a specified signal. + +@var{signum} is the signal number, which can be specified using the value +of variables such as @code{SIGINT}. + +If @var{action} is omitted, @code{sigaction} returns a pair: the +CAR is the current +signal hander, which will be either an integer with the value @code{SIG_DFL} +(default action) or @code{SIG_IGN} (ignore), or the Scheme procedure which +handles the signal, or @code{#f} if a non-Scheme procedure handles the +signal. The CDR contains the current @code{sigaction} flags for the handler. + +If @var{action} is provided, it is installed as the new handler for +@var{signum}. @var{action} can be a Scheme procedure taking one +argument, or the value of @code{SIG_DFL} (default action) or +@code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler +was installed before @code{sigaction} was first used. Flags can +optionally be specified for the new handler (@code{SA_RESTART} will +always be added if it's available and the system is using restartable +system calls.) The return value is a pair with information about the +old handler as described above. + +This interface does not provide access to the "signal blocking" +facility. Maybe this is not needed, since the thread support may +provide solutions to the problem of consistent access to data +structures. +@end deffn + +restore-signals +@c snarfed from scmsigs.c:360 +@deffn primitive restore-signals +Return all signal handlers to the values they had before any call to +@code{sigaction} was made. The return value is unspecified. +@end deffn + +alarm +@c snarfed from scmsigs.c:399 +@deffn primitive alarm i +Set a timer to raise a @code{SIGALRM} signal after the specified +number of seconds (an integer). It's advisable to install a signal +handler for +@code{SIGALRM} beforehand, since the default action is to terminate +the process. + +The return value indicates the time remaining for the previous alarm, +if any. The new value replaces the previous alarm. If there was +no previous alarm, the return value is zero. +@end deffn + +pause +@c snarfed from scmsigs.c:414 +@deffn primitive pause +Pause the current process (thread?) until a signal arrives whose +action is to either terminate the current process or invoke a +handler procedure. The return value is unspecified. +@end deffn + +sleep +@c snarfed from scmsigs.c:427 +@deffn primitive sleep i +Wait for the given number of seconds (an integer) or until a signal +arrives. The return value is zero if the time elapses or the number +of seconds remaining otherwise. +@end deffn + +usleep +@c snarfed from scmsigs.c:445 +@deffn primitive usleep i +Sleep for I microseconds. @code{usleep} is not available on +all platforms. +@end deffn + +raise +@c snarfed from scmsigs.c:475 +@deffn primitive raise sig +Sends a specified signal @var{sig} to the current process, where +@var{sig} is as described for the kill procedure. +@end deffn + +system +@c snarfed from simpos.c:76 +@deffn primitive system [cmd] +Executes @var{cmd} using the operating system's "command processor". +Under Unix this is usually the default shell @code{sh}. The value +returned is @var{cmd}'s exit status as returned by @code{waitpid}, which +can be interpreted using the functions above. + +If @code{system} is called without arguments, it returns a boolean +indicating whether the command processor is available. +@end deffn + +getenv +@c snarfed from simpos.c:104 +@deffn primitive getenv nam +Looks up the string @var{name} in the current environment. The return +value is @code{#f} unless a string of the form @code{NAME=VALUE} is +found, in which case the string @code{VALUE} is returned. +@end deffn + +primitive-exit +@c snarfed from simpos.c:120 +@deffn primitive primitive-exit [status] +Terminate the current process without unwinding the Scheme stack. +This is would typically be useful after a fork. The exit status +is @var{status} if supplied, otherwise zero. +@end deffn + +htons +@c snarfed from socket.c:89 +@deffn primitive htons in +Returns a new integer from @var{value} by converting from host to +network order. @var{value} must be within the range of a C unsigned +short integer. +@end deffn + +ntohs +@c snarfed from socket.c:106 +@deffn primitive ntohs in +Returns a new integer from @var{value} by converting from network to +host order. @var{value} must be within the range of a C unsigned short +integer. +@end deffn + +htonl +@c snarfed from socket.c:123 +@deffn primitive htonl in +Returns a new integer from @var{value} by converting from host to +network order. @var{value} must be within the range of a C unsigned +long integer. +@end deffn + +ntohl +@c snarfed from socket.c:135 +@deffn primitive ntohl in +Returns a new integer from @var{value} by converting from network to +host order. @var{value} must be within the range of a C unsigned +long integer. +@end deffn + +socket +@c snarfed from socket.c:158 +@deffn primitive socket family style proto +Returns a new socket port of the type specified by @var{family}, @var{style} +and @var{protocol}. All three parameters are integers. Typical values +for @var{family} are the values of @code{AF_UNIX} +and @code{AF_INET}. Typical values for @var{style} are +the values of @code{SOCK_STREAM}, @code{SOCK_DGRAM} and @code{SOCK_RAW}. + +@var{protocol} can be obtained from a protocol name using +@code{getprotobyname}. A value of +zero specifies the default protocol, which is usually right. + +A single socket port cannot by used for communication until +it has been connected to another socket. +@end deffn + +socketpair +@c snarfed from socket.c:180 +@deffn primitive socketpair family style proto +Returns a pair of connected (but unnamed) socket ports of the type specified +by @var{family}, @var{style} and @var{protocol}. +Many systems support only +socket pairs of the @code{AF_UNIX} family. Zero is likely to be +the only meaningful value for @var{protocol}. +@end deffn + +getsockopt +@c snarfed from socket.c:209 +@deffn primitive getsockopt sock level optname +Returns the value of a particular socket option for the socket +port @var{socket}. @var{level} is an integer code for type of option +being requested, e.g., @code{SOL_SOCKET} for socket-level options. +@var{optname} is an +integer code for the option required and should be specified using one of +the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. + +The returned value is typically an integer but @code{SO_LINGER} returns a +pair of integers. +@end deffn + +setsockopt +@c snarfed from socket.c:277 +@deffn primitive setsockopt sock level optname value +Sets the value of a particular socket option for the socket +port @var{socket}. @var{level} is an integer code for type of option +being set, e.g., @code{SOL_SOCKET} for socket-level options. +@var{optname} is an +integer code for the option to set and should be specified using one of +the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. +@var{value} is the value to which the option should be set. For +most options this must be an integer, but for @code{SO_LINGER} it must +be a pair. + +The return value is unspecified. +@end deffn + +shutdown +@c snarfed from socket.c:381 +@deffn primitive shutdown sock how +Sockets can be closed simply by using @code{close-port}. The +@code{shutdown} procedure allows reception or tranmission on a +connection to be shut down individually, according to the parameter +@var{how}: + +@table @asis +@item 0 +Stop receiving data for this socket. If further data arrives, reject it. +@item 1 +Stop trying to transmit data from this socket. Discard any +data waiting to be sent. Stop looking for acknowledgement of +data already sent; don't retransmit it if it is lost. +@item 2 +Stop both reception and transmission. +@end table + +The return value is unspecified. +@end deffn + +connect +@c snarfed from socket.c:474 +@deffn primitive connect sock fam address . args +Initiates a connection from @var{socket} to the address +specified by @var{address} and possibly @var{arg @dots{}}. The format +required for @var{address} +and @var{arg} @dots{} depends on the family of the socket. + +For a socket of family @code{AF_UNIX}, +only @code{address} is specified and must be a string with the +filename where the socket is to be created. + +For a socket of family @code{AF_INET}, +@code{address} must be an integer Internet host address and @var{arg} @dots{} +must be a single integer port number. + +The return value is unspecified. +@end deffn + +bind +@c snarfed from socket.c:528 +@deffn primitive bind sock fam address . args +Assigns an address to the socket port @var{socket}. +Generally this only needs to be done for server sockets, +so they know where to look for incoming connections. A socket +without an address will be assigned one automatically when it +starts communicating. + +The format of @var{address} and @var{ARG} @dots{} depends on the family +of the socket. + +For a socket of family @code{AF_UNIX}, only @var{address} +is specified and must +be a string with the filename where the socket is to be created. + +For a socket of family @code{AF_INET}, @var{address} must be an integer +Internet host address and @var{arg} @dots{} must be a single integer +port number. + +The values of the following variables can also be used for @var{address}: + +@defvar INADDR_ANY +Allow connections from any address. +@end defvar + +@defvar INADDR_LOOPBACK +The address of the local host using the loopback device. +@end defvar + +@defvar INADDR_BROADCAST +The broadcast address on the local network. +@end defvar + +@defvar INADDR_NONE +No address. +@end defvar + +The return value is unspecified. +@end deffn + +listen +@c snarfed from socket.c:561 +@deffn primitive listen sock backlog +This procedure enables @var{socket} to accept connection +requests. @var{backlog} is an integer specifying +the maximum length of the queue for pending connections. +If the queue fills, new clients will fail to connect until the +server calls @code{accept} to accept a connection from the queue. + +The return value is unspecified. +@end deffn + +accept +@c snarfed from socket.c:637 +@deffn primitive accept sock +Accepts a connection on a bound, listening socket @var{socket}. If there +are no pending connections in the queue, it waits until +one is available unless the non-blocking option has been set on the +socket. + +The return value is a +pair in which the CAR is a new socket port for the connection and +the CDR is an object with address information about the client which +initiated the connection. + +If the address is not available then the CDR will be an empty vector. + +@var{socket} does not become part of the +connection and will continue to accept new requests. +@end deffn + +getsockname +@c snarfed from socket.c:668 +@deffn primitive getsockname sock +Returns the address of @var{socket}, in the same form as the object +returned by @code{accept}. On many systems the address of a socket +in the @code{AF_FILE} namespace cannot be read. +@end deffn + +getpeername +@c snarfed from socket.c:695 +@deffn primitive getpeername sock +Returns the address of the socket that the socket @var{socket} is connected to, +in the same form as the object +returned by @code{accept}. On many systems the address of a socket +in the @code{AF_FILE} namespace cannot be read. +@end deffn + +recv! +@c snarfed from socket.c:730 +@deffn primitive recv! sock buf [flags] +Receives data from the socket port @var{socket}. @var{socket} must already +be bound to the address from which data is to be received. +@var{buf} is a string into which +the data will be written. The size of @var{buf} limits the amount of +data which can be received: in the case of packet +protocols, if a packet larger than this limit is encountered then some data +will be irrevocably lost. + +The optional @var{flags} argument is a value or +bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. + +The value returned is the number of bytes read from the socket. + +Note that the data is read directly from the socket file descriptor: +any unread buffered port data is ignored. +@end deffn + +send +@c snarfed from socket.c:759 +@deffn primitive send sock message [flags] +Transmits the string @var{message} on the socket port @var{socket}. +@var{socket} must already be bound to a destination address. The +value returned is the number of bytes transmitted -- it's possible for +this to be less than the length of @var{message} if the socket is +set to be non-blocking. The optional @var{flags} argument is a value or +bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. + +Note that the data is written directly to the socket file descriptor: +any unflushed buffered port data is ignored. +@end deffn + +recvfrom! +@c snarfed from socket.c:797 +@deffn primitive recvfrom! sock str [flags [start [end]]] +Returns data from the socket port @var{socket} and also information about +where the data was received from. @var{socket} must already +be bound to the address from which data is to be received. +@code{str}, is a string into which +the data will be written. The size of @var{str} limits the amount of +data which can be received: in the case of packet +protocols, if a packet larger than this limit is encountered then some data +will be irrevocably lost. + +The optional @var{flags} argument is a value or +bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. + +The value returned is a pair: the CAR is the number of bytes read from +the socket and the CDR an address object in the same form as returned by +@code{accept}. + +The @var{start} and @var{end} arguments specify a substring of @var{str} +to which the data should be written. + +Note that the data is read directly from the socket file descriptor: +any unread buffered port data is ignored. +@end deffn + +sendto +@c snarfed from socket.c:848 +@deffn primitive sendto sock message fam address . args_and_flags +Transmits the string @var{message} on the socket port @var{socket}. The +destination address is specified using the @var{family}, @var{address} and +@var{arg} arguments, in a similar way to the @code{connect} +procedure. The +value returned is the number of bytes transmitted -- it's possible for +this to be less than the length of @var{message} if the socket is +set to be non-blocking. The optional @var{flags} argument is a value or +bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. + +Note that the data is written directly to the socket file descriptor: +any unflushed buffered port data is ignored. +@end deffn + +restricted-vector-sort! +@c snarfed from sort.c:425 +@deffn primitive restricted-vector-sort! vec less startpos endpos +Sort the vector @var{vec}, using @var{less} for comparing +the vector elements. @var{startpos} and @var{endpos} delimit +the range of the vector which gets sorted. The return value +is not specified. +@end deffn + +sorted? +@c snarfed from sort.c:456 +@deffn primitive sorted? items less +Return @code{#t} iff @var{items} is a list or a vector such that +for all 1 <= i <= m, the predicate @var{less} returns true when +applied to all elements i - 1 and i +@end deffn + +merge +@c snarfed from sort.c:528 +@deffn primitive merge alist blist less +Takes two lists @var{alist} and @var{blist} such that +@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and +returns a new list in which the elements of @var{alist} and +@var{blist} have been stably interleaved so that +@code{(sorted? (merge alist blist less?) less?)}. +Note: this does _not_ accept vectors. +@end deffn + +merge! +@c snarfed from sort.c:641 +@deffn primitive merge! alist blist less +Takes two lists @var{alist} and @var{blist} such that +@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and +returns a new list in which the elements of @var{alist} and +@var{blist} have been stably interleaved so that + @code{(sorted? (merge alist blist less?) less?)}. +This is the destructive variant of @code{merge} +Note: this does _not_ accept vectors. +@end deffn + +sort! +@c snarfed from sort.c:717 +@deffn primitive sort! items less +Sort the sequence @var{items}, which may be a list or a +vector. @var{less} is used for comparing the sequence +elements. The sorting is destructive, that means that the +input sequence is modified to produce the sorted result. +This is not a stable sort. +@end deffn + +sort +@c snarfed from sort.c:751 +@deffn primitive sort items less +Sort the sequence @var{items}, which may be a list or a +vector. @var{less} is used for comparing the sequence +elements. This is not a stable sort. +@end deffn + +stable-sort! +@c snarfed from sort.c:847 +@deffn primitive stable-sort! items less +Sort the sequence @var{items}, which may be a list or a +vector. @var{less} is used for comparing the sequence elements. +The sorting is destructive, that means that the input sequence +is modified to produce the sorted result. +This is a stable sort. +@end deffn + +stable-sort +@c snarfed from sort.c:887 +@deffn primitive stable-sort items less +Sort the sequence @var{items}, which may be a list or a +vector. @var{less} is used for comparing the sequence elements. +This is a stable sort. +@end deffn + +sort-list! +@c snarfed from sort.c:933 +@deffn primitive sort-list! items less +Sort the list @var{items}, using @var{less} for comparing the +list elements. The sorting is destructive, that means that the +input list is modified to produce the sorted result. +This is a stable sort. +@end deffn + +sort-list +@c snarfed from sort.c:947 +@deffn primitive sort-list items less +Sort the list @var{items}, using @var{less} for comparing the +list elements. This is a stable sort. +@end deffn + +source-properties +@c snarfed from srcprop.c:171 +@deffn primitive source-properties obj +Return the source property association list of @var{obj}. +@end deffn + +set-source-properties! +@c snarfed from srcprop.c:194 +@deffn primitive set-source-properties! obj plist +Install the association list @var{plist} as the source property +list for @var{obj}. +@end deffn + +source-property +@c snarfed from srcprop.c:214 +@deffn primitive source-property obj key +Return the source property specified by @var{key} from +@var{obj}'s source property list. +@end deffn + +set-source-property! +@c snarfed from srcprop.c:247 +@deffn primitive set-source-property! obj key datum +Set the source property of object @var{obj}, which is specified by +@var{key} to @var{datum}. Normally, the key will be a symbol. +@end deffn + +stack? +@c snarfed from stacks.c:407 +@deffn primitive stack? obj +Return @code{#t} if @var{obj} is a calling stack. +@end deffn + +make-stack +@c snarfed from stacks.c:421 +@deffn primitive make-stack obj . args +Create a new stack. If @var{obj} is @code{#t}, the current +evaluation stack is used for creating the stack frames, +otherwise the frames are taken from @var{obj} (which must be +either a debug object or a continuation). +@var{args} must be a list if integers and specifies how the +resulting stack will be narrowed. +@end deffn + +stack-id +@c snarfed from stacks.c:512 +@deffn primitive stack-id stack +Return the identifier given to @var{stack} by @code{start-stack}. +@end deffn + +stack-ref +@c snarfed from stacks.c:548 +@deffn primitive stack-ref stack i +Return the @var{i}'th frame from @var{stack}. +@end deffn + +stack-length +@c snarfed from stacks.c:562 +@deffn primitive stack-length stack +Return the length of @var{stack}. +@end deffn + +frame? +@c snarfed from stacks.c:575 +@deffn primitive frame? obj +Return @code{#t} if @var{obj} is a stack frame. +@end deffn + +last-stack-frame +@c snarfed from stacks.c:586 +@deffn primitive last-stack-frame obj +Return a stack which consists of a single frame, which is the +last stack frame for @var{obj}. @var{obj} must be either a +debug object or a continuation. +@end deffn + +frame-number +@c snarfed from stacks.c:627 +@deffn primitive frame-number frame +Return the frame number of @var{frame}. +@end deffn + +frame-source +@c snarfed from stacks.c:637 +@deffn primitive frame-source frame +Return the source of @var{frame}. +@end deffn + +frame-procedure +@c snarfed from stacks.c:648 +@deffn primitive frame-procedure frame +Return the procedure for @var{frame}, or @code{#f} if no +procedure is associated with @var{frame}. +@end deffn + +frame-arguments +@c snarfed from stacks.c:660 +@deffn primitive frame-arguments frame +Return the arguments of @var{frame}. +@end deffn + +frame-previous +@c snarfed from stacks.c:671 +@deffn primitive frame-previous frame +Return the previous frame of @var{frame}, or @code{#f} if +@var{frame} is the first frame in its stack. +@end deffn + +frame-next +@c snarfed from stacks.c:687 +@deffn primitive frame-next frame +Return the next frame of @var{frame}, or @code{#f} if +@var{frame} is the last frame in its stack. +@end deffn + +frame-real? +@c snarfed from stacks.c:702 +@deffn primitive frame-real? frame +Return @code{#t} if @var{frame} is a real frame. +@end deffn + +frame-procedure? +@c snarfed from stacks.c:712 +@deffn primitive frame-procedure? frame +Return @code{#t} if a procedure is associated with @var{frame}. +@end deffn + +frame-evaluating-args? +@c snarfed from stacks.c:722 +@deffn primitive frame-evaluating-args? frame +Return @code{#t} if @var{frame} contains evaluated arguments. +@end deffn + +frame-overflow? +@c snarfed from stacks.c:732 +@deffn primitive frame-overflow? frame +Return @code{#t} if @var{frame} is an overflow frame. +@end deffn + +get-internal-real-time +@c snarfed from stime.c:141 +@deffn primitive get-internal-real-time +Returns the number of time units since the interpreter was started. +@end deffn + +times +@c snarfed from stime.c:183 +@deffn primitive times +Returns an object with information about real and processor time. +The following procedures accept such an object as an argument and +return a selected component: + +@table @code +@item tms:clock +The current real time, expressed as time units relative to an +arbitrary base. +@item tms:utime +The CPU time units used by the calling process. +@item tms:stime +The CPU time units used by the system on behalf of the calling process. +@item tms:cutime +The CPU time units used by terminated child processes of the calling +process, whose status has been collected (e.g., using @code{waitpid}). +@item tms:cstime +Similarly, the CPU times units used by the system on behalf of +terminated child processes. +@end table +@end deffn + +get-internal-run-time +@c snarfed from stime.c:214 +@deffn primitive get-internal-run-time +Returns the number of time units of processor time used by the interpreter. +Both "system" and "user" time are included but subprocesses are not. +@end deffn + +current-time +@c snarfed from stime.c:224 +@deffn primitive current-time +Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding +leap seconds. +@end deffn + +gettimeofday +@c snarfed from stime.c:241 +@deffn primitive gettimeofday +Returns a pair containing the number of seconds and microseconds since +1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true +microsecond resolution is available depends on the operating system. +@end deffn + +localtime +@c snarfed from stime.c:341 +@deffn primitive localtime time [zone] +Returns an object representing the broken down components of @var{time}, +an integer like the one returned by @code{current-time}. The time zone +for the calculation is optionally specified by @var{zone} (a string), +otherwise the @code{TZ} environment variable or the system default is +used. +@end deffn + +gmtime +@c snarfed from stime.c:413 +@deffn primitive gmtime time +Returns an object representing the broken down components of @var{time}, +an integer like the one returned by @code{current-time}. The values +are calculated for UTC. +@end deffn + +mktime +@c snarfed from stime.c:475 +@deffn primitive mktime sbd_time [zone] +@var{bd-time} is an object representing broken down time and @code{zone} +is an optional time zone specifier (otherwise the TZ environment variable +or the system default is used). + +Returns a pair: the car is a corresponding +integer time value like that returned +by @code{current-time}; the cdr is a broken down time object, similar to +as @var{bd-time} but with normalized values. +@end deffn + +tzset +@c snarfed from stime.c:548 +@deffn primitive tzset +Initialize the timezone from the TZ environment variable +or the system default. It's not usually necessary to call this procedure +since it's done automatically by other procedures that depend on the +timezone. +@end deffn + +strftime +@c snarfed from stime.c:565 +@deffn primitive strftime format stime +Formats a time specification @var{time} using @var{template}. @var{time} +is an object with time components in the form returned by @code{localtime} +or @code{gmtime}. @var{template} is a string which can include formatting +specifications introduced by a @code{%} character. The formatting of +month and day names is dependent on the current locale. The value returned +is the formatted string. +@xref{Formatting Date and Time, , , libc, The GNU C Library Reference Manual}.) +@end deffn + +strptime +@c snarfed from stime.c:663 +@deffn primitive strptime format string +Performs the reverse action to @code{strftime}, parsing +@var{string} according to the specification supplied in +@var{template}. The interpretation of month and day names is +dependent on the current locale. The value returned is a pair. +The car has an object with time components +in the form returned by @code{localtime} or @code{gmtime}, +but the time zone components +are not usefully set. +The cdr reports the number of characters from @var{string} +which were used for the conversion. +@end deffn + +string? +@c snarfed from strings.c:62 +@deffn primitive string? obj +Returns @code{#t} iff @var{obj} is a string, else returns +@code{#f}. +@end deffn + +read-only-string? +@c snarfed from strings.c:85 +@deffn primitive read-only-string? obj +Return true if @var{obj} can be read as a string, + +This illustrates the difference between @code{string?} and +@code{read-only-string?}: + +@example +(string? "a string") @result{} #t +(string? 'a-symbol) @result{} #f + +(read-only-string? "a string") @result{} #t +(read-only-string? 'a-symbol) @result{} #t +@end example +@end deffn + +list->string +@c snarfed from strings.c:94 +@deffn primitive list->string +scm_string +@end deffn + +string +@c snarfed from strings.c:100 +@deffn primitive string . chrs +@deffnx primitive list->string chrs +Returns a newly allocated string composed of the arguments, +@var{chrs}. +@end deffn + +make-string +@c snarfed from strings.c:253 +@deffn primitive make-string k [chr] +Return a newly allocated string of +length @var{k}. If @var{chr} is given, then all elements of +the string are initialized to @var{chr}, otherwise the contents +of the @var{string} are unspecified. +@end deffn + +string-length +@c snarfed from strings.c:286 +@deffn primitive string-length string +Return the number of characters in @var{string}. +@end deffn + +string-ref +@c snarfed from strings.c:297 +@deffn primitive string-ref str k +Return character @var{k} of @var{str} using zero-origin +indexing. @var{k} must be a valid index of @var{str}. +@end deffn + +string-set! +@c snarfed from strings.c:314 +@deffn primitive string-set! str k chr +Store @var{chr} in element @var{k} of @var{str} and return +an unspecified value. @var{k} must be a valid index of +@var{str}. +@end deffn + +substring +@c snarfed from strings.c:337 +@deffn primitive substring str start [end] +Return a newly allocated string formed from the characters +of @var{str} beginning with index @var{start} (inclusive) and +ending with index @var{end} (exclusive). +@var{str} must be a string, @var{start} and @var{end} must be +exact integers satisfying: + +0 <= @var{start} <= @var{end} <= (string-length @var{str}). +@end deffn + +string-append +@c snarfed from strings.c:360 +@deffn primitive string-append . args +Return a newly allocated string whose characters form the +concatenation of the given strings, @var{args}. +@end deffn + +make-shared-substring +@c snarfed from strings.c:400 +@deffn primitive make-shared-substring str [frm [to]] +Return a shared substring of @var{str}. The semantics are the same as +for the @code{substring} function: the shared substring returned +includes all of the text from @var{str} between indexes @var{start} +(inclusive) and @var{end} (exclusive). If @var{end} is omitted, it +defaults to the end of @var{str}. The shared substring returned by +@code{make-shared-substring} occupies the same storage space as +@var{str}. +@end deffn + +string-index +@c snarfed from strop.c:120 +@deffn primitive string-index str chr [frm [to]] +Return the index of the first occurrence of @var{chr} in +@var{str}. The optional integer arguments @var{frm} and +@var{to} limit the search to a portion of the string. This +procedure essentially implements the @code{index} or +@code{strchr} functions from the C library.\n (qdocs:) Returns +the index of @var{char} in @var{str}, or @code{#f} if the +@var{char} isn't in @var{str}. If @var{frm} is given and not +@code{#f}, it is used as the starting index; if @var{to} is +given and not @code{#f}, it is used as the ending index +(exclusive). + +@example +(string-index "weiner" #\\e) +@result{} 1 + +(string-index "weiner" #\\e 2) +@result{} 4 + +(string-index "weiner" #\\e 2 4) +@result{} #f +@end example +@end deffn + +string-rindex +@c snarfed from strop.c:151 +@deffn primitive string-rindex str chr [frm [to]] +Like @code{string-index}, but search from the right of the string rather +than from the left. This procedure essentially implements the +@code{rindex} or @code{strrchr} functions from the C library. + +(qdocs:) The same as @code{string-index}, except it gives the rightmost occurance +of @var{char} in the range [@var{frm}, @var{to}-1], which defaults to +the entire string. + +@example +(string-rindex "weiner" #\\e) +@result{} 4 + +(string-rindex "weiner" #\\e 2 4) +@result{} #f + +(string-rindex "weiner" #\\e 2 5) +@result{} 4 +@end example +@end deffn + +substring-move-left! +@c snarfed from strop.c:168 +@deffn primitive substring-move-left! +scm_substring_move_x +@end deffn + +substring-move-right! +@c snarfed from strop.c:169 +@deffn primitive substring-move-right! +scm_substring_move_x +@end deffn + +substring-move! +@c snarfed from strop.c:243 +@deffn primitive substring-move! str1 start1 end1 str2 start2 +@deffnx primitive substring-move-left! str1 start1 end1 str2 start2 +@deffnx primitive substring-move-right! str1 start1 end1 str2 start2 +Copy the substring of @var{str1} bounded by @var{start1} and @var{end1} +into @var{str2} beginning at position @var{end2}. +@code{substring-move-right!} begins copying from the rightmost character +and moves left, and @code{substring-move-left!} copies from the leftmost +character moving right. + +It is useful to have two functions that copy in different directions so +that substrings can be copied back and forth within a single string. If +you wish to copy text from the left-hand side of a string to the +right-hand side of the same string, and the source and destination +overlap, you must be careful to copy the rightmost characters of the +text first, to avoid clobbering your data. Hence, when @var{str1} and +@var{str2} are the same string, you should use +@code{substring-move-right!} when moving text from left to right, and +@code{substring-move-left!} otherwise. If @code{str1} and @samp{str2} +are different strings, it does not matter which function you use. +@end deffn + +substring-fill! +@c snarfed from strop.c:279 +@deffn primitive substring-fill! str start end fill +Change every character in @var{str} between @var{start} and @var{end} to +@var{fill-char}. + +(qdocs:) Destructively fills @var{str}, from @var{start} to @var{end}, with @var{fill}. + +@example +(define y "abcdefg") +(substring-fill! y 1 3 #\\r) +y +@result{} "arrdefg" +@end example +@end deffn + +string-null? +@c snarfed from strop.c:306 +@deffn primitive string-null? str +Return @code{#t} if @var{str}'s length is nonzero, and @code{#f} +otherwise. + +(qdocs:) Returns @code{#t} if @var{str} is empty, else returns @code{#f}. + +@example +(string-null? "") +@result{} #t + +(string-null? y) +@result{} #f +@end example +@end deffn + +string->list +@c snarfed from strop.c:322 +@deffn primitive string->list str +@samp{String->list} returns a newly allocated list of the +characters that make up the given string. @samp{List->string} +returns a newly allocated string formed from the characters in the list +@var{list}, which must be a list of characters. @samp{String->list} +and @samp{list->string} are +inverses so far as @samp{equal?} is concerned. (r5rs) +@end deffn + +string-copy +@c snarfed from strop.c:347 +@deffn primitive string-copy str +Returns a newly allocated copy of the given @var{string}. (r5rs) +@end deffn + +string-fill! +@c snarfed from strop.c:360 +@deffn primitive string-fill! str chr +Stores @var{char} in every element of the given @var{string} and returns an +unspecified value. (r5rs) +@end deffn + +string-upcase! +@c snarfed from strop.c:396 +@deffn primitive string-upcase! str +Destructively upcase every character in @code{str}. + +(qdocs:) Converts each element in @var{str} to upper case. + +@example +(string-upcase! y) +@result{} "ARRDEFG" + +y +@result{} "ARRDEFG" +@end example +@end deffn + +string-upcase +@c snarfed from strop.c:408 +@deffn primitive string-upcase str +Upcase every character in @code{str}. +@end deffn + +string-downcase! +@c snarfed from strop.c:443 +@deffn primitive string-downcase! str +Destructively downcase every character in @code{str}. + +(qdocs:) Converts each element in @var{str} to lower case. + +@example +y +@result{} "ARRDEFG" + +(string-downcase! y) +@result{} "arrdefg" + +y +@result{} "arrdefg" +@end example +@end deffn + +string-downcase +@c snarfed from strop.c:455 +@deffn primitive string-downcase str +Downcase every character in @code{str}. +@end deffn + +string-capitalize! +@c snarfed from strop.c:492 +@deffn primitive string-capitalize! str +Destructively capitalize every character in @code{str}. +@end deffn + +string-capitalize +@c snarfed from strop.c:504 +@deffn primitive string-capitalize str +Capitalize every character in @code{str}. +@end deffn + +string-ci->symbol +@c snarfed from strop.c:516 +@deffn primitive string-ci->symbol str +Return the symbol whose name is @var{str}, downcased in necessary(???). +@end deffn + +string=? +@c snarfed from strorder.c:64 +@deffn primitive string=? s1 s2 +Lexicographic equality predicate; +Returns @code{#t} if the two strings are the same length and +contain the same characters in the same positions, otherwise +returns @code{#f}. (r5rs) + +The procedure @code{string-ci=?} treats upper and lower case +letters as though they were the same character, but +@code{string=?} treats upper and lower case as distinct +characters. +@end deffn + +string-ci=? +@c snarfed from strorder.c:99 +@deffn primitive string-ci=? s1 s2 +Case-insensitive string equality predicate; returns @code{#t} +if the two strings are the same length and their component +characters match (ignoring case) at each position; otherwise +returns @code{#f}. (r5rs) +@end deffn + +string<? +@c snarfed from strorder.c:156 +@deffn primitive string<? s1 s2 +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically less than @var{s2}. (r5rs) +@end deffn + +string<=? +@c snarfed from strorder.c:171 +@deffn primitive string<=? s1 s2 +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically less than or equal to @var{s2}. +(r5rs) +@end deffn + +string>? +@c snarfed from strorder.c:185 +@deffn primitive string>? s1 s2 +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically greater than @var{s2}. (r5rs) +@end deffn + +string>=? +@c snarfed from strorder.c:200 +@deffn primitive string>=? s1 s2 +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically greater than or equal to +@var{s2}. (r5rs) +@end deffn + +string-ci<? +@c snarfed from strorder.c:239 +@deffn primitive string-ci<? s1 s2 +Case insensitive lexicographic ordering predicate; +returns @code{#t} if @var{s1} is lexicographically less than +@var{s2} regardless of case. (r5rs) +@end deffn + +string-ci<=? +@c snarfed from strorder.c:254 +@deffn primitive string-ci<=? s1 s2 +Case insensitive lexicographic ordering predicate; +returns @code{#t} if @var{s1} is lexicographically less than +or equal to @var{s2} regardless of case. (r5rs) +@end deffn + +string-ci>? +@c snarfed from strorder.c:269 +@deffn primitive string-ci>? s1 s2 +Case insensitive lexicographic ordering predicate; +returns @code{#t} if @var{s1} is lexicographically greater +than @var{s2} regardless of case. (r5rs) +@end deffn + +string-ci>=? +@c snarfed from strorder.c:284 +@deffn primitive string-ci>=? s1 s2 +Case insensitive lexicographic ordering predicate; +returns @code{#t} if @var{s1} is lexicographically greater +than or equal to @var{s2} regardless of case. (r5rs) +@end deffn + +object->string +@c snarfed from strports.c:318 +@deffn primitive object->string obj [printer] +Return a Scheme string obtained by printing @var{obj}. +Printing function can be specified by the optional second +argument @var{printer} (default: @code{write}). +@end deffn + +call-with-output-string +@c snarfed from strports.c:352 +@deffn primitive call-with-output-string proc +Calls the one-argument procedure @var{proc} with a newly created output +port. When the function returns, the string composed of the characters +written into the port is returned. +@end deffn + +call-with-input-string +@c snarfed from strports.c:371 +@deffn primitive call-with-input-string str proc +Calls the one-argument procedure @var{proc} with a newly created input +port from which @var{string}'s contents may be read. The value yielded +by the @var{proc} is returned. +@end deffn + +open-input-string +@c snarfed from strports.c:384 +@deffn primitive open-input-string str +Takes a string and returns an input port that delivers +characters from the string. The port can be closed by +@code{close-input-port}, though its storage will be reclaimed +by the garbage collector if it becomes inaccessible. +@end deffn + +open-output-string +@c snarfed from strports.c:398 +@deffn primitive open-output-string +Returns an output port that will accumulate characters for +retrieval by @code{get-output-string}. The port can be closed +by the procedure @code{close-output-port}, though its storage +will be reclaimed by the garbage collector if it becomes +inaccessible. +@end deffn + +get-output-string +@c snarfed from strports.c:415 +@deffn primitive get-output-string port +Given an output port created by @code{open-output-string}, +returns a string consisting of the characters that have been +output to the port so far. +@end deffn + +eval-string +@c snarfed from strports.c:456 +@deffn primitive eval-string string +Evaluate @var{string} as the text representation of a Scheme +form or forms, and return whatever value they produce. +Evaluation takes place in the environment returned by the +procedure @code{interaction-environment}. +@end deffn + +make-struct-layout +@c snarfed from struct.c:79 +@deffn primitive make-struct-layout fields +Return a new structure layout object. + +@var{fields} must be a string made up of pairs of characters +strung together. The first character of each pair describes a field +type, the second a field protection. Allowed types are 'p' for +GC-protected Scheme data, 'u' for unprotected binary data, and 's' for +a field that points to the structure itself. Allowed protections +are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque +fields. The last field protection specification may be capitalized to +indicate that the field is a tail-array. +@end deffn + +struct? +@c snarfed from struct.c:246 +@deffn primitive struct? x +Return @code{#t} iff @var{obj} is a structure object, else +@code{#f}. +@end deffn + +struct-vtable? +@c snarfed from struct.c:255 +@deffn primitive struct-vtable? x +Return @code{#t} iff obj is a vtable structure. +@end deffn + +make-struct +@c snarfed from struct.c:437 +@deffn primitive make-struct vtable tail_array_size . init +Create a new structure. + +@var{type} must be a vtable structure (@pxref{Vtables}). + +@var{tail-elts} must be a non-negative integer. If the layout +specification indicated by @var{type} includes a tail-array, +this is the number of elements allocated to that array. + +The @var{init1}, @dots{} are optional arguments describing how +successive fields of the structure should be initialized. Only fields +with protection 'r' or 'w' can be initialized, except for fields of +type 's', which are automatically initialized to point to the new +structure itself; fields with protection 'o' can not be initialized by +Scheme programs. + +If fewer optional arguments than initializable fields are supplied, +fields of type 'p' get default value #f while fields of type 'u' are +initialized to 0. + +Structs are currently the basic representation for record-like data +structures in Guile. The plan is to eventually replace them with a +new representation which will at the same time be easier to use and +more powerful. + +For more information, see the documentation for @code{make-vtable-vtable}. +@end deffn + +make-vtable-vtable +@c snarfed from struct.c:523 +@deffn primitive make-vtable-vtable user_fields tail_array_size . init +Return a new, self-describing vtable structure. + +@var{user-fields} is a string describing user defined fields of the +vtable beginning at index @code{vtable-offset-user} +(see @code{make-struct-layout}). + +@var{tail-size} specifies the size of the tail-array (if any) of +this vtable. + +@var{init1}, @dots{} are the optional initializers for the fields of +the vtable. + +Vtables have one initializable system field---the struct printer. +This field comes before the user fields in the initializers passed +to @code{make-vtable-vtable} and @code{make-struct}, and thus works as +a third optional argument to @code{make-vtable-vtable} and a fourth to +@code{make-struct} when creating vtables: + +If the value is a procedure, it will be called instead of the standard +printer whenever a struct described by this vtable is printed. +The procedure will be called with arguments STRUCT and PORT. + +The structure of a struct is described by a vtable, so the vtable is +in essence the type of the struct. The vtable is itself a struct with +a vtable. This could go on forever if it weren't for the +vtable-vtables which are self-describing vtables, and thus terminate +the chain. + +There are several potential ways of using structs, but the standard +one is to use three kinds of structs, together building up a type +sub-system: one vtable-vtable working as the root and one or several +"types", each with a set of "instances". (The vtable-vtable should be +compared to the class <class> which is the class of itself.) + +@example +(define ball-root (make-vtable-vtable "pr" 0)) + +(define (make-ball-type ball-color) + (make-struct ball-root 0 + (make-struct-layout "pw") + (lambda (ball port) + (format port "#<a ~A ball owned by ~A>" + (color ball) + (owner ball))) + ball-color)) +(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user)) +(define (owner ball) (struct-ref ball 0)) + +(define red (make-ball-type 'red)) +(define green (make-ball-type 'green)) + +(define (make-ball type owner) (make-struct type 0 owner)) + +(define ball (make-ball green 'Nisse)) +ball @result{} #<a green ball owned by Nisse> +@end example +@end deffn + +struct-ref +@c snarfed from struct.c:565 +@deffn primitive struct-ref handle pos +@deffnx primitive struct-set! struct n value +Access (or modify) the @var{n}th field of @var{struct}. + +If the field is of type 'p', then it can be set to an arbitrary value. + +If the field is of type 'u', then it can only be set to a non-negative +integer value small enough to fit in one machine word. +@end deffn + +struct-set! +@c snarfed from struct.c:643 +@deffn primitive struct-set! handle pos val +Set the slot of the structure @var{handle} with index @var{pos} +to @var{val}. Signal an error if the slot can not be written +to. +@end deffn + +struct-vtable +@c snarfed from struct.c:713 +@deffn primitive struct-vtable handle +Return the vtable structure that describes the type of @var{struct}. +@end deffn + +struct-vtable-tag +@c snarfed from struct.c:724 +@deffn primitive struct-vtable-tag handle +Return the vtable tag of the structure @var{handle}. +@end deffn + +struct-vtable-name +@c snarfed from struct.c:763 +@deffn primitive struct-vtable-name vtable +Return the name of the vtable @var{vtable}. +@end deffn + +set-struct-vtable-name! +@c snarfed from struct.c:773 +@deffn primitive set-struct-vtable-name! vtable name +Set the name of the vtable @var{vtable} to @var{name}. +@end deffn + +symbol? +@c snarfed from symbols.c:422 +@deffn primitive symbol? obj +Returns @code{#t} if @var{obj} is a symbol, otherwise returns +@code{#f}. (r5rs) +@end deffn + +symbol->string +@c snarfed from symbols.c:451 +@deffn primitive symbol->string s +Returns the name of @var{symbol} as a string. If the symbol +was part of an object returned as the value of a literal +expression (section @pxref{Literal expressions,,,r4rs, The +Revised^4 Report on Scheme}) or by a call to the @code{read} +procedure, and its name contains alphabetic characters, then +the string returned will contain characters in the +implementation's preferred standard case---some implementations +will prefer upper case, others lower case. If the symbol was +returned by @code{string->symbol}, the case of characters in +the string returned will be the same as the case in the string +that was passed to @code{string->symbol}. It is an error to +apply mutation procedures like @code{string-set!} to strings +returned by this procedure. (r5rs) + +The following examples assume that the implementation's +standard case is lower case: + +@lisp +(symbol->string 'flying-fish) @result{} "flying-fish" +(symbol->string 'Martin) @result{} "martin" +(symbol->string + (string->symbol "Malvina")) @result{} "Malvina" +@end lisp +@end deffn + +string->symbol +@c snarfed from symbols.c:478 +@deffn primitive string->symbol s +Returns the symbol whose name is @var{string}. This procedure +can create symbols with names containing special characters or +letters in the non-standard case, but it is usually a bad idea +to create such because in some implementations of Scheme they +cannot be read as themselves. See @code{symbol->string}. + +The following examples assume that the implementation's +standard case is lower case: + +@lisp +(eq? 'mISSISSIppi 'mississippi) @result{} #t +(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"} +(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f +(eq? 'JollyWog + (string->symbol (symbol->string 'JollyWog))) @result{} #t +(string=? "K. Harper, M.D." + (symbol->string + (string->symbol "K. Harper, M.D."))) @result{}#t +@end lisp +@end deffn + +string->obarray-symbol +@c snarfed from symbols.c:499 +@deffn primitive string->obarray-symbol o s [softp] +Intern a new symbol in @var{obarray}, a symbol table, with name +@var{string}. + +If @var{obarray} is @code{#f}, use the default system symbol table. If +@var{obarray} is @code{#t}, the symbol should not be interned in any +symbol table; merely return the pair (@var{symbol} +. @var{#<undefined>}). + +The @var{soft?} argument determines whether new symbol table entries +should be created when the specified symbol is not already present in +@var{obarray}. If @var{soft?} is specified and is a true value, then +new entries should not be added for symbols not already present in the +table; instead, simply return @code{#f}. +@end deffn + +intern-symbol +@c snarfed from symbols.c:531 +@deffn primitive intern-symbol o s +Add a new symbol to @var{obarray} with name @var{string}, bound to an +unspecified initial value. The symbol table is not modified if a symbol +with this name is already present. +@end deffn + +unintern-symbol +@c snarfed from symbols.c:568 +@deffn primitive unintern-symbol o s +Remove the symbol with name @var{string} from @var{obarray}. This +function returns @code{#t} if the symbol was present and @code{#f} +otherwise. +@end deffn + +symbol-binding +@c snarfed from symbols.c:609 +@deffn primitive symbol-binding o s +Look up in @var{obarray} the symbol whose name is @var{string}, and +return the value to which it is bound. If @var{obarray} is @code{#f}, +use the global symbol table. If @var{string} is not interned in +@var{obarray}, an error is signalled. +@end deffn + +symbol-interned? +@c snarfed from symbols.c:626 +@deffn primitive symbol-interned? o s +Return @code{#t} if @var{obarray} contains a symbol with name +@var{string}, and @code{#f} otherwise. +@end deffn + +symbol-bound? +@c snarfed from symbols.c:649 +@deffn primitive symbol-bound? o s +Return @code{#t} if @var{obarray} contains a symbol with name +@var{string} bound to a defined value. This differs from +@var{symbol-interned?} in that the mere mention of a symbol +usually causes it to be interned; @code{symbol-bound?} +determines whether a symbol has been given any meaningful +value. +@end deffn + +symbol-set! +@c snarfed from symbols.c:667 +@deffn primitive symbol-set! o s v +Find the symbol in @var{obarray} whose name is @var{string}, and rebind +it to @var{value}. An error is signalled if @var{string} is not present +in @var{obarray}. +@end deffn + +symbol-fref +@c snarfed from symbols.c:684 +@deffn primitive symbol-fref s +Return the contents of @var{symbol}'s @dfn{function slot}. +@end deffn + +symbol-pref +@c snarfed from symbols.c:695 +@deffn primitive symbol-pref s +Return the @dfn{property list} currently associated with @var{symbol}. +@end deffn + +symbol-fset! +@c snarfed from symbols.c:706 +@deffn primitive symbol-fset! s val +Change the binding of @var{symbol}'s function slot. +@end deffn + +symbol-pset! +@c snarfed from symbols.c:718 +@deffn primitive symbol-pset! s val +Change the binding of @var{symbol}'s property slot. +@end deffn + +symbol-hash +@c snarfed from symbols.c:732 +@deffn primitive symbol-hash symbol +Return a hash value for @var{symbol}. +@end deffn + +builtin-bindings +@c snarfed from symbols.c:769 +@deffn primitive builtin-bindings +Create and return a copy of the global symbol table, removing all +unbound symbols. +@end deffn + +gensym +@c snarfed from symbols.c:790 +@deffn primitive gensym [prefix] +Create a new symbol with a name constructed from a prefix and +a counter value. The string @var{prefix} can be specified as +an optional argument. Default prefix is @code{g}. The counter +is increased by 1 at each call. There is no provision for +resetting the counter. +@end deffn + +gentemp +@c snarfed from symbols.c:829 +@deffn primitive gentemp [prefix [obarray]] +Create a new symbol with a name unique in an obarray. +The name is constructed from an optional string @var{prefix} +and a counter value. The default prefix is @code{t}. The +@var{obarray} is specified as a second optional argument. +Default is the system obarray where all normal symbols are +interned. The counter is increased by 1 at each +call. There is no provision for resetting the counter. +@end deffn + +tag +@c snarfed from tag.c:98 +@deffn primitive tag x +Return an integer corresponding to the type of X. Deprecated. +@end deffn + +catch +@c snarfed from throw.c:529 +@deffn primitive catch tag thunk handler +Invoke @var{thunk} in the dynamic context of @var{handler} for +exceptions matching @var{key}. If thunk throws to the symbol @var{key}, +then @var{handler} is invoked this way: + +@example +(handler key args ...) +@end example + +@var{key} is a symbol or #t. + +@var{thunk} takes no arguments. If @var{thunk} returns normally, that +is the return value of @code{catch}. + +Handler is invoked outside the scope of its own @code{catch}. If +@var{handler} again throws to the same key, a new handler from further +up the call chain is invoked. + +If the key is @code{#t}, then a throw to @emph{any} symbol will match +this call to @code{catch}. +@end deffn + +lazy-catch +@c snarfed from throw.c:556 +@deffn primitive lazy-catch tag thunk handler +This behaves exactly like @code{catch}, except that it does +not unwind the stack (this is the major difference), and if +handler returns, its value is returned from the throw. +@end deffn + +throw +@c snarfed from throw.c:589 +@deffn primitive throw key . args +Invoke the catch form matching @var{key}, passing @var{args} to the +@var{handler}. + +@var{key} is a symbol. It will match catches of the same symbol or of +#t. + +If there is no handler at all, an error is signaled. +@end deffn + +uniform-vector-length +@c snarfed from unif.c:255 +@deffn primitive uniform-vector-length v +Returns the number of elements in @var{uve}. +@end deffn + +array? +@c snarfed from unif.c:289 +@deffn primitive array? v [prot] +Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not. + +The @var{prototype} argument is used with uniform arrays and is described +elsewhere. +@end deffn + +array-rank +@c snarfed from unif.c:360 +@deffn primitive array-rank ra +Returns the number of dimensions of @var{obj}. If @var{obj} is not an +array, @code{0} is returned. +@end deffn + +array-dimensions +@c snarfed from unif.c:398 +@deffn primitive array-dimensions ra +@code{Array-dimensions} is similar to @code{array-shape} but replaces +elements with a @code{0} minimum with one greater than the maximum. So: +@example +(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5) +@end example +@end deffn + +shared-array-root +@c snarfed from unif.c:445 +@deffn primitive shared-array-root ra +Return the root vector of a shared array. +@end deffn + +shared-array-offset +@c snarfed from unif.c:456 +@deffn primitive shared-array-offset ra +Return the root vector index of the first element in the array. +@end deffn + +shared-array-increments +@c snarfed from unif.c:467 +@deffn primitive shared-array-increments ra +For each dimension, return the distance between elements in the root vector. +@end deffn + +dimensions->uniform-array +@c snarfed from unif.c:586 +@deffn primitive dimensions->uniform-array dims prot [fill] +@deffnx primitive make-uniform-vector length prototype [fill] +Creates and returns a uniform array or vector of type corresponding to +@var{prototype} with dimensions @var{dims} or length @var{length}. If +@var{fill} is supplied, it's used to fill the array, otherwise +@var{prototype} is used. +@end deffn + +make-shared-array +@c snarfed from unif.c:672 +@deffn primitive make-shared-array oldra mapfunc . dims +@code{make-shared-array} can be used to create shared subarrays of other +arrays. The @var{mapper} is a function that translates coordinates in +the new array into coordinates in the old array. A @var{mapper} must be +linear, and its range must stay within the bounds of the old array, but +it can be otherwise arbitrary. A simple example: +@example +(define fred (make-array #f 8 8)) +(define freds-diagonal + (make-shared-array fred (lambda (i) (list i i)) 8)) +(array-set! freds-diagonal 'foo 3) +(array-ref fred 3 3) @result{} foo +(define freds-center + (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2)) +(array-ref freds-center 0 0) @result{} foo +@end example +@end deffn + +transpose-array +@c snarfed from unif.c:802 +@deffn primitive transpose-array ra . args +Returns an array sharing contents with @var{array}, but with dimensions +arranged in a different order. There must be one @var{dim} argument for +each dimension of @var{array}. @var{dim0}, @var{dim1}, @dots{} should +be integers between 0 and the rank of the array to be returned. Each +integer in that range must appear at least once in the argument list. + +The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions +in the array to be returned, their positions in the argument list to +dimensions of @var{array}. Several @var{dim}s may have the same value, +in which case the returned array will have smaller rank than +@var{array}. + +examples: +@example +(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d)) +(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d) +(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{} + #2((a 4) (b 5) (c 6)) +@end example +@end deffn + +enclose-array +@c snarfed from unif.c:911 +@deffn primitive enclose-array ra . axes +@var{dim0}, @var{dim1} @dots{} should be nonnegative integers less than +the rank of @var{array}. @var{enclose-array} returns an array +resembling an array of shared arrays. The dimensions of each shared +array are the same as the @var{dim}th dimensions of the original array, +the dimensions of the outer array are the same as those of the original +array that did not match a @var{dim}. + +An enclosed array is not a general Scheme array. Its elements may not +be set using @code{array-set!}. Two references to the same element of +an enclosed array will be @code{equal?} but will not in general be +@code{eq?}. The value returned by @var{array-prototype} when given an +enclosed array is unspecified. + +examples: +@example +(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{} + #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))> + +(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{} + #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))> +@end example +@end deffn + +array-in-bounds? +@c snarfed from unif.c:994 +@deffn primitive array-in-bounds? v . args +Returns @code{#t} if its arguments would be acceptable to array-ref. +@end deffn + +array-ref +@c snarfed from unif.c:1073 +@deffn primitive array-ref +scm_uniform_vector_ref +@end deffn + +uniform-vector-ref +@c snarfed from unif.c:1079 +@deffn primitive uniform-vector-ref v args +@deffnx primitive array-ref v . args +Returns the element at the @code{(index1, index2)} element in @var{array}. +@end deffn + +uniform-array-set1! +@c snarfed from unif.c:1248 +@deffn primitive uniform-array-set1! +scm_array_set_x +@end deffn + +array-set! +@c snarfed from unif.c:1257 +@deffn primitive array-set! v obj . args +@deffnx primitive uniform-array-set1! v obj args +Sets the element at the @code{(index1, index2)} element in @var{array} to +@var{new-value}. The value returned by array-set! is unspecified. +@end deffn + +array-contents +@c snarfed from unif.c:1372 +@deffn primitive array-contents ra [strict] +@deffnx primitive array-contents array strict +If @var{array} may be @dfn{unrolled} into a one dimensional shared array +without changing their order (last subscript changing fastest), then +@code{array-contents} returns that shared array, otherwise it returns +@code{#f}. All arrays made by @var{make-array} and +@var{make-uniform-array} may be unrolled, some arrays made by +@var{make-shared-array} may not be. + +If the optional argument @var{strict} is provided, a shared array will +be returned only if its elements are stored internally contiguous in +memory. +@end deffn + +uniform-array-read! +@c snarfed from unif.c:1486 +@deffn primitive uniform-array-read! ra [port_or_fd [start [end]]] +@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end] +Attempts to read all elements of @var{ura}, in lexicographic order, as +binary objects from @var{port-or-fdes}. +If an end of file is encountered during +uniform-array-read! the objects up to that point only are put into @var{ura} +(starting at the beginning) and the remainder of the array is +unchanged. + +The optional arguments @var{start} and @var{end} allow +a specified region of a vector (or linearized array) to be read, +leaving the remainder of the vector unchanged. + +@code{uniform-array-read!} returns the number of objects read. +@var{port-or-fdes} may be omitted, in which case it defaults to the value +returned by @code{(current-input-port)}. +@end deffn + +uniform-array-write +@c snarfed from unif.c:1649 +@deffn primitive uniform-array-write v [port_or_fd [start [end]]] +@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end] +Writes all elements of @var{ura} as binary objects to +@var{port-or-fdes}. + +The optional arguments @var{start} +and @var{end} allow +a specified region of a vector (or linearized array) to be written. + +The number of objects actually written is returned. +@var{port-or-fdes} may be +omitted, in which case it defaults to the value returned by +@code{(current-output-port)}. +@end deffn + +bit-count +@c snarfed from unif.c:1774 +@deffn primitive bit-count b bitvector +Returns the number of occurrences of the boolean @var{b} in +@var{bitvector}. +@end deffn + +bit-position +@c snarfed from unif.c:1813 +@deffn primitive bit-position item v k +Returns the minimum index of an occurrence of @var{bool} in @var{bv} +which is at least @var{k}. If no @var{bool} occurs within the specified +range @code{#f} is returned. +@end deffn + +bit-set*! +@c snarfed from unif.c:1881 +@deffn primitive bit-set*! v kv obj +If uve is a bit-vector @var{bv} and uve must be of the same +length. If @var{bool} is @code{#t}, uve is OR'ed into +@var{bv}; If @var{bool} is @code{#f}, the inversion of uve is +AND'ed into @var{bv}. + +If uve is a unsigned integer vector all the elements of uve +must be between 0 and the @code{length} of @var{bv}. The bits +of @var{bv} corresponding to the indexes in uve are set to +@var{bool}. The return value is unspecified. +@end deffn + +bit-count* +@c snarfed from unif.c:1935 +@deffn primitive bit-count* v kv obj +Returns +@example +(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t). +@end example +@var{bv} is not modified. +@end deffn + +bit-invert! +@c snarfed from unif.c:1999 +@deffn primitive bit-invert! v +Modifies @var{bv} by replacing each element with its negation. +@end deffn + +array->list +@c snarfed from unif.c:2077 +@deffn primitive array->list v +Returns a list consisting of all the elements, in order, of @var{array}. +@end deffn + +list->uniform-array +@c snarfed from unif.c:2169 +@deffn primitive list->uniform-array ndim prot lst +@deffnx procedure list->uniform-vector prot lst +Returns a uniform array of the type indicated by prototype @var{prot} +with elements the same as those of @var{lst}. Elements must be of the +appropriate type, no coercions are done. +@end deffn + +array-prototype +@c snarfed from unif.c:2520 +@deffn primitive array-prototype ra +Returns an object that would produce an array of the same type as +@var{array}, if used as the @var{prototype} for +@code{make-uniform-array}. +@end deffn + +values +@c snarfed from values.c:83 +@deffn primitive values . args +Delivers all of its arguments to its continuation. Except for +continuations created by the @code{call-with-values} procedure, +all continuations take exactly one value. The effect of +passing no value or more than one value to continuations that +were not created by @code{call-with-values} is unspecified. +@end deffn + +call-with-values +@c snarfed from values.c:116 +@deffn primitive call-with-values producer consumer +Calls its @var{producer} argument with no values and a +continuation that, when passed some values, calls the +@var{consumer} procedure with those values as arguments. The +continuation for the call to @var{consumer} is the continuation +of the call to @code{call-with-values}. + +@example +(call-with-values (lambda () (values 4 5)) + (lambda (a b) b)) + ==> 5 + +@end example +@example +(call-with-values * -) ==> -1 +@end example +@end deffn + +make-variable +@c snarfed from variable.c:100 +@deffn primitive make-variable init [name_hint] +Return a variable object initialized to value @var{init}. +If given, uses @var{name-hint} as its internal (debugging) +name, otherwise just treat it as an anonymous variable. +Remember, of course, that multiple bindings to the same +variable may exist, so @var{name-hint} is just that---a hint. +@end deffn + +make-undefined-variable +@c snarfed from variable.c:124 +@deffn primitive make-undefined-variable [name_hint] +Return a variable object initialized to an undefined value. +If given, uses @var{name-hint} as its internal (debugging) +name, otherwise just treat it as an anonymous variable. +Remember, of course, that multiple bindings to the same +variable may exist, so @var{name-hint} is just that---a hint. +@end deffn + +variable? +@c snarfed from variable.c:145 +@deffn primitive variable? obj +Return @code{#t} iff @var{obj} is a variable object, else +return @code{#f} +@end deffn + +variable-ref +@c snarfed from variable.c:157 +@deffn primitive variable-ref var +Dereference @var{var} and return its value. +@var{var} must be a variable object; see @code{make-variable} +and @code{make-undefined-variable}. +@end deffn + +variable-set! +@c snarfed from variable.c:171 +@deffn primitive variable-set! var val +Set the value of the variable @var{var} to @var{val}. +@var{var} must be a variable object, @var{val} can be any +value. Return an unspecified value. +@end deffn + +builtin-variable +@c snarfed from variable.c:185 +@deffn primitive builtin-variable name +Return the built-in variable with the name @var{name}. +@var{name} must be a symbol (not a string). +Then use @code{variable-ref} to access its value. +@end deffn + +variable-bound? +@c snarfed from variable.c:213 +@deffn primitive variable-bound? var +Return @code{#t} iff @var{var} is bound to a value. +Throws an error if @var{var} is not a variable object. +@end deffn + +vector? +@c snarfed from vectors.c:142 +@deffn primitive vector? obj +Returns @code{#t} if @var{obj} is a vector, otherwise returns +@code{#f}. (r5rs) +@end deffn + +list->vector +@c snarfed from vectors.c:161 +@deffn primitive list->vector +scm_vector +@end deffn + +vector +@c snarfed from vectors.c:177 +@deffn primitive vector . l +@deffnx primitive list->vector l +Returns a newly allocated vector whose elements contain the +given arguments. Analogous to @code{list}. (r5rs) + +@lisp +(vector 'a 'b 'c) @result{} #(a b c) +@end lisp +@end deffn + +make-vector +@c snarfed from vectors.c:255 +@deffn primitive make-vector k [fill] +Returns a newly allocated vector of @var{k} elements. If a second +argument is given, then each element is initialized to @var{fill}. +Otherwise the initial contents of each element is unspecified. (r5rs) +@end deffn + +vector->list +@c snarfed from vectors.c:311 +@deffn primitive vector->list v +@samp{Vector->list} returns a newly allocated list of the +objects contained in the elements of @var{vector}. (r5rs) + +@lisp +(vector->list '#(dah dah didah)) @result{} (dah dah didah) +(list->vector '(dididit dah)) @result{} #(dididit dah) +@end lisp +@end deffn + +vector-fill! +@c snarfed from vectors.c:328 +@deffn primitive vector-fill! v fill_x +Stores @var{fill} in every element of @var{vector}. +The value returned by @code{vector-fill!} is unspecified. (r5rs) +@end deffn + +vector-move-left! +@c snarfed from vectors.c:355 +@deffn primitive vector-move-left! vec1 start1 end1 vec2 start2 +Vector version of @code{substring-move-left!}. +@end deffn + +vector-move-right! +@c snarfed from vectors.c:378 +@deffn primitive vector-move-right! vec1 start1 end1 vec2 start2 +Vector version of @code{substring-move-right!}. +@end deffn + +major-version +@c snarfed from version.c:59 +@deffn primitive major-version +Return a string containing Guile's major version number. +E.g., "1". +@end deffn + +minor-version +@c snarfed from version.c:71 +@deffn primitive minor-version +Return a string containing Guile's minor version number. +E.g., "3.5". +@end deffn + +version +@c snarfed from version.c:90 +@deffn primitive version +@deffnx primitive major-version +@deffnx primitive minor-version +Return a string describing Guile's version number, or its major or minor +version numbers, respectively. + +@example +(version) @result{} "1.3a" +(major-version) @result{} "1" +(minor-version) @result{} "3a" +@end example +@end deffn + +make-soft-port +@c snarfed from vports.c:184 +@deffn primitive make-soft-port pv modes +Returns a port capable of receiving or delivering characters as +specified by the @var{modes} string (@pxref{File Ports, +open-file}). @var{vector} must be a vector of length 6. Its components +are as follows: + +@enumerate 0 +@item +procedure accepting one character for output +@item +procedure accepting a string for output +@item +thunk for flushing output +@item +thunk for getting one character +@item +thunk for closing port (not by garbage collection) +@end enumerate + +For an output-only port only elements 0, 1, 2, and 4 need be +procedures. For an input-only port only elements 3 and 4 need be +procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful +operation for them to perform. + +If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input, +eof-object?, ,r4rs, The Revised^4 Report on Scheme}) it indicates that +the port has reached end-of-file. For example: + +@example +(define stdout (current-output-port)) +(define p (make-soft-port + (vector + (lambda (c) (write c stdout)) + (lambda (s) (display s stdout)) + (lambda () (display "." stdout)) + (lambda () (char-upcase (read-char))) + (lambda () (display "@@" stdout))) + "rw")) + +(write p p) @result{} #<input-output: soft 8081e20> +@end example +@end deffn + +make-weak-vector +@c snarfed from weaks.c:62 +@deffn primitive make-weak-vector k [fill] +Return a weak vector with @var{size} elements. If the optional +argument @var{fill} is given, all entries in the vector will be set to +@var{fill}. The default value for @var{fill} is the empty list. +@end deffn + +list->weak-vector +@c snarfed from weaks.c:79 +@deffn primitive list->weak-vector +scm_weak_vector +@end deffn + +weak-vector +@c snarfed from weaks.c:87 +@deffn primitive weak-vector . l +@deffnx primitive list->weak-vector l +Construct a weak vector from a list: @code{weak-vector} uses the list of +its arguments while @code{list->weak-vector} uses its only argument +@var{l} (a list) to construct a weak vector the same way +@code{vector->list} would. +@end deffn + +weak-vector? +@c snarfed from weaks.c:110 +@deffn primitive weak-vector? x +Return @code{#t} if @var{obj} is a weak vector. Note that all +weak hashes are also weak vectors. +@end deffn + +make-weak-key-hash-table +@c snarfed from weaks.c:130 +@deffn primitive make-weak-key-hash-table k +@deffnx primitive make-weak-value-hash-table size +@deffnx primitive make-doubly-weak-hash-table size +Return a weak hash table with @var{size} buckets. As with any hash +table, choosing a good size for the table requires some caution. + +You can modify weak hash tables in exactly the same way you would modify +regular hash tables. (@pxref{Hash Tables}) +@end deffn + +make-weak-value-hash-table +@c snarfed from weaks.c:147 +@deffn primitive make-weak-value-hash-table k +Return a hash table with weak values with @var{size} buckets. +(@pxref{Hash Tables}) +@end deffn + +make-doubly-weak-hash-table +@c snarfed from weaks.c:165 +@deffn primitive make-doubly-weak-hash-table k +Return a hash table with weak keys and values with @var{size} +buckets. (@pxref{Hash Tables}) +@end deffn + +weak-key-hash-table? +@c snarfed from weaks.c:184 +@deffn primitive weak-key-hash-table? x +@deffnx primitive weak-value-hash-table? obj +@deffnx primitive doubly-weak-hash-table? obj +Return @code{#t} if @var{obj} is the specified weak hash +table. Note that a doubly weak hash table is neither a weak key +nor a weak value hash table. +@end deffn + +weak-value-hash-table? +@c snarfed from weaks.c:194 +@deffn primitive weak-value-hash-table? x +Return @code{#t} if @var{x} is a weak value hash table. +@end deffn + +doubly-weak-hash-table? +@c snarfed from weaks.c:204 +@deffn primitive doubly-weak-hash-table? x +Return @code{#t} if @var{x} is a doubly weak hash table. +@end deffn diff --git a/doc/new-docstrings.texi b/doc/new-docstrings.texi new file mode 100644 index 000000000..1626e9e6a --- /dev/null +++ b/doc/new-docstrings.texi @@ -0,0 +1,599 @@ + +@c module (guile) + +@deffn primitive environment? obj +Return @code{#t} if @var{obj} is an environment, or @code{#f} +otherwise. +@end deffn + +@deffn primitive environment-bound? env sym +Return @code{#t} if @var{sym} is bound in @var{env}, or +@code{#f} otherwise. +@end deffn + +@deffn primitive environment-ref env sym +Return the value of the location bound to @var{sym} in +@var{env}. If @var{sym} is unbound in @var{env}, signal an +@code{environment:unbound} error. +@end deffn + +@deffn primitive environment-fold env proc init +Iterate over all the bindings in @var{env}, accumulating some +value. +For each binding in @var{env}, apply @var{proc} to the symbol +bound, its value, and the result from the previous application +of @var{proc}. +Use @var{init} as @var{proc}'s third argument the first time +@var{proc} is applied. +If @var{env} contains no bindings, this function simply returns +@var{init}. +If @var{env} binds the symbol sym1 to the value val1, sym2 to +val2, and so on, then this procedure computes: +@example + (proc sym1 val1 + (proc sym2 val2 + ... + (proc symn valn + init))) +@end example +Each binding in @var{env} will be processed exactly once. +@code{environment-fold} makes no guarantees about the order in +which the bindings are processed. +Here is a function which, given an environment, constructs an +association list representing that environment's bindings, +using environment-fold: +@example + (define (environment->alist env) + (environment-fold env + (lambda (sym val tail) + (cons (cons sym val) tail)) + '())) +@end example +@end deffn + +@deffn primitive environment-define env sym val +Bind @var{sym} to a new location containing @var{val} in +@var{env}. If @var{sym} is already bound to another location +in @var{env} and the binding is mutable, that binding is +replaced. The new binding and location are both mutable. The +return value is unspecified. +If @var{sym} is already bound in @var{env}, and the binding is +immutable, signal an @code{environment:immutable-binding} error. +@end deffn + +@deffn primitive environment-undefine env sym +Remove any binding for @var{sym} from @var{env}. If @var{sym} +is unbound in @var{env}, do nothing. The return value is +unspecified. +If @var{sym} is already bound in @var{env}, and the binding is +immutable, signal an @code{environment:immutable-binding} error. +@end deffn + +@deffn primitive environment-set! env sym val +If @var{env} binds @var{sym} to some location, change that +location's value to @var{val}. The return value is +unspecified. +If @var{sym} is not bound in @var{env}, signal an +@code{environment:unbound} error. If @var{env} binds @var{sym} +to an immutable location, signal an +@code{environment:immutable-location} error. +@end deffn + +@deffn primitive environment-cell env sym for_write +Return the value cell which @var{env} binds to @var{sym}, or +@code{#f} if the binding does not live in a value cell. +The argument @var{for-write} indicates whether the caller +intends to modify the variable's value by mutating the value +cell. If the variable is immutable, then +@code{environment-cell} signals an +@code{environment:immutable-location} error. +If @var{sym} is unbound in @var{env}, signal an +@code{environment:unbound} error. +If you use this function, you should consider using +@code{environment-observe}, to be notified when @var{sym} gets +re-bound to a new value cell, or becomes undefined. +@end deffn + +@deffn primitive environment-observe env proc +Whenever @var{env}'s bindings change, apply @var{proc} to +@var{env}. +This function returns an object, token, which you can pass to +@code{environment-unobserve} to remove @var{proc} from the set +of procedures observing @var{env}. The type and value of +token is unspecified. +@end deffn + +@deffn primitive environment-observe-weak env proc +This function is the same as environment-observe, except that +the reference @var{env} retains to @var{proc} is a weak +reference. This means that, if there are no other live, +non-weak references to @var{proc}, it will be +garbage-collected, and dropped from @var{env}'s +list of observing procedures. +@end deffn + +@deffn primitive environment-unobserve token +Cancel the observation request which returned the value +@var{token}. The return value is unspecified. +If a call @code{(environment-observe env proc)} returns +@var{token}, then the call @code{(environment-unobserve token)} +will cause @var{proc} to no longer be called when @var{env}'s +bindings change. +@end deffn + +@deffn primitive make-leaf-environment +Create a new leaf environment, containing no bindings. +All bindings and locations created in the new environment +will be mutable. +@end deffn + +@deffn primitive leaf-environment? object +Return @code{#t} if object is a leaf environment, or @code{#f} +otherwise. +@end deffn + +@deffn primitive make-eval-environment local imported +Return a new environment object eval whose bindings are the +union of the bindings in the environments @var{local} and +@var{imported}, with bindings from @var{local} taking +precedence. Definitions made in eval are placed in @var{local}. +Applying @code{environment-define} or +@code{environment-undefine} to eval has the same effect as +applying the procedure to @var{local}. +Note that eval incorporates @var{local} and @var{imported} by +reference: +If, after creating eval, the program changes the bindings of +@var{local} or @var{imported}, those changes will be visible +in eval. +Since most Scheme evaluation takes place in eval environments, +they transparently cache the bindings received from @var{local} +and @var{imported}. Thus, the first time the program looks up +a symbol in eval, eval may make calls to @var{local} or +@var{imported} to find their bindings, but subsequent +references to that symbol will be as fast as references to +bindings in finite environments. +In typical use, @var{local} will be a finite environment, and +@var{imported} will be an import environment +@end deffn + +@deffn primitive eval-environment? object +Return @code{#t} if object is an eval environment, or @code{#f} +otherwise. +@end deffn + +@deffn primitive eval-environment-local env +Return the local environment of eval environment @var{env}. +@end deffn + +@deffn primitive eval-environment-set-local! env local +Change @var{env}'s local environment to @var{local}. +@end deffn + +@deffn primitive eval-environment-imported env +Return the imported environment of eval environment @var{env}. +@end deffn + +@deffn primitive eval-environment-set-imported! env imported +Change @var{env}'s imported environment to @var{imported}. +@end deffn + +@deffn primitive make-import-environment imports conflict_proc +Return a new environment @var{imp} whose bindings are the union +of the bindings from the environments in @var{imports}; +@var{imports} must be a list of environments. That is, +@var{imp} binds a symbol to a location when some element of +@var{imports} does. +If two different elements of @var{imports} have a binding for +the same symbol, the @var{conflict-proc} is called with the +following parameters: the import environment, the symbol and +the list of the imported environments that bind the symbol. +If the @var{conflict-proc} returns an environment @var{env}, +the conflict is considered as resolved and the binding from +@var{env} is used. If the @var{conflict-proc} returns some +non-environment object, the conflict is considered unresolved +and the symbol is treated as unspecified in the import +environment. +The checking for conflicts may be performed lazily, i. e. at +the moment when a value or binding for a certain symbol is +requested instead of the moment when the environment is +created or the bindings of the imports change. +All bindings in @var{imp} are immutable. If you apply +@code{environment-define} or @code{environment-undefine} to +@var{imp}, Guile will signal an + @code{environment:immutable-binding} error. However, +notice that the set of bindings in @var{imp} may still change, +if one of its imported environments changes. +@end deffn + +@deffn primitive import-environment? object +Return @code{#t} if object is an import environment, or +@code{#f} otherwise. +@end deffn + +@deffn primitive import-environment-imports env +Return the list of environments imported by the import +environment @var{env}. +@end deffn + +@deffn primitive import-environment-set-imports! env imports +Change @var{env}'s list of imported environments to +@var{imports}, and check for conflicts. +@end deffn + +@deffn primitive make-export-environment private signature +Return a new environment @var{exp} containing only those +bindings in private whose symbols are present in +@var{signature}. The @var{private} argument must be an +environment. + +The environment @var{exp} binds symbol to location when +@var{env} does, and symbol is exported by @var{signature}. + +@var{signature} is a list specifying which of the bindings in +@var{private} should be visible in @var{exp}. Each element of +@var{signature} should be a list of the form: + (symbol attribute ...) +where each attribute is one of the following: +@table @asis +@item the symbol @code{mutable-location} + @var{exp} should treat the + location bound to symbol as mutable. That is, @var{exp} + will pass calls to @code{environment-set!} or + @code{environment-cell} directly through to private. +@item the symbol @code{immutable-location} + @var{exp} should treat + the location bound to symbol as immutable. If the program + applies @code{environment-set!} to @var{exp} and symbol, or + calls @code{environment-cell} to obtain a writable value + cell, @code{environment-set!} will signal an + @code{environment:immutable-location} error. Note that, even + if an export environment treats a location as immutable, the + underlying environment may treat it as mutable, so its + value may change. +@end table +It is an error for an element of signature to specify both +@code{mutable-location} and @code{immutable-location}. If +neither is specified, @code{immutable-location} is assumed. + +As a special case, if an element of signature is a lone +symbol @var{sym}, it is equivalent to an element of the form +@code{(sym)}. + +All bindings in @var{exp} are immutable. If you apply +@code{environment-define} or @code{environment-undefine} to +@var{exp}, Guile will signal an +@code{environment:immutable-binding} error. However, +notice that the set of bindings in @var{exp} may still change, +if the bindings in private change. +@end deffn + +@deffn primitive export-environment? object +Return @code{#t} if object is an export environment, or +@code{#f} otherwise. +@end deffn + +@deffn primitive export-environment-private env +Return the private environment of export environment @var{env}. +@end deffn + +@deffn primitive export-environment-set-private! env private +Change the private environment of export environment @var{env}. +@end deffn + +@deffn primitive export-environment-signature env +Return the signature of export environment @var{env}. +@end deffn + +@deffn primitive export-environment-set-signature! env signature +Change the signature of export environment @var{env}. +@end deffn + +@deffn primitive %compute-slots class +Return a list consisting of the names of all slots belonging to +class @var{class}, i. e. the slots of @var{class} and of all of +its superclasses. +@end deffn + +@deffn primitive get-keyword key l default_value +Determine an associated value for the keyword @var{key} from +the list @var{l}. The list @var{l} has to consist of an even +number of elements, where, starting with the first, every +second element is a keyword, followed by its associated value. +If @var{l} does not hold a value for @var{key}, the value +@var{default_value} is returned. +@end deffn + +@deffn primitive slot-ref-using-class class obj slot_name +@end deffn + +@deffn primitive slot-set-using-class! class obj slot_name value +@end deffn + +@deffn primitive class-of x +Return the class of @var{x}. +@end deffn + +@deffn primitive %goops-loaded +Announce that GOOPS is loaded and perform initialization +on the C level which depends on the loaded GOOPS modules. +@end deffn + +@deffn primitive %method-more-specific? m1 m2 targs +@end deffn + +@deffn primitive find-method . l +@end deffn + +@deffn primitive primitive-generic-generic subr +@end deffn + +@deffn primitive enable-primitive-generic! . subrs +@end deffn + +@deffn primitive generic-capability? proc +@end deffn + +@deffn primitive %invalidate-method-cache! gf +@end deffn + +@deffn primitive %invalidate-class class +@end deffn + +@deffn primitive %modify-class old new +@end deffn + +@deffn primitive %modify-instance old new +@end deffn + +@deffn primitive %set-object-setter! obj setter +@end deffn + +@deffn primitive %allocate-instance class initargs +Create a new instance of class @var{class} and initialize it +from the arguments @var{initargs}. +@end deffn + +@deffn primitive slot-exists? obj slot_name +Return @code{#t} if @var{obj} has a slot named @var{slot_name}. +@end deffn + +@deffn primitive slot-bound? obj slot_name +Return @code{#t} if the slot named @var{slot_name} of @var{obj} +is bound. +@end deffn + +@deffn primitive slot-set! obj slot_name value +Set the slot named @var{slot_name} of @var{obj} to @var{value}. +@end deffn + +@deffn primitive slot-exists-using-class? class obj slot_name +@end deffn + +@deffn primitive slot-bound-using-class? class obj slot_name +@end deffn + +@deffn primitive %fast-slot-set! obj index value +Set the slot with index @var{index} in @var{obj} to +@var{value}. +@end deffn + +@deffn primitive %fast-slot-ref obj index +Return the slot value with index @var{index} from @var{obj}. +@end deffn + +@deffn primitive @@assert-bound-ref obj index +Like @code{assert-bound}, but use @var{index} for accessing +the value from @var{obj}. +@end deffn + +@deffn primitive assert-bound value obj +Return @var{value} if it is bound, and invoke the +@var{slot-unbound} method of @var{obj} if it is not. +@end deffn + +@deffn primitive unbound? obj +Return @code{#t} if @var{obj} is unbound. +@end deffn + +@deffn primitive make-unbound +Return the unbound value. +@end deffn + +@deffn primitive accessor-method-slot-definition obj +Return the slot definition of the accessor @var{obj}. +@end deffn + +@deffn primitive method-procedure obj +Return the procedure of the method @var{obj}. +@end deffn + +@deffn primitive method-specializers obj +Return specializers of the method @var{obj}. +@end deffn + +@deffn primitive method-generic-function obj +Return the generic function fot the method @var{obj}. +@end deffn + +@deffn primitive generic-function-methods obj +Return the methods of the generic function @var{obj}. +@end deffn + +@deffn primitive generic-function-name obj +Return the name of the generic function @var{obj}. +@end deffn + +@deffn primitive class-environment obj +Return the environment of the class @var{obj}. +@end deffn + +@deffn primitive class-slots obj +Return the slot list of the class @var{obj}. +@end deffn + +@deffn primitive class-precedence-list obj +Return the class precedence list of the class @var{obj}. +@end deffn + +@deffn primitive class-direct-methods obj +Return the direct methods of the class @var{obj} +@end deffn + +@deffn primitive class-direct-subclasses obj +Return the direct subclasses of the class @var{obj}. +@end deffn + +@deffn primitive class-direct-slots obj +Return the direct slots of the class @var{obj}. +@end deffn + +@deffn primitive class-direct-supers obj +Return the direct superclasses of the class @var{obj}. +@end deffn + +@deffn primitive class-name obj +Return the class name of @var{obj}. +@end deffn + +@deffn primitive instance? obj +Return @code{#t} if @var{obj} is an instance. +@end deffn + +@deffn primitive %inherit-magic! class dsupers +@end deffn + +@deffn primitive %prep-layout! class +@end deffn + +@deffn primitive %initialize-object obj initargs +Initialize the object @var{obj} with the given arguments +@var{initargs}. +@end deffn + +@deffn primitive make . args +Make a new object. @var{args} must contain the class and +all necessary initialization information. +@end deffn + +@deffn primitive slot-ref obj slot_name +Return the value from @var{obj}'s slot with the name +@var{slot_name}. +@end deffn + +@deffn primitive builtin-bindings +Create and return a copy of the global symbol table, removing all +unbound symbols. +@end deffn + +@deffn primitive object->string obj [printer] +Return a Scheme string obtained by printing @var{obj}. +Printing function can be specified by the optional second +argument @var{printer} (default: @code{write}). +@end deffn + +@deffn primitive gethostname +Return the host name of the current processor. +@end deffn + +@deffn primitive sethostname name +Set the host name of the current processor to @var{name}. May +only be used by the superuser. The return value is not +specified. +@end deffn + +@deffn primitive flock file operation +Apply or remove an advisory lock on an open file. +@var{operation} specifies the action to be done: +@table @code +@item LOCK_SH +Shared lock. More than one process may hold a shared lock +for a given file at a given time. +@item LOCK_EX +Exclusive lock. Only one process may hold an exclusive lock +for a given file at a given time. +@item LOCK_UN +Unlock the file. +@item LOCK_NB +Don't block when locking. May be specified by bitwise OR'ing +it to one of the other operations. +@end table +The return value is not specified. @var{file} may be an open +file descriptor or an open file descriptior port. +@end deffn + +@deffn primitive getpass prompt +Display @var{prompt} to the standard error output and read +a password from @file{/dev/tty}. If this file is not +accessible, it reads from standard input. The password may be +up to 127 characters in length. Additional characters and the +terminating newline character are discarded. While reading +the password, echoing and the generation of signals by special +characters is disabled. +@end deffn + +@deffn primitive setpriority which who prio +Set the scheduling priority of the process, process group +or user, as indicated by @var{which} and @var{who}. @var{which} +is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} +or @code{PRIO_USER}, and @var{who} is interpreted relative to +@var{which} (a process identifier for @code{PRIO_PROCESS}, +process group identifier for @code{PRIO_PGRP}, and a user +identifier for @code{PRIO_USER}. A zero value of @var{who} +denotes the current process, process group, or user. +@var{prio} is a value in the range -20 and 20, the default +priority is 0; lower priorities cause more favorable +scheduling. Sets the priority of all of the specified +processes. Only the super-user may lower priorities. +The return value is not specified. +@end deffn + +@deffn primitive getpriority which who +Return the scheduling priority of the process, process group +or user, as indicated by @var{which} and @var{who}. @var{which} +is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP} +or @code{PRIO_USER}, and @var{who} is interpreted relative to +@var{which} (a process identifier for @code{PRIO_PROCESS}, +process group identifier for @code{PRIO_PGRP}, and a user +identifier for @code{PRIO_USER}. A zero value of @var{who} +denotes the current process, process group, or user. Return +the highest priority (lowest numerical value) of any of the +specified processes. +@end deffn + +@deffn primitive cuserid +Return a string containing a user name associated with the +effective user id of the process. Return @code{#f} if this +information cannot be obtained. +@end deffn + +@deffn primitive getlogin +Return a string containing the name of the user logged in on +the controlling terminal of the process, or @code{#f} if this +information cannot be obtained. +@end deffn + +@deffn primitive chroot path +Change the root directory to that specified in @var{path}. +This directory will be used for path names beginning with +@file{/}. The root directory is inherited by all children +of the current process. Only the superuser may change the +root directory. +@end deffn + +@deffn primitive crypt key salt +Encrypt @var{key} using @var{salt} as the salt value to the +crypt(3) library call +@end deffn + +@deffn primitive mkstemp! tmpl +mkstemp creates a new unique file in the file system and +returns a new buffered port open for reading and writing to +the file. @var{tmpl} is a string specifying where the +file should be created: it must end with @code{XXXXXX} +and will be changed in place to return the name of the +temporary file. +@end deffn + +@deffn primitive %tag-body body +Internal GOOPS magic---don't use this function! +@end deffn diff --git a/doc/posix.texi b/doc/posix.texi index 7a4cc8e40..fea735015 100644 --- a/doc/posix.texi +++ b/doc/posix.texi @@ -760,9 +760,11 @@ The return value is unspecified. @c docstring begin (texi-doc-string "guile" "tmpnam") @deffn primitive tmpnam -Create a new file in the file system with a unique name. The return -value is the name of the new file. This function is implemented with -the @code{tmpnam} function in the system libraries. +tmpnam returns a name in the file system that does not match +any existing file. However there is no guarantee that +another process will not create the file after tmpnam +is called. Care should be taken if opening the file, +e.g., use the O_EXCL open flag or use @code{mkstemp!} instead. @end deffn @c docstring begin (texi-doc-string "guile" "dirname") @@ -1469,8 +1471,8 @@ of seconds remaining otherwise. @c docstring begin (texi-doc-string "guile" "usleep") @deffn primitive usleep i -Sleep for I microseconds. -`usleep' is not available on all platforms. +Sleep for I microseconds. @code{usleep} is not available on +all platforms. @end deffn @node Terminals and Ptys diff --git a/doc/scheme-data.texi b/doc/scheme-data.texi index c69a5431c..7bbf89760 100755 --- a/doc/scheme-data.texi +++ b/doc/scheme-data.texi @@ -274,8 +274,8 @@ completely invisible to the Scheme level programmer. @c on the C level, where the conversion is not so automatic - NJ @c docstring begin (texi-doc-string "guile" "integer?") -@deffn primitive integer? obj -Return @code{#t} if @var{obj} is an integer number, @code{#f} else. +@deffn primitive integer? x +Return @code{#t} if @var{x} is an integer number, @code{#f} else. @lisp (integer? 487) @@ -343,11 +343,13 @@ if @var{obj} is an integer number or a rational number. @end deffn @c docstring begin (texi-doc-string "guile" "rational?") -@deffn primitive rational? obj -Return @code{#t} if @var{obj} is a rational number, @code{#f} else. -Note that the set of integer values forms a subset of the set of -rational numbers, so the predicate will also be fulfilled if @var{obj} -is an integer number. +@deffn primitive rational? x +Return @code{#t} if @var{x} is a rational number, @code{#f} +else. Note that the set of integer values forms a subset of +the set of rational numbers, i. e. the predicate will also be +fulfilled if @var{x} is an integer number. Real numbers +will also satisfy this predicate, because of their limited +precision. @end deffn @@ -379,11 +381,12 @@ real, so the real and imaginary parts of a complex number have the same properties of inexactness and limited precision as single real numbers. @c docstring begin (texi-doc-string "guile" "complex?") -@deffn primitive complex? obj -Return @code{#t} if @var{obj} is a complex number, @code{#f} else. -Note that the sets of real, rational and integer values form subsets of -the set of complex numbers, so the predicate will also be fulfilled if -@var{obj} is a real, rational or integer number. +@deffn primitive complex? x +Return @code{#t} if @var{x} is a complex number, @code{#f} +else. Note that the sets of real, rational and integer +values form subsets of the set of complex numbers, i. e. the +predicate will also be fulfilled if @var{x} is a real, +rational or integer number. @end deffn @@ -404,12 +407,14 @@ an invocation of the @code{inexact->exact} procedure. @c docstring begin (texi-doc-string "guile" "exact?") @deffn primitive exact? x -Return #t if X is an exact number, #f otherwise. +Return @code{#t} if @var{x} is an exact number, @code{#f} +otherwise. @end deffn @c docstring begin (texi-doc-string "guile" "inexact?") @deffn primitive inexact? x -Return #t if X is an inexact number, #f else. +Return @code{#t} if @var{x} is an inexact number, @code{#f} +else. @end deffn @c docstring begin (texi-doc-string "guile" "inexact->exact") @@ -502,12 +507,14 @@ multiplying by 10^N. @c docstring begin (texi-doc-string "guile" "odd?") @deffn primitive odd? n -Return #t if N is an odd number, #f otherwise. +Return @code{#t} if @var{n} is an odd number, @code{#f} +otherwise. @end deffn @c docstring begin (texi-doc-string "guile" "even?") @deffn primitive even? n -Return #t if N is an even number, #f otherwise. +Return @code{#t} if @var{n} is an even number, @code{#f} +otherwise. @end deffn @c begin (texi-doc-string "guile" "quotient") @@ -608,19 +615,20 @@ zero. @c docstring begin (texi-doc-string "guile" "number->string") @deffn primitive number->string n [radix] Return a string holding the external representation of the -number N in the given RADIX. If N is inexact, a radix of 10 -will be used. +number @var{n} in the given @var{radix}. If @var{n} is +inexact, a radix of 10 will be used. @end deffn @c docstring begin (texi-doc-string "guile" "string->number") @deffn primitive string->number string [radix] Returns a number of the maximally precise representation -expressed by the given STRING. RADIX must be an exact integer, -either 2, 8, 10, or 16. If supplied, RADIX is a default radix -that may be overridden by an explicit radix prefix in STRING -(e.g. "#o177"). If RADIX is not supplied, then the default -radix is 10. If string is not a syntactically valid notation -for a number, then `string->number' returns #f. (r5rs) +expressed by the given @var{string}. @var{radix} must be an +exact integer, either 2, 8, 10, or 16. If supplied, @var{radix} +is a default radix that may be overridden by an explicit radix +prefix in @var{string} (e.g. "#o177"). If @var{radix} is not +supplied, then the default radix is 10. If string is not a +syntactically valid notation for a number, then +@code{string->number} returns @code{#f}. @end deffn @@ -635,13 +643,13 @@ for a number, then `string->number' returns #f. (r5rs) @c docstring begin (texi-doc-string "guile" "make-rectangular") @deffn primitive make-rectangular real imaginary -Return a complex number constructed of the given REAL and -IMAGINARY parts. +Return a complex number constructed of the given @var{real} and +@var{imaginary} parts. @end deffn @c docstring begin (texi-doc-string "guile" "make-polar") @deffn primitive make-polar x y -Return the complex number X * e^(i * Y). +Return the complex number @var{x} * e^(i * @var{y}). @end deffn @c begin (texi-doc-string "guile" "real-part") @@ -1026,15 +1034,16 @@ Example: @c ARGFIXME n/int cnt/count @c docstring begin (texi-doc-string "guile" "ash") @deffn primitive ash n cnt -The function ash performs an arithmetic shift left by CNT bits -(or shift right, if CNT is negative). 'Arithmetic' means, that -the function does not guarantee to keep the bit structure of N, -but rather guarantees that the result will always be rounded -towards minus infinity. Therefore, the results of ash and a -corresponding bitwise shift will differ if N is negative. +The function ash performs an arithmetic shift left by @var{CNT} +bits (or shift right, if @var{cnt} is negative). +'Arithmetic' means, that the function does not guarantee to +keep the bit structure of @var{n}, but rather guarantees that +the result will always be rounded towards minus infinity. +Therefore, the results of ash and a corresponding bitwise +shift will differ if N is negative. Formally, the function returns an integer equivalent to -@code{(inexact->exact (floor (* N (expt 2 CNT))))}.@refill +@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}. Example: @lisp @@ -1481,7 +1490,7 @@ a portion of the string. This procedure essentially implements the (qdocs:) Returns the index of @var{char} in @var{str}, or @code{#f} if the @var{char} isn't in @var{str}. If @var{frm} is given and not @code{#f}, -it is used as the starting index; if @var{to} is given and not @var{#f}, +it is used as the starting index; if @var{to} is given and not @code{#f}, it is used as the ending index (exclusive). @example @@ -1695,7 +1704,7 @@ Capitalize every character in @code{str}. @c docstring begin (texi-doc-string "guile" "string-ci<=?") @deffn primitive string-ci<=? s1 s2 Case insensitive lexicographic ordering predicate; -returns @t{#t} if @var{s1} is lexicographically less than +returns @code{#t} if @var{s1} is lexicographically less than or equal to @var{s2} regardless of case. (r5rs) @end deffn @@ -1703,72 +1712,77 @@ or equal to @var{s2} regardless of case. (r5rs) @c docstring begin (texi-doc-string "guile" "string-ci<?") @deffn primitive string-ci<? s1 s2 Case insensitive lexicographic ordering predicate; -returns @t{#t} if @var{s1} is lexicographically less than +returns @code{#t} if @var{s1} is lexicographically less than @var{s2} regardless of case. (r5rs) @end deffn @r5index string-ci=? @c docstring begin (texi-doc-string "guile" "string-ci=?") @deffn primitive string-ci=? s1 s2 -Case-insensitive string equality predicate; returns @t{#t} if -the two strings are the same length and their component characters -match (ignoring case) at each position; otherwise returns @t{#f}. (r5rs) +Case-insensitive string equality predicate; returns @code{#t} +if the two strings are the same length and their component +characters match (ignoring case) at each position; otherwise +returns @code{#f}. (r5rs) @end deffn @r5index string-ci>=? @c docstring begin (texi-doc-string "guile" "string-ci>=?") @deffn primitive string-ci>=? s1 s2 Case insensitive lexicographic ordering predicate; -returns @t{#t} if @var{s1} is lexicographically greater than -or equal to @var{s2} regardless of case. (r5rs) +returns @code{#t} if @var{s1} is lexicographically greater +than or equal to @var{s2} regardless of case. (r5rs) @end deffn @r5index string-ci>? @c docstring begin (texi-doc-string "guile" "string-ci>?") @deffn primitive string-ci>? s1 s2 Case insensitive lexicographic ordering predicate; -returns @t{#t} if @var{s1} is lexicographically greater than -@var{s2} regardless of case. (r5rs) +returns @code{#t} if @var{s1} is lexicographically greater +than @var{s2} regardless of case. (r5rs) @end deffn @r5index string<=? @c docstring begin (texi-doc-string "guile" "string<=?") @deffn primitive string<=? s1 s2 -Lexicographic ordering predicate; returns @t{#t} if @var{s1} -is lexicographically less than or equal to @var{s2}. (r5rs) +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically less than or equal to @var{s2}. +(r5rs) @end deffn @r5index string<? @c docstring begin (texi-doc-string "guile" "string<?") @deffn primitive string<? s1 s2 -Lexicographic ordering predicate; returns @t{#t} if @var{s1} -is lexicographically less than @var{s2}. (r5rs) +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically less than @var{s2}. (r5rs) @end deffn @r5index string=? @c docstring begin (texi-doc-string "guile" "string=?") @deffn primitive string=? s1 s2 Lexicographic equality predicate; -Returns @t{#t} if the two strings are the same length and contain the same -characters in the same positions, otherwise returns @t{#f}. (r5rs) +Returns @code{#t} if the two strings are the same length and +contain the same characters in the same positions, otherwise +returns @code{#f}. (r5rs) -@samp{String-ci=?} treats -upper and lower case letters as though they were the same character, but -@samp{string=?} treats upper and lower case as distinct characters. +The procedure @code{string-ci=?} treats upper and lower case +letters as though they were the same character, but +@code{string=?} treats upper and lower case as distinct +characters. @end deffn @r5index string>=? @c docstring begin (texi-doc-string "guile" "string>=?") @deffn primitive string>=? s1 s2 -Lexicographic ordering predicate; returns @t{#t} if @var{s1} -is lexicographically greater than or equal to @var{s2}. (r5rs) +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically greater than or equal to +@var{s2}. (r5rs) @end deffn @r5index string>? @c docstring begin (texi-doc-string "guile" "string>?") @deffn primitive string>? s1 s2 -Lexicographic ordering predicate; returns @t{#t} if @var{s1} -is lexicographically greater than @var{s2}. (r5rs) +Lexicographic ordering predicate; returns @code{#t} if +@var{s1} is lexicographically greater than @var{s2}. (r5rs) @end deffn @r5index string->list @@ -2452,57 +2466,48 @@ Returns the symbol whose name is @var{string}. This procedure can create symbols with names containing special characters or letters in the non-standard case, but it is usually a bad idea to create such symbols because in some implementations of Scheme they cannot be read as -themselves. See @samp{symbol->string}. - -The following examples assume that the implementation's standard case is -lower case: - -@format -@t{(eq? 'mISSISSIppi 'mississippi) - ==> #t -(string->symbol "mISSISSIppi") - ==> - @r{}the symbol with name "mISSISSIppi" -(eq? 'bitBlt (string->symbol "bitBlt")) - ==> #f +themselves. See @code{symbol->string}. + +The following examples assume that the implementation's +standard case is lower case: + +@lisp +(eq? 'mISSISSIppi 'mississippi) @result{} #t +(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"} +(eq? 'bitBlt (string->symbol "bitBlt")) @result{} #f (eq? 'JollyWog - (string->symbol - (symbol->string 'JollyWog))) - ==> #t + (string->symbol (symbol->string 'JollyWog))) @result{} #t (string=? "K. Harper, M.D." - (symbol->string - (string->symbol "K. Harper, M.D."))) - ==> #t -} -@end format + (symbol->string + (string->symbol "K. Harper, M.D."))) @result{}#t +@end lisp @end deffn @c docstring begin (texi-doc-string "guile" "symbol->string") -@deffn primitive symbol->string symbol -Returns the name of @var{symbol} as a string. If the symbol was part of -an object returned as the value of a literal expression (section -@pxref{Literal expressions,,,r4rs, The Revised^4 Report on Scheme}) or -by a call to the @samp{read} procedure, and its name contains alphabetic -characters, then the string returned will contain characters in the -implementation's preferred standard case---some implementations will -prefer upper case, others lower case. If the symbol was returned by -@samp{string->symbol}, the case of characters in the string returned -will be the same as the case in the string that was passed to -@samp{string->symbol}. It is an error to apply mutation procedures like -@code{string-set!} to strings returned by this procedure. (r5rs) - -The following examples assume that the implementation's standard case is -lower case: - -@format -@t{(symbol->string 'flying-fish) - ==> "flying-fish" -(symbol->string 'Martin) ==> "martin" +@deffn primitive symbol->string s +Returns the name of @var{symbol} as a string. If the symbol +was part of an object returned as the value of a literal +expression (section @pxref{Literal expressions,,,r4rs, The +Revised^4 Report on Scheme}) or by a call to the @code{read} +procedure, and its name contains alphabetic characters, then +the string returned will contain characters in the +implementation's preferred standard case---some implementations +will prefer upper case, others lower case. If the symbol was +returned by @code{string->symbol}, the case of characters in +the string returned will be the same as the case in the string +that was passed to @code{string->symbol}. It is an error to +apply mutation procedures like @code{string-set!} to strings +returned by this procedure. (r5rs) + +The following examples assume that the implementation's +standard case is lower case: + +@lisp +(symbol->string 'flying-fish) @result{} "flying-fish" +(symbol->string 'Martin) @result{} "martin" (symbol->string - (string->symbol "Malvina")) - ==> "Malvina" -} -@end format + (string->symbol "Malvina")) @result{} "Malvina" +@end lisp @end deffn @c docstring begin (texi-doc-string "guile" "symbol-binding") @@ -2515,11 +2520,12 @@ use the global symbol table. If @var{string} is not interned in @c docstring begin (texi-doc-string "guile" "symbol-bound?") @deffn primitive symbol-bound? obarray string -Return @var{#t} if @var{obarray} contains a symbol with name +Return @code{#t} if @var{obarray} contains a symbol with name @var{string} bound to a defined value. This differs from -@var{symbol-interned?} in that the mere mention of a symbol usually causes -it to be interned; @code{symbol-bound?} determines whether a symbol has -been given any meaningful value. +@var{symbol-interned?} in that the mere mention of a symbol +usually causes it to be interned; @code{symbol-bound?} +determines whether a symbol has been given any meaningful +value. @end deffn @c docstring begin (texi-doc-string "guile" "symbol-fref") @@ -2539,8 +2545,8 @@ Return a hash value for @var{symbol}. @c docstring begin (texi-doc-string "guile" "symbol-interned?") @deffn primitive symbol-interned? obarray string -Return @var{#t} if @var{obarray} contains a symbol with name -@var{string}, and @var{#f} otherwise. +Return @code{#t} if @var{obarray} contains a symbol with name +@var{string}, and @code{#f} otherwise. @end deffn @c docstring begin (texi-doc-string "guile" "symbol-pref") @@ -2562,7 +2568,8 @@ in @var{obarray}. @c docstring begin (texi-doc-string "guile" "symbol?") @deffn primitive symbol? obj -Returns @t{#t} if @var{obj} is a symbol, otherwise returns @t{#f}. (r5rs) +Returns @code{#t} if @var{obj} is a symbol, otherwise returns +@code{#f}. (r5rs) @end deffn @c docstring begin (texi-doc-string "guile" "unintern-symbol") @@ -2905,53 +2912,51 @@ by @code{set-cdr!} is unspecified. @c docstring begin (texi-doc-string "guile" "list") @deffn primitive list . objs -Return a list containing OBJS, the arguments to `list'. +Return a list containing @var{objs}, the arguments to +@code{list}. @end deffn @c docstring begin (texi-doc-string "guile" "cons*") @deffn primitive cons* arg . rest -@deffnx primitive list* arg . rest -Like `list', but the last arg provides the tail of the constructed list, -returning (cons ARG1 (cons ARG2 (cons ... ARGn))). -Requires at least one argument. If given one argument, that argument -is returned as result. -This function is called `list*' in some other Schemes and in Common LISP. +Like @code{list}, but the last arg provides the tail of the +constructed list, returning @code{(cons @var{arg1} (cons +@var{arg2} (cons @dots{} @var{argn}))). Requires at least one +argument. If given one argument, that argument is returned as +result. This function is called @code{list*} in some other +Schemes and in Common LISP. @end deffn @c docstring begin (texi-doc-string "guile" "list?") @deffn primitive list? x -Return #t iff X is a proper list, else #f. +Return @code{#t} iff @var{x} is a proper list, else @code{#f}. @end deffn @c docstring begin (texi-doc-string "guile" "null?") @deffn primitive null? x -Return #t iff X is the empty list, else #f. +Return @code{#t} iff @var{x} is the empty list, else @code{#f}. @end deffn @c docstring begin (texi-doc-string "guile" "length") @deffn primitive length lst -Return the number of elements in list LST. +Return the number of elements in list @var{lst}. @end deffn @c docstring begin (texi-doc-string "guile" "append") @deffn primitive append . args -Returns a list consisting of the elements of the first LIST -followed by the elements of the other LISTs. - +Return a list consisting of the elements the lists passed as +arguments. @example - (append '(x) '(y)) => (x y) - (append '(a) '(b c d)) => (a b c d) - (append '(a (b)) '((c))) => (a (b) (c)) +(append '(x) '(y)) @result{} (x y) +(append '(a) '(b c d)) @result{} (a b c d) +(append '(a (b)) '((c))) @result{} (a (b) (c)) @end example - -The resulting list is always newly allocated, except that it shares -structure with the last LIST argument. The last argument may -actually be any object; an improper list results if the last -argument is not a proper list. - +The resulting list is always newly allocated, except that it +shares structure with the last list argument. The last +argument may actually be any object; an improper list results +if the last argument is not a proper list. @example - (append '(a b) '(c . d)) => (a b c . d) - (append '() 'a) => a +(append '(a b) '(c . d)) @result{} (a b c . d) +(append '() 'a) @result{} a @end example @end deffn @@ -2972,7 +2977,8 @@ Return a pointer to the last pair in @var{lst}, signalling an error if @c docstring begin (texi-doc-string "guile" "reverse") @deffn primitive reverse lst -Return a new list that contains the elements of LST but in reverse order. +Return a new list that contains the elements of @var{lst} but +in reverse order. @end deffn @c NJFIXME explain new_tail @@ -2993,7 +2999,7 @@ of the modified list is not lost, it is wise to save the return value of @c docstring begin (texi-doc-string "guile" "list-ref") @deffn primitive list-ref list k -Return the Kth element from LIST. +Return the @var{k}th element from @var{list}. @end deffn @c docstring begin (texi-doc-string "guile" "list-set!") @@ -3031,53 +3037,56 @@ Return a (newly-created) copy of @var{lst}. @c docstring begin (texi-doc-string "guile" "memq") @deffn primitive memq x lst -Return the first sublist of LST whose car is `eq?' to X -where the sublists of LST are the non-empty lists returned -by `(list-tail LST K)' for K less than the length of LST. If -X does not occur in LST, then `#f' (not the empty list) is +Return the first sublist of @var{lst} whose car is @code{eq?} +to @var{x} where the sublists of @var{lst} are the non-empty +lists returned by @code{(list-tail @var{lst} @var{k})} for +@var{k} less than the length of @var{lst}. If @var{x} does not +occur in @var{lst}, then @code{#f} (not the empty list) is returned. @end deffn @c docstring begin (texi-doc-string "guile" "memv") @deffn primitive memv x lst -Return the first sublist of LST whose car is `eqv?' to X -where the sublists of LST are the non-empty lists returned -by `(list-tail LST K)' for K less than the length of LST. If -X does not occur in LST, then `#f' (not the empty list) is +Return the first sublist of @var{lst} whose car is @code{eqv?} +to @var{x} where the sublists of @var{lst} are the non-empty +lists returned by @code{(list-tail @var{lst} @var{k})} for +@var{k} less than the length of @var{lst}. If @var{x} does not +occur in @var{lst}, then @code{#f} (not the empty list) is returned. @end deffn @c docstring begin (texi-doc-string "guile" "member") @deffn primitive member x lst -Return the first sublist of LST whose car is `equal?' to X -where the sublists of LST are the non-empty lists returned -by `(list-tail LST K)' for K less than the length of LST. If -X does not occur in LST, then `#f' (not the empty list) is -returned. +Return the first sublist of @var{lst} whose car is +@code{equal?} to @var{x} where the sublists of @var{lst} are +the non-empty lists returned by @code{(list-tail @var{lst} +@var{k})} for @var{k} less than the length of @var{lst}. If +@var{x} does not occur in @var{lst}, then @code{#f} (not the +empty list) is returned. @end deffn @c docstring begin (texi-doc-string "guile" "delq") @deffn primitive delq item lst -Return a newly-created copy of @var{lst} with elements `eq?' to @var{item} removed. -This procedure mirrors @code{memq}: -@code{delq} compares elements of @var{lst} against @var{item} with -@code{eq?}. +Return a newly-created copy of @var{lst} with elements +@code{eq?} to @var{item} removed. This procedure mirrors +@code{memq}: @code{delq} compares elements of @var{lst} against +@var{item} with @code{eq?}. @end deffn @c docstring begin (texi-doc-string "guile" "delv") @deffn primitive delv item lst -Return a newly-created copy of @var{lst} with elements `eqv?' to @var{item} removed. -This procedure mirrors @code{memv}: -@code{delv} compares elements of @var{lst} against @var{item} with -@code{eqv?}. +Return a newly-created copy of @var{lst} with elements +@code{eqv?} to @var{item} removed. This procedure mirrors +@code{memv}: @code{delv} compares elements of @var{lst} against +@var{item} with @code{eqv?}. @end deffn @c docstring begin (texi-doc-string "guile" "delete") @deffn primitive delete item lst -Return a newly-created copy of @var{lst} with elements `equal?' to @var{item} removed. -This procedure mirrors @code{member}: -@code{delete} compares elements of @var{lst} against @var{item} with -@code{equal?}. +Return a newly-created copy of @var{lst} with elements +@code{equal?} to @var{item} removed. This procedure mirrors +@code{member}: @code{delete} compares elements of @var{lst} +against @var{item} with @code{equal?}. @end deffn @c docstring begin (texi-doc-string "guile" "delq!") @@ -3096,20 +3105,23 @@ destructive list functions, these functions cannot modify the binding of @c docstring begin (texi-doc-string "guile" "delq1!") @deffn primitive delq1! item lst -Like `delq!', but only deletes the first occurrence of ITEM from LST. -Tests for equality using `eq?'. See also `delv1!' and `delete1!'. +Like @code{delq!}, but only deletes the first occurrence of +@var{item} from @var{lst}. Tests for equality using +@code{eq?}. See also @code{delv1!} and @code{delete1!}. @end deffn @c docstring begin (texi-doc-string "guile" "delv1!") @deffn primitive delv1! item lst -Like `delv!', but only deletes the first occurrence of ITEM from LST. -Tests for equality using `eqv?'. See also `delq1!' and `delete1!'. +Like @code{delv!}, but only deletes the first occurrence of +@var{item} from @var{lst}. Tests for equality using +@code{eqv?}. See also @code{delq1!} and @code{delete1!}. @end deffn @c docstring begin (texi-doc-string "guile" "delete1!") @deffn primitive delete1! item lst -Like `delete!', but only deletes the first occurrence of ITEM from LST. -Tests for equality using `equal?'. See also `delq1!' and `delv1!'. +Like @code{delete!}, but only deletes the first occurrence of +@var{item} from @var{lst}. Tests for equality using +@code{equal?}. See also @code{delq1!} and @code{delv1!}. @end deffn [FIXME: is there any reason to have the `sloppy' functions available at @@ -3450,7 +3462,8 @@ For more information, see the documentation for @code{make-vtable-vtable}. @c docstring begin (texi-doc-string "guile" "struct?") @deffn primitive struct? x -Return #t iff @var{obj} is a structure object, else #f. +Return @code{#t} iff @var{obj} is a structure object, else +@code{#f}. @end deffn @@ -3486,7 +3499,7 @@ Return the vtable structure that describes the type of @var{struct}. @c docstring begin (texi-doc-string "guile" "struct-vtable?") @deffn primitive struct-vtable? x -Return #t iff obj is a vtable structure. +Return @code{#t} iff obj is a vtable structure. @end deffn If you have a vtable structure, @code{V}, you can create an instance of @@ -4543,8 +4556,8 @@ any Scheme object. @deffn primitive hashq-ref table obj [dflt] Look up @var{key} in the hash table @var{table}, and return the value (if any) associated with it. If @var{key} is not found, -return @var{default} (or @code{#f} if no @var{default} argument is -supplied). Uses `eq?' for equality testing. +return @var{default} (or @code{#f} if no @var{default} argument +is supplied). Uses @code{eq?} for equality testing. @end deffn @c ARGFIXME obj/key @@ -4552,8 +4565,8 @@ supplied). Uses `eq?' for equality testing. @deffn primitive hashv-ref table obj [dflt] Look up @var{key} in the hash table @var{table}, and return the value (if any) associated with it. If @var{key} is not found, -return @var{default} (or @code{#f} if no @var{default} argument is -supplied). Uses `eqv?' for equality testing. +return @var{default} (or @code{#f} if no @var{default} argument +is supplied). Uses @code{eqv?} for equality testing. @end deffn @c ARGFIXME obj/key @@ -4561,50 +4574,51 @@ supplied). Uses `eqv?' for equality testing. @deffn primitive hash-ref table obj [dflt] Look up @var{key} in the hash table @var{table}, and return the value (if any) associated with it. If @var{key} is not found, -return @var{default} (or @code{#f} if no @var{default} argument is -supplied). Uses `equal?' for equality testing. +return @var{default} (or @code{#f} if no @var{default} argument +is supplied). Uses @code{equal?} for equality testing. @end deffn @c ARGFIXME obj/key @c docstring begin (texi-doc-string "guile" "hashq-set!") @deffn primitive hashq-set! table obj val -Find the entry in @var{table} associated with @var{key}, and store -@var{value} there. Uses `eq?' for equality testing. +Find the entry in @var{table} associated with @var{key}, and +store @var{value} there. Uses @code{eq?} for equality testing. @end deffn @c ARGFIXME obj/key @c docstring begin (texi-doc-string "guile" "hashv-set!") @deffn primitive hashv-set! table obj val -Find the entry in @var{table} associated with @var{key}, and store -@var{value} there. Uses `eqv?' for equality testing. +Find the entry in @var{table} associated with @var{key}, and +store @var{value} there. Uses @code{eqv?} for equality testing. @end deffn @c ARGFIXME obj/key @c docstring begin (texi-doc-string "guile" "hash-set!") @deffn primitive hash-set! table obj val -Find the entry in @var{table} associated with @var{key}, and store -@var{value} there. Uses `equal?' for equality testing. +Find the entry in @var{table} associated with @var{key}, and +store @var{value} there. Uses @code{equal?} for equality +testing. @end deffn @c ARGFIXME obj/key @c docstring begin (texi-doc-string "guile" "hashq-remove!") @deffn primitive hashq-remove! table obj -Remove @var{key} (and any value associated with it) from @var{table}. -Uses `eq?' for equality tests. +Remove @var{key} (and any value associated with it) from +@var{table}. Uses @code{eq?} for equality tests. @end deffn @c ARGFIXME obj/key @c docstring begin (texi-doc-string "guile" "hashv-remove!") @deffn primitive hashv-remove! table obj -Remove @var{key} (and any value associated with it) from @var{table}. -Uses `eqv?' for equality tests. +Remove @var{key} (and any value associated with it) from +@var{table}. Uses @code{eqv?} for equality tests. @end deffn @c ARGFIXME obj/key @c docstring begin (texi-doc-string "guile" "hash-remove!") @deffn primitive hash-remove! table obj -Remove @var{key} (and any value associated with it) from @var{table}. -Uses `equal?' for equality tests. +Remove @var{key} (and any value associated with it) from +@var{table}. Uses @code{equal?} for equality tests. @end deffn The standard hash table functions may be too limited for some @@ -4624,36 +4638,38 @@ explanation of how hash tables are implemented. @c docstring begin (texi-doc-string "guile" "hashq") @deffn primitive hashq key size -Determine a hash value for KEY that is suitable for lookups in -a hashtable of size SIZE, where eq? is used as the equality -predicate. The function returns an integer in the range 0 to -SIZE - 1. NOTE that `hashq' may use internal addresses. -Thus two calls to hashq where the keys are eq? are not -guaranteed to deliver the same value if the key object gets -garbage collected in between. This can happen, for example -with symbols: (hashq 'foo n) (gc) (hashq 'foo n) may produce two -different values, since 'foo will be garbage collected. +Determine a hash value for @var{key} that is suitable for +lookups in a hashtable of size @var{size}, where @code{eq?} is +used as the equality predicate. The function returns an +integer in the range 0 to @var{size} - 1. Note that +@code{hashq} may use internal addresses. Thus two calls to +hashq where the keys are @code{eq?} are not guaranteed to +deliver the same value if the key object gets garbage collected +in between. This can happen, for example with symbols: +@code{(hashq 'foo n) (gc) (hashq 'foo n)} may produce two +different values, since @code{foo} will be garbage collected. @end deffn @c docstring begin (texi-doc-string "guile" "hashv") @deffn primitive hashv key size -Determine a hash value for KEY that is suitable for lookups in -a hashtable of size SIZE, where eqv? is used as the equality -predicate. The function returns an integer in the range 0 to -SIZE - 1. NOTE that (hashv key) may use internal addresses. -Thus two calls to hashv where the keys are eqv? are not -guaranteed to deliver the same value if the key object gets -garbage collected in between. This can happen, for example -with symbols: (hashv 'foo n) (gc) (hashv 'foo n) may produce two -different values, since 'foo will be garbage collected. +Determine a hash value for @var{key} that is suitable for +lookups in a hashtable of size @var{size}, where @code{eqv?} is +used as the equality predicate. The function returns an +integer in the range 0 to @var{size} - 1. Note that +@code{(hashv key)} may use internal addresses. Thus two calls +to hashv where the keys are @code{eqv?} are not guaranteed to +deliver the same value if the key object gets garbage collected +in between. This can happen, for example with symbols: +@code{(hashv 'foo n) (gc) (hashv 'foo n)} may produce two +different values, since @code{foo} will be garbage collected. @end deffn @c docstring begin (texi-doc-string "guile" "hash") @deffn primitive hash key size -Determine a hash value for KEY that is suitable for lookups in -a hashtable of size SIZE, where equal? is used as the equality -predicate. The function returns an integer in the range 0 to -SIZE - 1. +Determine a hash value for @var{key} that is suitable for +lookups in a hashtable of size @var{size}, where @code{equal?} +is used as the equality predicate. The function returns an +integer in the range 0 to @var{size} - 1. @end deffn @c ARGFIXME hash/hasher @@ -4784,27 +4800,24 @@ Otherwise the initial contents of each element is unspecified. (r5rs) @c docstring begin (texi-doc-string "guile" "list->vector") @deffn primitive vector . l @deffnx primitive list->vector l -Returns a newly allocated vector whose elements contain the given -arguments. Analogous to @samp{list}. (r5rs) +Returns a newly allocated vector whose elements contain the +given arguments. Analogous to @code{list}. (r5rs) -@format -@t{(vector 'a 'b 'c) ==> #(a b c) } -@end format +@lisp +(vector 'a 'b 'c) @result{} #(a b c) +@end lisp @end deffn @r5index vector->list @c docstring begin (texi-doc-string "guile" "vector->list") @deffn primitive vector->list v -@samp{Vector->list} returns a newly allocated list of the objects contained -in the elements of @var{vector}. (r5rs) +@samp{Vector->list} returns a newly allocated list of the +objects contained in the elements of @var{vector}. (r5rs) -@format -@t{(vector->list '#(dah dah didah)) -=> (dah dah didah) -list->vector '(dididit dah)) -=> #(dididit dah) -} -@end format +@lisp +(vector->list '#(dah dah didah)) @result{} (dah dah didah) +(list->vector '(dididit dah)) @result{} #(dididit dah) +@end lisp @end deffn @r5index vector-fill! @@ -4812,13 +4825,14 @@ list->vector '(dididit dah)) @c docstring begin (texi-doc-string "guile" "vector-fill!") @deffn primitive vector-fill! v fill_x Stores @var{fill} in every element of @var{vector}. -The value returned by @samp{vector-fill!} is unspecified. (r5rs) +The value returned by @code{vector-fill!} is unspecified. (r5rs) @end deffn @r5index vector? @c docstring begin (texi-doc-string "guile" "vector?") @deffn primitive vector? obj -Returns @t{#t} if @var{obj} is a vector, otherwise returns @t{#f}. (r5rs) +Returns @code{#t} if @var{obj} is a vector, otherwise returns +@code{#f}. (r5rs) @end deffn @r5index vector-length diff --git a/doc/scheme-evaluation.texi b/doc/scheme-evaluation.texi index 8211aa37a..26a3c3238 100644 --- a/doc/scheme-evaluation.texi +++ b/doc/scheme-evaluation.texi @@ -132,9 +132,10 @@ dynamically typed by the user. @c docstring begin (texi-doc-string "guile" "eval-string") @deffn primitive eval-string string -Evaluate @var{string} as the text representation of a Scheme form -or forms, and return whatever value they produce. -Evaluation takes place in (interaction-environment). +Evaluate @var{string} as the text representation of a Scheme +form or forms, and return whatever value they produce. +Evaluation takes place in the environment returned by the +procedure @code{interaction-environment}. @end deffn @c docstring begin (texi-doc-string "guile" "apply:nconc2last") @@ -191,31 +192,34 @@ this section. @c ARGFIXME file/filename @c docstring begin (texi-doc-string "guile" "primitive-load") @deffn primitive primitive-load filename -Load @var{file} and evaluate its contents in the top-level environment. -The load paths are not searched; @var{file} must either be a full -pathname or be a pathname relative to the current directory. If the -variable @code{%load-hook} is defined, it should be bound to a procedure -that will be called before any code is loaded. See documentation for -@code{%load-hook} later in this section. +Load the file named @var{filename} and evaluate its contents in +the top-level environment. The load paths are not searched; +@var{filename} must either be a full pathname or be a pathname +relative to the current directory. If the variable +@code{%load-hook} is defined, it should be bound to a procedure +that will be called before any code is loaded. See the +documentation for @code{%load-hook} later in this section. @end deffn @c ARGFIXME file/filename @c docstring begin (texi-doc-string "guile" "primitive-load-path") @deffn primitive primitive-load-path filename -Search @var{%load-path} for @var{file} and load it into the top-level -environment. If @var{file} is a relative pathname and is not found in -the list of search paths, an error is signalled. +Search @var{%load-path} for the file named @var{filename} and +load it into the top-level environment. If @var{filename} is a +relative pathname and is not found in the list of search paths, +an error is signalled. @end deffn @c ARGFIXME file/filename @c docstring begin (texi-doc-string "guile" "%search-load-path") @deffn primitive %search-load-path filename -Search @var{%load-path} for @var{file}, which must be readable by the -current user. If @var{file} is found in the list of paths to search or -is an absolute pathname, return its full pathname. Otherwise, return -@code{#f}. Filenames may have any of the optional extensions in the -@code{%load-extensions} list; @code{%search-load-path} will try each -extension automatically. +Search @var{%load-path} for the file named @var{filename}, +which must be readable by the current user. If @var{filename} +is found in the list of paths to search or is an absolute +pathname, return its full pathname. Otherwise, return +@code{#f}. Filenames may have any of the optional extensions +in the @code{%load-extensions} list; @code{%search-load-path} +will try each extension automatically. @end deffn @defvar %load-hook @@ -255,7 +259,7 @@ list @code{("" ".scm")}. @c ARGFIXME x/obj @c docstring begin (texi-doc-string "guile" "promise?") -@deffn primitive promise? x +@deffn primitive promise? obj Return true if @var{obj} is a promise, i.e. a delayed computation (@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}). @end deffn @@ -263,8 +267,9 @@ Return true if @var{obj} is a promise, i.e. a delayed computation @r5index force @c docstring begin (texi-doc-string "guile" "force") @deffn primitive force x -If the promise X has not been computed yet, compute and return -X, otherwise just return the previously computed value. +If the promise @var{x} has not been computed yet, compute and +return @var{x}, otherwise just return the previously computed +value. @end deffn diff --git a/doc/scheme-io.texi b/doc/scheme-io.texi index f3a6a9001..0a64c52c7 100644 --- a/doc/scheme-io.texi +++ b/doc/scheme-io.texi @@ -51,7 +51,8 @@ Returns @code{#t} if @var{x} is an output port, otherwise returns @c docstring begin (texi-doc-string "guile" "port?") @deffn primitive port? x Returns a boolean indicating whether @var{x} is a port. -Equivalent to @code{(or (input-port? X) (output-port? X))}. +Equivalent to @code{(or (input-port? @var{x}) (output-port? +@var{x}))}. @end deffn @@ -135,13 +136,13 @@ characters) and returns the content as a single string. @c docstring begin (texi-doc-string "guile" "port-column") @c docstring begin (texi-doc-string "guile" "port-line") @deffn primitive port-column port -@deffnx primitive port-line [input-port] -Return the current column number or line number of @var{input-port}, +@deffnx primitive port-line port +Return the current column number or line number of @var{port}, using the current input port if none is specified. If the number is unknown, the result is #f. Otherwise, the result is a 0-origin integer - i.e. the first character of the first line is line 0, column 0. (However, when you display a file position, for example in an error -message, we recommand you add 1 to get 1-origin integers. This is +message, we recommend you add 1 to get 1-origin integers. This is because lines and column numbers traditionally start with 1, and that is what non-programmers will find most natural.) @end deffn @@ -216,8 +217,9 @@ included print state @var{pstate}. @c docstring begin (texi-doc-string "guile" "print-options-interface") @deffn primitive print-options-interface [setting] Option interface for the print options. Instead of using -this procedure directly, use the procedures @code{print-enable}, -@code{print-disable}, @code{print-set!} and @var{print-options}. +this procedure directly, use the procedures +@code{print-enable}, @code{print-disable}, @code{print-set!} +and @code{print-options}. @end deffn @c docstring begin (texi-doc-string "guile" "simple-format") @@ -460,19 +462,19 @@ internals. @c docstring begin (texi-doc-string "guile" "%read-delimited!") @deffn primitive %read-delimited! delims str gobble [port [start [end]]] Read characters from @var{port} into @var{str} until one of the -characters in the @var{delims} string is encountered. If @var{gobble} -is true, discard the delimiter character; otherwise, leave it -in the input stream for the next read. -If @var{port} is not specified, use the value of -@code{(current-input-port)}. If @var{start} or @var{end} are specified, -store data only into the substring of @var{str} bounded by @var{start} -and @var{end} (which default to the beginning and end of the string, -respectively). - -Return a pair consisting of the delimiter that terminated the string and -the number of characters read. If reading stopped at the end of file, -the delimiter returned is the @var{eof-object}; if the string was filled -without encountering a delimiter, this value is @var{#f}. +characters in the @var{delims} string is encountered. If +@var{gobble} is true, discard the delimiter character; +otherwise, leave it in the input stream for the next read. If +@var{port} is not specified, use the value of +@code{(current-input-port)}. If @var{start} or @var{end} are +specified, store data only into the substring of @var{str} +bounded by @var{start} and @var{end} (which default to the +beginning and end of the string, respectively). + Return a pair consisting of the delimiter that terminated the +string and the number of characters read. If reading stopped +at the end of file, the delimiter returned is the +@var{eof-object}; if the string was filled without encountering +a delimiter, this value is @code{#f}. @end deffn @c docstring begin (texi-doc-string "guile" "%read-line") diff --git a/doc/scheme-memory.texi b/doc/scheme-memory.texi index 54ee5dfec..b01d7915d 100644 --- a/doc/scheme-memory.texi +++ b/doc/scheme-memory.texi @@ -104,9 +104,9 @@ regular hash tables. (@pxref{Hash Tables}) @deffn primitive weak-key-hash-table? x @deffnx primitive weak-value-hash-table? obj @deffnx primitive doubly-weak-hash-table? obj -Return @var{#t} if @var{obj} is the specified weak hash table. Note -that a doubly weak hash table is neither a weak key nor a weak value -hash table. +Return @code{#t} if @var{obj} is the specified weak hash +table. Note that a doubly weak hash table is neither a weak key +nor a weak value hash table. @end deffn @c docstring begin (texi-doc-string "guile" "make-weak-value-hash-table") @@ -154,8 +154,8 @@ its arguments while @code{list->weak-vector} uses its only argument @c ARGFIXME x/obj @c docstring begin (texi-doc-string "guile" "weak-vector?") @deffn primitive weak-vector? x -Return @var{#t} if @var{obj} is a weak vector. Note that all weak -hashes are also weak vectors. +Return @code{#t} if @var{obj} is a weak vector. Note that all +weak hashes are also weak vectors. @end deffn |