mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 11:50:28 +02:00
Code Activity

* scheme-options.texi, scheme-procedures.texi,

Browse source 
scheme-modules.texi, scheme-memory.texi, scheme-control.texi,
	scheme-utility.texi, scheme-io.texi, scheme-evaluation.texi,
	scheme-data.texi: Removed a lot of ARGFIXME's after tweaking
	docstrings and C source.

	* new-docstrings.texi, scheme-io.texi, scheme-data.texi,
	posix.texi, scheme-control.texi, scheme-evaluation.texi,
	scheme-memory.texi, scheme-procedures.texi, scheme-modules.texi,
	scheme-scheduling.texi: Automated docstring merging.
This commit is contained in:
Martin Grabmüller 2001-04-03 13:11:14 +00:00
parent abaec75d1d
commit ae9f3a1582
15 changed files with 1641 additions and 1875 deletions
Download patch file Download diff file Expand all files Collapse all files

13
doc/ChangeLog
View file

@ -1,3 +1,16 @@
2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* scheme-options.texi, scheme-procedures.texi,
scheme-modules.texi, scheme-memory.texi, scheme-control.texi,
scheme-utility.texi, scheme-io.texi, scheme-evaluation.texi,
scheme-data.texi: Removed a lot of ARGFIXME's after tweaking
docstrings and C source.
* new-docstrings.texi, scheme-io.texi, scheme-data.texi,
posix.texi, scheme-control.texi, scheme-evaluation.texi,
scheme-memory.texi, scheme-procedures.texi, scheme-modules.texi,
scheme-scheduling.texi: Automated docstring merging.
2001-04-02 Neil Jerram <neil@ossau.uklinux.net> 2001-04-02 Neil Jerram <neil@ossau.uklinux.net>
* data-rep.texi (Immediates vs. Non-immediates): Update * data-rep.texi (Immediates vs. Non-immediates): Update

4
doc/maint/ChangeLog
View file

@ -1,3 +1,7 @@
2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* guile.texi: Automated docstring merging.
2001-03-23 Neil Jerram <neil@ossau.uklinux.net> 2001-03-23 Neil Jerram <neil@ossau.uklinux.net>
* ChangeLog, README, docstring.el, guile.texi: New files. * ChangeLog, README, docstring.el, guile.texi: New files.

1719
doc/maint/guile.texi
View file

File diff suppressed because it is too large Load diff

19
doc/new-docstrings.texi
View file

@ -29,26 +29,26 @@ If @var{env} contains no bindings, this function simply returns
@var{init}. @var{init}.
If @var{env} binds the symbol sym1 to the value val1, sym2 to If @var{env} binds the symbol sym1 to the value val1, sym2 to
val2, and so on, then this procedure computes: val2, and so on, then this procedure computes:
@example @lisp
(proc sym1 val1 (proc sym1 val1
(proc sym2 val2 (proc sym2 val2
... ...
(proc symn valn (proc symn valn
init))) init)))
@end example @end lisp
Each binding in @var{env} will be processed exactly once. Each binding in @var{env} will be processed exactly once.
@code{environment-fold} makes no guarantees about the order in @code{environment-fold} makes no guarantees about the order in
which the bindings are processed. which the bindings are processed.
Here is a function which, given an environment, constructs an Here is a function which, given an environment, constructs an
association list representing that environment's bindings, association list representing that environment's bindings,
using environment-fold: using environment-fold:
@example @lisp
(define (environment->alist env) (define (environment->alist env)
(environment-fold env (environment-fold env
(lambda (sym val tail) (lambda (sym val tail)
(cons (cons sym val) tail)) (cons (cons sym val) tail))
'())) '()))
@end example @end lisp
@end deffn @end deffn
@deffn primitive environment-define env sym val @deffn primitive environment-define env sym val
@ -586,12 +586,11 @@ crypt(3) library call
@end deffn @end deffn
@deffn primitive mkstemp! tmpl @deffn primitive mkstemp! tmpl
mkstemp creates a new unique file in the file system and Create a new unique file in the file system and returns a new
returns a new buffered port open for reading and writing to buffered port open for reading and writing to the file.
the file. @var{tmpl} is a string specifying where the @var{tmpl} is a string specifying where the file should be
file should be created: it must end with @code{XXXXXX} created: it must end with @code{XXXXXX} and will be changed in
and will be changed in place to return the name of the place to return the name of the temporary file.
temporary file.
@end deffn @end deffn
@deffn primitive %tag-body body @deffn primitive %tag-body body

493
doc/posix.texi
View file

@ -152,7 +152,7 @@ fdes->ports.
@c docstring begin (texi-doc-string "guile" "port-revealed") @c docstring begin (texi-doc-string "guile" "port-revealed")
@deffn primitive port-revealed port @deffn primitive port-revealed port
Returns the revealed count for @var{port}. Return the revealed count for @var{port}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "set-port-revealed!") @c docstring begin (texi-doc-string "guile" "set-port-revealed!")
@ -163,8 +163,8 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "fileno") @c docstring begin (texi-doc-string "guile" "fileno")
@deffn primitive fileno port @deffn primitive fileno port
Returns the integer file descriptor underlying @var{port}. Return the integer file descriptor underlying @var{port}. Does
Does not change its revealed count. not change its revealed count.
@end deffn @end deffn
@deffn procedure port->fdes port @deffn procedure port->fdes port
@ -174,16 +174,17 @@ side effect the revealed count of @var{port} is incremented.
@c docstring begin (texi-doc-string "guile" "fdopen") @c docstring begin (texi-doc-string "guile" "fdopen")
@deffn primitive fdopen fdes modes @deffn primitive fdopen fdes modes
Returns a new port based on the file descriptor @var{fdes}. Return a new port based on the file descriptor @var{fdes}.
Modes are given by the string @var{modes}. The revealed count of the port Modes are given by the string @var{modes}. The revealed count
is initialized to zero. The modes string is the same as that accepted of the port is initialized to zero. The modes string is the
by @ref{File Ports, open-file}. same as that accepted by @ref{File Ports, open-file}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "fdes->ports") @c docstring begin (texi-doc-string "guile" "fdes->ports")
@deffn primitive fdes->ports fd @deffn primitive fdes->ports fd
Returns a list of existing ports which have @var{fdes} as an Return a list of existing ports which have @var{fdes} as an
underlying file descriptor, without changing their revealed counts. underlying file descriptor, without changing their revealed
counts.
@end deffn @end deffn
@deffn procedure fdes->inport fdes @deffn procedure fdes->inport fdes
@ -261,8 +262,8 @@ for additional flags.
@c docstring begin (texi-doc-string "guile" "open-fdes") @c docstring begin (texi-doc-string "guile" "open-fdes")
@deffn primitive open-fdes path flags [mode] @deffn primitive open-fdes path flags [mode]
Similar to @code{open} but returns a file descriptor instead of a Similar to @code{open} but return a file descriptor instead of
port. a port.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "close") @c docstring begin (texi-doc-string "guile" "close")
@ -300,19 +301,18 @@ unread characters will be read again in last-in first-out order. If
@c docstring begin (texi-doc-string "guile" "pipe") @c docstring begin (texi-doc-string "guile" "pipe")
@deffn primitive pipe @deffn primitive pipe
Returns a newly created pipe: a pair of ports which are linked Return a newly created pipe: a pair of ports which are linked
together on the local machine. The CAR is the input port and together on the local machine. The @emph{car} is the input
the CDR is the output port. Data written (and flushed) to the port and the @emph{cdr} is the output port. Data written (and
output port can be read from the input port. flushed) to the output port can be read from the input port.
Pipes are commonly used for communication with a newly Pipes are commonly used for communication with a newly forked
forked child process. The need to flush the output port child process. The need to flush the output port can be
can be avoided by making it unbuffered using @code{setvbuf}. avoided by making it unbuffered using @code{setvbuf}.
Writes occur atomically provided the size of the data in bytes
Writes occur atomically provided the size of the data in is not greater than the value of @code{PIPE_BUF}. Note that
bytes is not greater than the value of @code{PIPE_BUF} the output port is likely to block if too much data (typically
Note that the output port is likely to block if too much data equal to @code{PIPE_BUF}) has been written but not yet read
(typically equal to @code{PIPE_BUF}) has been written but not from the input port.
yet read from the input port.
@end deffn @end deffn
The next group of procedures perform a @code{dup2} The next group of procedures perform a @code{dup2}
@ -327,7 +327,9 @@ their revealed counts set to zero.
@c docstring begin (texi-doc-string "guile" "dup->fdes") @c docstring begin (texi-doc-string "guile" "dup->fdes")
@deffn primitive dup->fdes fd_or_port [fd] @deffn primitive dup->fdes fd_or_port [fd]
Returns an integer file descriptor. Return a new integer file descriptor referring to the open file
designated by @var{fd_or_port}, which must be either an open
file port or a file descriptor.
@end deffn @end deffn
@deffn procedure dup->inport port/fd [newfd] @deffn procedure dup->inport port/fd [newfd]
@ -393,10 +395,10 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "port-mode") @c docstring begin (texi-doc-string "guile" "port-mode")
@deffn primitive port-mode port @deffn primitive port-mode port
Returns the port modes associated with the open port @var{port}. These Return the port modes associated with the open port @var{port}.
will not necessarily be identical to the modes used when the port was These will not necessarily be identical to the modes used when
opened, since modes such as "append" which are used only during the port was opened, since modes such as "append" which are
port creation are not retained. used only during port creation are not retained.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "close-all-ports-except") @c docstring begin (texi-doc-string "guile" "close-all-ports-except")
@ -506,19 +508,15 @@ contents; syncing the file system and creating special files.
@c docstring begin (texi-doc-string "guile" "access?") @c docstring begin (texi-doc-string "guile" "access?")
@deffn primitive access? path how @deffn primitive access? path how
Returns @code{#t} if @var{path} corresponds to an existing Return @code{#t} if @var{path} corresponds to an existing file
file and the current process and the current process has the type of access specified by
has the type of access specified by @var{how}, otherwise @var{how}, otherwise @code{#f}. @var{how} should be specified
@code{#f}. using the values of the variables listed below. Multiple
@var{how} should be specified values can be combined using a bitwise or, in which case
using the values of the variables listed below. Multiple values can @code{#t} will only be returned if all accesses are granted.
be combined using a bitwise or, in which case @code{#t} will only Permissions are checked using the real id of the current
be returned if all accesses are granted. process, not the effective id, although it's the effective id
which determines whether the access would actually be 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 @defvar R_OK
test for read permission. test for read permission.
@end defvar @end defvar
@ -536,25 +534,24 @@ test for existence of the file.
@findex fstat @findex fstat
@c docstring begin (texi-doc-string "guile" "stat") @c docstring begin (texi-doc-string "guile" "stat")
@deffn primitive stat object @deffn primitive stat object
Returns an object containing various information Return an object containing various information about the file
about the file determined by @var{obj}. determined by @var{obj}. @var{obj} can be a string containing
@var{obj} can be a string containing a file name or a port or integer file a file name or a port or integer file descriptor which is open
descriptor which is open on a file (in which case @code{fstat} is used on a file (in which case @code{fstat} is used as the underlying
as the underlying system call). system call).
The object returned by @code{stat} can be passed as a single
The object returned by @code{stat} can be passed as a single parameter parameter to the following procedures, all of which return
to the following procedures, all of which return integers: integers:
@table @code @table @code
@item stat:dev @item stat:dev
The device containing the file. The device containing the file.
@item stat:ino @item stat:ino
The file serial number, which distinguishes this file from all other The file serial number, which distinguishes this file from all
files on the same device. other files on the same device.
@item stat:mode @item stat:mode
The mode of the file. This includes file type information The mode of the file. This includes file type information and
and the file permission bits. See @code{stat:type} and @code{stat:perms} the file permission bits. See @code{stat:type} and
below. @code{stat:perms} below.
@item stat:nlink @item stat:nlink
The number of hard links to the file. The number of hard links to the file.
@item stat:uid @item stat:uid
@ -573,20 +570,19 @@ The last modification time for the file.
@item stat:ctime @item stat:ctime
The last modification time for the attributes of the file. The last modification time for the attributes of the file.
@item stat:blksize @item stat:blksize
The optimal block size for reading or writing the file, in bytes. The optimal block size for reading or writing the file, in
bytes.
@item stat:blocks @item stat:blocks
The amount of disk space that the file occupies measured in units of The amount of disk space that the file occupies measured in
512 byte blocks. units of 512 byte blocks.
@end table @end table
In addition, the following procedures return the information In addition, the following procedures return the information
from stat:mode in a more convenient form: from stat:mode in a more convenient form:
@table @code @table @code
@item stat:type @item stat:type
A symbol representing the type of file. Possible values are A symbol representing the type of file. Possible values are
regular, directory, symlink, block-special, char-special, regular, directory, symlink, block-special, char-special, fifo,
fifo, socket and unknown socket and unknown
@item stat:perms @item stat:perms
An integer representing the access permission bits. An integer representing the access permission bits.
@end table @end table
@ -601,9 +597,8 @@ file it points to. @var{path} must be a string.
@c docstring begin (texi-doc-string "guile" "readlink") @c docstring begin (texi-doc-string "guile" "readlink")
@deffn primitive readlink path @deffn primitive readlink path
Returns the value of the symbolic link named by Return the value of the symbolic link named by @var{path} (a
@var{path} (a string), i.e., the string), i.e., the file that the link points to.
file that the link points to.
@end deffn @end deffn
@findex fchown @findex fchown
@ -638,21 +633,16 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "utime") @c docstring begin (texi-doc-string "guile" "utime")
@deffn primitive utime pathname [actime [modtime]] @deffn primitive utime pathname [actime [modtime]]
@code{utime} sets the access and modification times for @code{utime} sets the access and modification times for the
the file named by @var{path}. If @var{actime} or @var{modtime} file named by @var{path}. If @var{actime} or @var{modtime} is
is not supplied, then the current time is used. not supplied, then the current time is used. @var{actime} and
@var{actime} and @var{modtime} @var{modtime} must be integer time values as returned by the
must be integer time values as returned by the @code{current-time} @code{current-time} procedure.
procedure. @lisp
E.g.,
@smalllisp
(utime "foo" (- (current-time) 3600)) (utime "foo" (- (current-time) 3600))
@end smalllisp @end lisp
will set the access time to one hour in the past and the
will set the access time to one hour in the past and the modification modification time to the current time.
time to the current time.
@end deffn @end deffn
@findex unlink @findex unlink
@ -710,8 +700,8 @@ stream.
@c docstring begin (texi-doc-string "guile" "directory-stream?") @c docstring begin (texi-doc-string "guile" "directory-stream?")
@deffn primitive directory-stream? obj @deffn primitive directory-stream? obj
Returns a boolean indicating whether @var{object} is a directory stream Return a boolean indicating whether @var{object} is a directory
as returned by @code{opendir}. stream as returned by @code{opendir}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "readdir") @c docstring begin (texi-doc-string "guile" "readdir")
@ -751,20 +741,20 @@ to. Its exact interpretation depends on the kind of special file
being created. being created.
E.g., E.g.,
@example @lisp
(mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2)) (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
@end example @end lisp
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "tmpnam") @c docstring begin (texi-doc-string "guile" "tmpnam")
@deffn primitive tmpnam @deffn primitive tmpnam
tmpnam returns a name in the file system that does not match Return a name in the file system that does not match any
any existing file. However there is no guarantee that existing file. However there is no guarantee that another
another process will not create the file after tmpnam process will not create the file after @code{tmpnam} is called.
is called. Care should be taken if opening the file, Care should be taken if opening the file, e.g., use the
e.g., use the O_EXCL open flag or use @code{mkstemp!} instead. @code{O_EXCL} open flag or use @code{mkstemp!} instead.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "dirname") @c docstring begin (texi-doc-string "guile" "dirname")
@ -904,15 +894,16 @@ or getgrent respectively.
@c docstring begin (texi-doc-string "guile" "current-time") @c docstring begin (texi-doc-string "guile" "current-time")
@deffn primitive current-time @deffn primitive current-time
Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding Return the number of seconds since 1970-01-01 00:00:00 UTC,
leap seconds. excluding leap seconds.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "gettimeofday") @c docstring begin (texi-doc-string "guile" "gettimeofday")
@deffn primitive gettimeofday @deffn primitive gettimeofday
Returns a pair containing the number of seconds and microseconds since Return a pair containing the number of seconds and microseconds
1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:
microsecond resolution is available depends on the operating system. whether true microsecond resolution is available depends on the
operating system.
@end deffn @end deffn
The following procedures either accept an object representing a broken down The following procedures either accept an object representing a broken down
@ -948,18 +939,18 @@ Time zone label (a string), not necessarily unique.
@c docstring begin (texi-doc-string "guile" "localtime") @c docstring begin (texi-doc-string "guile" "localtime")
@deffn primitive localtime time [zone] @deffn primitive localtime time [zone]
Returns an object representing the broken down components of @var{time}, Return an object representing the broken down components of
an integer like the one returned by @code{current-time}. The time zone @var{time}, an integer like the one returned by
for the calculation is optionally specified by @var{zone} (a string), @code{current-time}. The time zone for the calculation is
otherwise the @code{TZ} environment variable or the system default is optionally specified by @var{zone} (a string), otherwise the
used. @code{TZ} environment variable or the system default is used.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "gmtime") @c docstring begin (texi-doc-string "guile" "gmtime")
@deffn primitive gmtime time @deffn primitive gmtime time
Returns an object representing the broken down components of @var{time}, Return an object representing the broken down components of
an integer like the one returned by @code{current-time}. The values @var{time}, an integer like the one returned by
are calculated for UTC. @code{current-time}. The values are calculated for UTC.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "mktime") @c docstring begin (texi-doc-string "guile" "mktime")
@ -1014,10 +1005,9 @@ reported by the following procedures.
@c docstring begin (texi-doc-string "guile" "times") @c docstring begin (texi-doc-string "guile" "times")
@deffn primitive times @deffn primitive times
Returns an object with information about real and processor time. Return an object with information about real and processor
The following procedures accept such an object as an argument and time. The following procedures accept such an object as an
return a selected component: argument and return a selected component:
@table @code @table @code
@item tms:clock @item tms:clock
The current real time, expressed as time units relative to an The current real time, expressed as time units relative to an
@ -1025,10 +1015,12 @@ arbitrary base.
@item tms:utime @item tms:utime
The CPU time units used by the calling process. The CPU time units used by the calling process.
@item tms:stime @item tms:stime
The CPU time units used by the system on behalf of the calling process. The CPU time units used by the system on behalf of the calling
process.
@item tms:cutime @item tms:cutime
The CPU time units used by terminated child processes of the calling The CPU time units used by terminated child processes of the
process, whose status has been collected (e.g., using @code{waitpid}). calling process, whose status has been collected (e.g., using
@code{waitpid}).
@item tms:cstime @item tms:cstime
Similarly, the CPU times units used by the system on behalf of Similarly, the CPU times units used by the system on behalf of
terminated child processes. terminated child processes.
@ -1037,13 +1029,15 @@ terminated child processes.
@c docstring begin (texi-doc-string "guile" "get-internal-real-time") @c docstring begin (texi-doc-string "guile" "get-internal-real-time")
@deffn primitive get-internal-real-time @deffn primitive get-internal-real-time
Returns the number of time units since the interpreter was started. Return the number of time units since the interpreter was
started.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "get-internal-run-time") @c docstring begin (texi-doc-string "guile" "get-internal-run-time")
@deffn primitive get-internal-run-time @deffn primitive get-internal-run-time
Returns the number of time units of processor time used by the interpreter. Return the number of time units of processor time used by the
Both "system" and "user" time are included but subprocesses are not. interpreter. Both @emph{system} and @emph{user} time are
included but subprocesses are not.
@end deffn @end deffn
@node Runtime Environment @node Runtime Environment
@ -1080,12 +1074,13 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "environ") @c docstring begin (texi-doc-string "guile" "environ")
@deffn primitive environ [env] @deffn primitive environ [env]
If @var{env} is omitted, returns the current environment as a list of strings. If @var{env} is omitted, return the current environment (in the
Otherwise it sets the current environment, which is also the Unix sense) as a list of strings. Otherwise set the current
default environment for child processes, to the supplied list of strings. environment, which is also the default environment for child
Each member of @var{env} should be of the form processes, to the supplied list of strings. Each member of
@code{NAME=VALUE} and values of @code{NAME} should not be duplicated. @var{env} should be of the form @code{NAME=VALUE} and values of
If @var{env} is supplied then the return value is unspecified. @code{NAME} should not be duplicated. If @var{env} is supplied
then the return value is unspecified.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "putenv") @c docstring begin (texi-doc-string "guile" "putenv")
@ -1117,7 +1112,7 @@ The return value is unspecified.
@findex pwd @findex pwd
@c docstring begin (texi-doc-string "guile" "getcwd") @c docstring begin (texi-doc-string "guile" "getcwd")
@deffn primitive getcwd @deffn primitive getcwd
Returns the name of the current working directory. Return the name of the current working directory.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "umask") @c docstring begin (texi-doc-string "guile" "umask")
@ -1131,43 +1126,45 @@ E.g., @code{(umask #o022)} sets the mask to octal 22, decimal 18.
@c docstring begin (texi-doc-string "guile" "getpid") @c docstring begin (texi-doc-string "guile" "getpid")
@deffn primitive getpid @deffn primitive getpid
Returns an integer representing the current process ID. Return an integer representing the current process ID.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "getgroups") @c docstring begin (texi-doc-string "guile" "getgroups")
@deffn primitive getgroups @deffn primitive getgroups
Returns a vector of integers representing the current supplimentary group IDs. Return a vector of integers representing the current
supplimentary group IDs.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "getppid") @c docstring begin (texi-doc-string "guile" "getppid")
@deffn primitive getppid @deffn primitive getppid
Returns an integer representing the process ID of the parent process. Return an integer representing the process ID of the parent
process.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "getuid") @c docstring begin (texi-doc-string "guile" "getuid")
@deffn primitive getuid @deffn primitive getuid
Returns an integer representing the current real user ID. Return an integer representing the current real user ID.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "getgid") @c docstring begin (texi-doc-string "guile" "getgid")
@deffn primitive getgid @deffn primitive getgid
Returns an integer representing the current real group ID. Return an integer representing the current real group ID.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "geteuid") @c docstring begin (texi-doc-string "guile" "geteuid")
@deffn primitive geteuid @deffn primitive geteuid
Returns an integer representing the current effective user ID. Return an integer representing the current effective user ID.
If the system does not support effective IDs, then the real ID If the system does not support effective IDs, then the real ID
is returned. @code{(feature? 'EIDs)} reports whether the system is returned. @code{(feature? 'EIDs)} reports whether the
supports effective IDs. system supports effective IDs.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "getegid") @c docstring begin (texi-doc-string "guile" "getegid")
@deffn primitive getegid @deffn primitive getegid
Returns an integer representing the current effective group ID. Return an integer representing the current effective group ID.
If the system does not support effective IDs, then the real ID If the system does not support effective IDs, then the real ID
is returned. @code{(feature? 'EIDs)} reports whether the system is returned. @code{(feature? 'EIDs)} reports whether the
supports effective IDs. system supports effective IDs.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "setuid") @c docstring begin (texi-doc-string "guile" "setuid")
@ -1204,7 +1201,7 @@ The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "getpgrp") @c docstring begin (texi-doc-string "guile" "getpgrp")
@deffn primitive getpgrp @deffn primitive getpgrp
Returns an integer representing the current process group ID. Return an integer representing the current process group ID.
This is the POSIX definition, not BSD. This is the POSIX definition, not BSD.
@end deffn @end deffn
@ -1276,31 +1273,31 @@ by @code{waitpid}.
@c docstring begin (texi-doc-string "guile" "status:exit-val") @c docstring begin (texi-doc-string "guile" "status:exit-val")
@deffn primitive status:exit-val status @deffn primitive status:exit-val status
Returns the exit status value, as would be Return the exit status value, as would be set if a process
set if a process ended normally through a ended normally through a call to @code{exit} or @code{_exit},
call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}. if any, otherwise @code{#f}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "status:term-sig") @c docstring begin (texi-doc-string "guile" "status:term-sig")
@deffn primitive status:term-sig status @deffn primitive status:term-sig status
Returns the signal number which terminated the Return the signal number which terminated the process, if any,
process, if any, otherwise @code{#f}. otherwise @code{#f}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "status:stop-sig") @c docstring begin (texi-doc-string "guile" "status:stop-sig")
@deffn primitive status:stop-sig status @deffn primitive status:stop-sig status
Returns the signal number which stopped the Return the signal number which stopped the process, if any,
process, if any, otherwise @code{#f}. otherwise @code{#f}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "system") @c docstring begin (texi-doc-string "guile" "system")
@deffn primitive system [cmd] @deffn primitive system [cmd]
Executes @var{cmd} using the operating system's "command processor". Execute @var{cmd} using the operating system's "command
Under Unix this is usually the default shell @code{sh}. The value processor". Under Unix this is usually the default shell
returned is @var{cmd}'s exit status as returned by @code{waitpid}, which @code{sh}. The value returned is @var{cmd}'s exit status as
can be interpreted using the functions above. returned by @code{waitpid}, which can be interpreted using the
functions above.
If @code{system} is called without arguments, it returns a boolean If @code{system} is called without arguments, return a boolean
indicating whether the command processor is available. indicating whether the command processor is available.
@end deffn @end deffn
@ -1480,28 +1477,27 @@ all platforms.
@c docstring begin (texi-doc-string "guile" "isatty?") @c docstring begin (texi-doc-string "guile" "isatty?")
@deffn primitive isatty? port @deffn primitive isatty? port
Returns @code{#t} if @var{port} is using a serial Return @code{#t} if @var{port} is using a serial non--file
non-file device, otherwise @code{#f}. device, otherwise @code{#f}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "ttyname") @c docstring begin (texi-doc-string "guile" "ttyname")
@deffn primitive ttyname port @deffn primitive ttyname port
Returns a string with the name of the serial terminal device underlying Return a string with the name of the serial terminal device
@var{port}. underlying @var{port}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "ctermid") @c docstring begin (texi-doc-string "guile" "ctermid")
@deffn primitive ctermid @deffn primitive ctermid
Returns a string containing the file name of the controlling terminal Return a string containing the file name of the controlling
for the current process. terminal for the current process.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "tcgetpgrp") @c docstring begin (texi-doc-string "guile" "tcgetpgrp")
@deffn primitive tcgetpgrp port @deffn primitive tcgetpgrp port
Returns the process group ID of the foreground Return the process group ID of the foreground process group
process group associated with the terminal open on the file descriptor associated with the terminal open on the file descriptor
underlying @var{port}. underlying @var{port}.
If there is no foreground process group, the return value is a If there is no foreground process group, the return value is a
number greater than 1 that does not match the process group ID number greater than 1 that does not match the process group ID
of any existing process group. This can happen if all of the of any existing process group. This can happen if all of the
@ -1575,52 +1571,48 @@ the database routines since they are not reentrant.
@c docstring begin (texi-doc-string "guile" "inet-aton") @c docstring begin (texi-doc-string "guile" "inet-aton")
@deffn primitive inet-aton address @deffn primitive inet-aton address
Converts a string containing an Internet host address in the traditional Converts a string containing an Internet host address in the
dotted decimal notation into an integer. traditional dotted decimal notation into an integer.
@lisp
@smalllisp
(inet-aton "127.0.0.1") @result{} 2130706433 (inet-aton "127.0.0.1") @result{} 2130706433
@end lisp
@end smalllisp
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "inet-ntoa") @c docstring begin (texi-doc-string "guile" "inet-ntoa")
@deffn primitive inet-ntoa inetid @deffn primitive inet-ntoa inetid
Converts an integer Internet host address into a string with the Converts an integer Internet host address into a string with
traditional dotted decimal representation. the traditional dotted decimal representation.
@lisp
@smalllisp
(inet-ntoa 2130706433) @result{} "127.0.0.1" (inet-ntoa 2130706433) @result{} "127.0.0.1"
@end smalllisp @end lisp
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "inet-netof") @c docstring begin (texi-doc-string "guile" "inet-netof")
@deffn primitive inet-netof address @deffn primitive inet-netof address
Returns the network number part of the given integer Internet address. Return the network number part of the given integer Internet
address.
@smalllisp @lisp
(inet-netof 2130706433) @result{} 127 (inet-netof 2130706433) @result{} 127
@end smalllisp @end lisp
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "inet-lnaof") @c docstring begin (texi-doc-string "guile" "inet-lnaof")
@deffn primitive inet-lnaof address @deffn primitive inet-lnaof address
Returns the local-address-with-network part of the given Internet Return the local-address-with-network part of the given
address. Internet address.
@lisp
@smalllisp
(inet-lnaof 2130706433) @result{} 1 (inet-lnaof 2130706433) @result{} 1
@end smalllisp @end lisp
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "inet-makeaddr") @c docstring begin (texi-doc-string "guile" "inet-makeaddr")
@deffn primitive inet-makeaddr net lna @deffn primitive inet-makeaddr net lna
Makes an Internet host address by combining the network number @var{net} Makes an Internet host address by combining the network number
with the local-address-within-network number @var{lna}. @var{net} with the local-address-within-network number
@var{lna}.
@smalllisp @lisp
(inet-makeaddr 127 1) @result{} 2130706433 (inet-makeaddr 127 1) @result{} 2130706433
@end smalllisp @end lisp
@end deffn @end deffn
@subsubsection The Host Database @subsubsection The Host Database
@ -1881,40 +1873,38 @@ required. The arguments and return values are thus in host order.
@c docstring begin (texi-doc-string "guile" "socket") @c docstring begin (texi-doc-string "guile" "socket")
@deffn primitive socket family style proto @deffn primitive socket family style proto
Returns a new socket port of the type specified by @var{family}, @var{style} Return a new socket port of the type specified by @var{family},
and @var{protocol}. All three parameters are integers. Typical values @var{style} and @var{protocol}. All three parameters are
for @var{family} are the values of @code{AF_UNIX} integers. Typical values for @var{family} are the values of
and @code{AF_INET}. Typical values for @var{style} are @code{AF_UNIX} and @code{AF_INET}. Typical values for
the values of @code{SOCK_STREAM}, @code{SOCK_DGRAM} and @code{SOCK_RAW}. @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 @var{protocol} can be obtained from a protocol name using
@code{getprotobyname}. A value of @code{getprotobyname}. A value of zero specifies the default
zero specifies the default protocol, which is usually right. protocol, which is usually right.
A single socket port cannot by used for communication until it
A single socket port cannot by used for communication until has been connected to another socket.
it has been connected to another socket.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "socketpair") @c docstring begin (texi-doc-string "guile" "socketpair")
@deffn primitive socketpair family style proto @deffn primitive socketpair family style proto
Returns a pair of connected (but unnamed) socket ports of the type specified Return a pair of connected (but unnamed) socket ports of the
by @var{family}, @var{style} and @var{protocol}. type specified by @var{family}, @var{style} and @var{protocol}.
Many systems support only Many systems support only socket pairs of the @code{AF_UNIX}
socket pairs of the @code{AF_UNIX} family. Zero is likely to be family. Zero is likely to be the only meaningful value for
the only meaningful value for @var{protocol}. @var{protocol}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "getsockopt") @c docstring begin (texi-doc-string "guile" "getsockopt")
@deffn primitive getsockopt sock level optname @deffn primitive getsockopt sock level optname
Returns the value of a particular socket option for the socket Return the value of a particular socket option for the socket
port @var{socket}. @var{level} is an integer code for type of option port @var{socket}. @var{level} is an integer code for type of
being requested, e.g., @code{SOL_SOCKET} for socket-level options. option being requested, e.g., @code{SOL_SOCKET} for
@var{optname} is an socket-level options. @var{optname} is an integer code for the
integer code for the option required and should be specified using one of option required and should be specified using one of the
the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc. symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
The returned value is typically an integer but @code{SO_LINGER}
The returned value is typically an integer but @code{SO_LINGER} returns a returns a pair of integers.
pair of integers.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "setsockopt") @c docstring begin (texi-doc-string "guile" "setsockopt")
@ -2060,17 +2050,17 @@ number.
@c docstring begin (texi-doc-string "guile" "getsockname") @c docstring begin (texi-doc-string "guile" "getsockname")
@deffn primitive getsockname sock @deffn primitive getsockname sock
Returns the address of @var{socket}, in the same form as the object Return the address of @var{socket}, in the same form as the
returned by @code{accept}. On many systems the address of a socket object returned by @code{accept}. On many systems the address
in the @code{AF_FILE} namespace cannot be read. of a socket in the @code{AF_FILE} namespace cannot be read.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "getpeername") @c docstring begin (texi-doc-string "guile" "getpeername")
@deffn primitive getpeername sock @deffn primitive getpeername sock
Returns the address of the socket that the socket @var{socket} is connected to, Return the address of the socket that the socket @var{socket}
in the same form as the object is connected to, in the same form as the object returned by
returned by @code{accept}. On many systems the address of a socket @code{accept}. On many systems the address of a socket in the
in the @code{AF_FILE} namespace cannot be read. @code{AF_FILE} namespace cannot be read.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "recv!") @c docstring begin (texi-doc-string "guile" "recv!")
@ -2107,27 +2097,23 @@ any unflushed buffered port data is ignored.
@c docstring begin (texi-doc-string "guile" "recvfrom!") @c docstring begin (texi-doc-string "guile" "recvfrom!")
@deffn primitive recvfrom! sock str [flags [start [end]]] @deffn primitive recvfrom! sock str [flags [start [end]]]
Returns data from the socket port @var{socket} and also information about Return data from the socket port @var{socket} and also
where the data was received from. @var{socket} must already information about where the data was received from.
be bound to the address from which data is to be received. @var{socket} must already be bound to the address from which
@code{str}, is a string into which data is to be received. @code{str}, is a string into which the
the data will be written. The size of @var{str} limits the amount of data will be written. The size of @var{str} limits the amount
data which can be received: in the case of packet of data which can be received: in the case of packet protocols,
protocols, if a packet larger than this limit is encountered then some data if a packet larger than this limit is encountered then some
will be irrevocably lost. data will be irrevocably lost.
The optional @var{flags} argument is a value or bitwise OR of
The optional @var{flags} argument is a value or @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. The value returned is a pair: the @emph{car} is the number of
bytes read from the socket and the @emph{cdr} an address object
The value returned is a pair: the CAR is the number of bytes read from in the same form as returned by @code{accept}.
the socket and the CDR an address object in the same form as returned by The @var{start} and @var{end} arguments specify a substring of
@code{accept}. @var{str} to which the data should be written.
Note that the data is read directly from the socket file
The @var{start} and @var{end} arguments specify a substring of @var{str} descriptor: any unread buffered port data is ignored.
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 @end deffn
@c docstring begin (texi-doc-string "guile" "sendto") @c docstring begin (texi-doc-string "guile" "sendto")
@ -2152,30 +2138,30 @@ be done when sending or receiving encoded integer data from the network.
@c docstring begin (texi-doc-string "guile" "htons") @c docstring begin (texi-doc-string "guile" "htons")
@deffn primitive htons in @deffn primitive htons in
Returns a new integer from @var{value} by converting from host to Return a new integer from @var{value} by converting from host
network order. @var{value} must be within the range of a C unsigned to network order. @var{value} must be within the range of a C
short integer. unsigned short integer.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "ntohs") @c docstring begin (texi-doc-string "guile" "ntohs")
@deffn primitive ntohs in @deffn primitive ntohs in
Returns a new integer from @var{value} by converting from network to Return a new integer from @var{value} by converting from
host order. @var{value} must be within the range of a C unsigned short network to host order. @var{value} must be within the range of
integer. a C unsigned short integer.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "htonl") @c docstring begin (texi-doc-string "guile" "htonl")
@deffn primitive htonl in @deffn primitive htonl in
Returns a new integer from @var{value} by converting from host to Return a new integer from @var{value} by converting from host
network order. @var{value} must be within the range of a C unsigned to network order. @var{value} must be within the range of a C
long integer. unsigned long integer.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "ntohl") @c docstring begin (texi-doc-string "guile" "ntohl")
@deffn primitive ntohl in @deffn primitive ntohl in
Returns a new integer from @var{value} by converting from network to Return a new integer from @var{value} by converting from
host order. @var{value} must be within the range of a C unsigned network to host order. @var{value} must be within the range of
long integer. a C unsigned long integer.
@end deffn @end deffn
These procedures are inconvenient to use at present, but consider: These procedures are inconvenient to use at present, but consider:
@ -2199,8 +2185,8 @@ These procedures are inconvenient to use at present, but consider:
@c docstring begin (texi-doc-string "guile" "uname") @c docstring begin (texi-doc-string "guile" "uname")
@deffn primitive uname @deffn primitive uname
Returns an object with some information about the computer system the Return an object with some information about the computer
program is running on. system the program is running on.
@end deffn @end deffn
The following procedures accept an object as returned by @code{uname} The following procedures accept an object as returned by @code{uname}
@ -2237,13 +2223,12 @@ no other easy or unambiguous way of detecting such features.
@c docstring begin (texi-doc-string "guile" "setlocale") @c docstring begin (texi-doc-string "guile" "setlocale")
@deffn primitive setlocale category [locale] @deffn primitive setlocale category [locale]
If @var{locale} is omitted, returns the current value of the specified If @var{locale} is omitted, return the current value of the
locale category as a system-dependent string. specified locale category as a system-dependent string.
@var{category} should be specified using the values @code{LC_COLLATE}, @var{category} should be specified using the values
@code{LC_ALL} etc. @code{LC_COLLATE}, @code{LC_ALL} etc.
Otherwise the specified locale category is set to the string
Otherwise the specified locale category is set to @var{locale} and the new value is returned as a
the string @var{locale} system-dependent string. If @var{locale} is an empty string,
and the new value is returned as a system-dependent string. If @var{locale} the locale will be set using envirionment variables.
is an empty string, the locale will be set using envirionment variables.
@end deffn @end deffn

96
doc/scheme-control.texi
View file

@ -88,28 +88,22 @@ Instead of using @code{call-with-current-continuation}, the exception
primitives documented here are implemented as built-ins that take primitives documented here are implemented as built-ins that take
advantage of the @emph{upward only} nature of exceptions. advantage of the @emph{upward only} nature of exceptions.
@c ARGFIXME tag/key
@c docstring begin (texi-doc-string "guile" "catch") @c docstring begin (texi-doc-string "guile" "catch")
@deffn primitive catch tag thunk handler @deffn primitive catch key thunk handler
Invoke @var{thunk} in the dynamic context of @var{handler} for Invoke @var{thunk} in the dynamic context of @var{handler} for
exceptions matching @var{key}. If thunk throws to the symbol @var{key}, exceptions matching @var{key}. If thunk throws to the symbol
then @var{handler} is invoked this way: @var{key}, then @var{handler} is invoked this way:
@lisp
@example
(handler key args ...) (handler key args ...)
@end example @end lisp
@var{key} is a symbol or @code{#t}.
@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}.
@var{thunk} takes no arguments. If @var{thunk} returns normally, that Handler is invoked outside the scope of its own @code{catch}.
is the return value of @code{catch}. If @var{handler} again throws to the same key, a new handler
from further up the call chain is invoked.
Handler is invoked outside the scope of its own @code{catch}. If If the key is @code{#t}, then a throw to @emph{any} symbol will
@var{handler} again throws to the same key, a new handler from further match this call to @code{catch}.
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 @end deffn
@c docstring begin (texi-doc-string "guile" "throw") @c docstring begin (texi-doc-string "guile" "throw")
@ -124,7 +118,7 @@ If there is no handler at all, an error is signaled.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "lazy-catch") @c docstring begin (texi-doc-string "guile" "lazy-catch")
@deffn primitive lazy-catch tag thunk handler @deffn primitive lazy-catch key thunk handler
This behaves exactly like @code{catch}, except that it does This behaves exactly like @code{catch}, except that it does
not unwind the stack (this is the major difference), and if not unwind the stack (this is the major difference), and if
handler returns, its value is returned from the throw. handler returns, its value is returned from the throw.
@ -145,25 +139,27 @@ displaying @var{msg} and writing @var{args}.
@end deffn @end deffn
@c end @c end
@c ARGFIXME rest/data
@c docstring begin (texi-doc-string "guile" "scm-error") @c docstring begin (texi-doc-string "guile" "scm-error")
@deffn primitive scm-error key subr message args rest @deffn primitive scm-error key subr message args data
Raise an error with key @var{key}. @var{subr} can be a string naming Raise an error with key @var{key}. @var{subr} can be a string
the procedure associated with the error, or @code{#f}. @var{message} naming the procedure associated with the error, or @code{#f}.
is the error message string, possibly containing @code{~S} and @code{~A} @var{message} is the error message string, possibly containing
escapes. When an error is reported, these are replaced by formating the @code{~S} and @code{~A} escapes. When an error is reported,
corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display} these are replaced by formatting the corresponding members of
and @code{~S} (was @code{%S}) formats using @code{write}. @var{data} is a @var{args}: @code{~A} (was @code{%s} in older versions of
list or @code{#f} depending on @var{key}: if @var{key} is Guile) formats using @code{display} and @code{~S} (was
@code{system-error} then it should be a list @code{%S}) formats using @code{write}. @var{data} is a list or
containing the Unix @code{errno} value; If @var{key} is @code{signal} then @code{#f} depending on @var{key}: if @var{key} is
it should be a list containing the Unix signal number; otherwise it @code{system-error} then it should be a list containing the
will usually be @code{#f}. 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 @end deffn
@c docstring begin (texi-doc-string "guile" "strerror") @c docstring begin (texi-doc-string "guile" "strerror")
@deffn primitive strerror err @deffn primitive strerror err
Returns the Unix error message corresponding to @var{err}, an integer. Return the Unix error message corresponding to @var{err}, which
must be an integer value.
@end deffn @end deffn
@c begin (scm-doc-string "boot-9.scm" "false-if-exception") @c begin (scm-doc-string "boot-9.scm" "false-if-exception")
@ -181,23 +177,20 @@ if an exception occurs then @code{#f} is returned instead.
be reviewed] be reviewed]
@r5index dynamic-wind @r5index dynamic-wind
@c ARGFIXME in-guard/thunk1 thunk/thunk2 out-guard/thunk3
@c docstring begin (texi-doc-string "guile" "dynamic-wind") @c docstring begin (texi-doc-string "guile" "dynamic-wind")
@deffn primitive dynamic-wind thunk1 thunk2 thunk3 @deffn primitive dynamic-wind in_guard thunk out_guard
All three arguments must be 0-argument procedures. All three arguments must be 0-argument procedures.
@var{in_guard} is called, then @var{thunk}, then
@var{in-guard} is called, then @var{thunk}, then @var{out-guard}. @var{out_guard}.
If, any time during the execution of @var{thunk}, the
If, any time during the execution of @var{thunk}, the continuation continuation of the @code{dynamic_wind} expression is escaped
of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard} non-locally, @var{out_guard} is called. If the continuation of
is called. If the continuation of the dynamic-wind is re-entered, the dynamic-wind is re-entered, @var{in_guard} is called. Thus
@var{in-guard} is called. Thus @var{in-guard} and @var{out-guard} may @var{in_guard} and @var{out_guard} may be called any number of
be called any number of times. times.
@lisp
@example
(define x 'normal-binding) (define x 'normal-binding)
@result{} x @result{} x
(define a-cont (call-with-current-continuation (define a-cont (call-with-current-continuation
(lambda (escape) (lambda (escape)
(let ((old-x x)) (let ((old-x x))
@ -205,38 +198,31 @@ be called any number of times.
;; in-guard: ;; in-guard:
;; ;;
(lambda () (set! x 'special-binding)) (lambda () (set! x 'special-binding))
;; thunk ;; thunk
;; ;;
(lambda () (display x) (newline) (lambda () (display x) (newline)
(call-with-current-continuation escape) (call-with-current-continuation escape)
(display x) (newline) (display x) (newline)
x) x)
;; out-guard: ;; out-guard:
;; ;;
(lambda () (set! x old-x))))))) (lambda () (set! x old-x)))))))
;; Prints: ;; Prints:
special-binding special-binding
;; Evaluates to: ;; Evaluates to:
@result{} a-cont @result{} a-cont
x x
@result{} normal-binding @result{} normal-binding
(a-cont #f) (a-cont #f)
;; Prints: ;; Prints:
special-binding special-binding
;; Evaluates to: ;; Evaluates to:
@result{} a-cont ;; the value of the (define a-cont...) @result{} a-cont ;; the value of the (define a-cont...)
x x
@result{} normal-binding @result{} normal-binding
a-cont a-cont
@result{} special-binding @result{} special-binding
@end example @end lisp
@end deffn @end deffn
@c Local Variables: @c Local Variables:
@c TeX-master: "guile.texi" @c TeX-master: "guile.texi"

739
doc/scheme-data.texi
View file

File diff suppressed because it is too large Load diff

14
doc/scheme-evaluation.texi
View file

@ -123,11 +123,11 @@ environment given by @var{environment specifier}.
@r5index interaction-environment @r5index interaction-environment
@c docstring begin (texi-doc-string "guile" "interaction-environment") @c docstring begin (texi-doc-string "guile" "interaction-environment")
@deffn primitive interaction-environment @deffn primitive interaction-environment
This procedure returns a specifier for the environment that contains Return a specifier for the environment that contains
implementation-defined bindings, typically a superset of those listed in implementation--defined bindings, typically a superset of those
the report. The intent is that this procedure will return the listed in the report. The intent is that this procedure will
environment in which the implementation would evaluate expressions return the environment in which the implementation would
dynamically typed by the user. evaluate expressions dynamically typed by the user.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "eval-string") @c docstring begin (texi-doc-string "guile" "eval-string")
@ -189,7 +189,6 @@ any code is loaded. See documentation for @code{%load-hook} later in
this section. this section.
@end deffn @end deffn
@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "primitive-load") @c docstring begin (texi-doc-string "guile" "primitive-load")
@deffn primitive primitive-load filename @deffn primitive primitive-load filename
Load the file named @var{filename} and evaluate its contents in Load the file named @var{filename} and evaluate its contents in
@ -201,7 +200,6 @@ that will be called before any code is loaded. See the
documentation for @code{%load-hook} later in this section. documentation for @code{%load-hook} later in this section.
@end deffn @end deffn
@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "primitive-load-path") @c docstring begin (texi-doc-string "guile" "primitive-load-path")
@deffn primitive primitive-load-path filename @deffn primitive primitive-load-path filename
Search @var{%load-path} for the file named @var{filename} and Search @var{%load-path} for the file named @var{filename} and
@ -210,7 +208,6 @@ relative pathname and is not found in the list of search paths,
an error is signalled. an error is signalled.
@end deffn @end deffn
@c ARGFIXME file/filename
@c docstring begin (texi-doc-string "guile" "%search-load-path") @c docstring begin (texi-doc-string "guile" "%search-load-path")
@deffn primitive %search-load-path filename @deffn primitive %search-load-path filename
Search @var{%load-path} for the file named @var{filename}, Search @var{%load-path} for the file named @var{filename},
@ -257,7 +254,6 @@ list @code{("" ".scm")}.
[delay] [delay]
@c ARGFIXME x/obj
@c docstring begin (texi-doc-string "guile" "promise?") @c docstring begin (texi-doc-string "guile" "promise?")
@deffn primitive promise? obj @deffn primitive promise? obj
Return true if @var{obj} is a promise, i.e. a delayed computation Return true if @var{obj} is a promise, i.e. a delayed computation

235
doc/scheme-io.texi
View file

@ -35,7 +35,7 @@ ports} are two interesting and powerful examples of this technique.
@r5index input-port? @r5index input-port?
@c docstring begin (texi-doc-string "guile" "input-port?") @c docstring begin (texi-doc-string "guile" "input-port?")
@deffn primitive input-port? x @deffn primitive input-port? x
Returns @code{#t} if @var{x} is an input port, otherwise returns Return @code{#t} if @var{x} is an input port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies @code{#f}. Any object satisfying this predicate also satisfies
@code{port?}. @code{port?}.
@end deffn @end deffn
@ -43,14 +43,14 @@ Returns @code{#t} if @var{x} is an input port, otherwise returns
@r5index output-port? @r5index output-port?
@c docstring begin (texi-doc-string "guile" "output-port?") @c docstring begin (texi-doc-string "guile" "output-port?")
@deffn primitive output-port? x @deffn primitive output-port? x
Returns @code{#t} if @var{x} is an output port, otherwise returns Return @code{#t} if @var{x} is an output port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies @code{#f}. Any object satisfying this predicate also satisfies
@code{port?}. @code{port?}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "port?") @c docstring begin (texi-doc-string "guile" "port?")
@deffn primitive port? x @deffn primitive port? x
Returns a boolean indicating whether @var{x} is a port. Return a boolean indicating whether @var{x} is a port.
Equivalent to @code{(or (input-port? @var{x}) (output-port? Equivalent to @code{(or (input-port? @var{x}) (output-port?
@var{x}))}. @var{x}))}.
@end deffn @end deffn
@ -64,50 +64,51 @@ Equivalent to @code{(or (input-port? @var{x}) (output-port?
@r5index eof-object? @r5index eof-object?
@c docstring begin (texi-doc-string "guile" "eof-object?") @c docstring begin (texi-doc-string "guile" "eof-object?")
@deffn primitive eof-object? x @deffn primitive eof-object? x
Returns @code{#t} if @var{x} is an end-of-file object; otherwise Return @code{#t} if @var{x} is an end-of-file object; otherwise
returns @code{#f}. return @code{#f}.
@end deffn @end deffn
@r5index char-ready? @r5index char-ready?
@c docstring begin (texi-doc-string "guile" "char-ready?") @c docstring begin (texi-doc-string "guile" "char-ready?")
@deffn primitive char-ready? [port] @deffn primitive char-ready? [port]
Returns @code{#t} if a character is ready on input @var{port} and Return @code{#t} if a character is ready on input @var{port}
returns @code{#f} otherwise. If @code{char-ready?} returns @code{#t} and return @code{#f} otherwise. If @code{char-ready?} returns
then the next @code{read-char} operation on @var{port} is @code{#t} then the next @code{read-char} operation on
guaranteed not to hang. If @var{port} is a file port at end of @var{port} is guaranteed not to hang. If @var{port} is a file
file then @code{char-ready?} returns @code{#t}. port at end of file then @code{char-ready?} returns @code{#t}.
@footnote{@code{char-ready?} exists to make it possible for a @footnote{@code{char-ready?} exists to make it possible for a
program to accept characters from interactive ports without getting program to accept characters from interactive ports without
stuck waiting for input. Any input editors associated with such ports getting stuck waiting for input. Any input editors associated
must make sure that characters whose existence has been asserted by with such ports must make sure that characters whose existence
@code{char-ready?} cannot be rubbed out. If @code{char-ready?} were to has been asserted by @code{char-ready?} cannot be rubbed out.
return @code{#f} at end of file, a port at end of file would be If @code{char-ready?} were to return @code{#f} at end of file,
indistinguishable from an interactive port that has no ready a port at end of file would be indistinguishable from an
characters.} interactive port that has no ready characters.}
@end deffn @end deffn
@r5index read-char? @r5index read-char?
@c docstring begin (texi-doc-string "guile" "read-char") @c docstring begin (texi-doc-string "guile" "read-char")
@deffn primitive read-char [port] @deffn primitive read-char [port]
Returns the next character available from @var{port}, updating Return the next character available from @var{port}, updating
@var{port} to point to the following character. If no more @var{port} to point to the following character. If no more
characters are available, an end-of-file object is returned. characters are available, the end-of-file object is returned.
@end deffn @end deffn
@r5index peek-char? @r5index peek-char?
@c docstring begin (texi-doc-string "guile" "peek-char") @c docstring begin (texi-doc-string "guile" "peek-char")
@deffn primitive peek-char [port] @deffn primitive peek-char [port]
Returns the next character available from @var{port}, Return the next character available from @var{port},
@emph{without} updating @var{port} to point to the following @emph{without} updating @var{port} to point to the following
character. If no more characters are available, an end-of-file object character. If no more characters are available, the
is returned.@footnote{The value returned by a call to @code{peek-char} end-of-file object is returned.@footnote{The value returned by
is the same as the value that would have been returned by a call to a call to @code{peek-char} is the same as the value that would
@code{read-char} on the same port. The only difference is that the very have been returned by a call to @code{read-char} on the same
next call to @code{read-char} or @code{peek-char} on that port. The only difference is that the very next call to
@var{port} will return the value returned by the preceding call to @code{read-char} or @code{peek-char} on that @var{port} will
@code{peek-char}. In particular, a call to @code{peek-char} on an return the value returned by the preceding call to
interactive port will hang waiting for input whenever a call to @code{peek-char}. In particular, a call to @code{peek-char} on
@code{read-char} would have hung.} an interactive port will hang waiting for input whenever a call
to @code{read-char} would have hung.}
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "unread-char") @c docstring begin (texi-doc-string "guile" "unread-char")
@ -129,10 +130,9 @@ unread characters will be read again in last-in first-out order. If
@c docstring begin (texi-doc-string "guile" "drain-input") @c docstring begin (texi-doc-string "guile" "drain-input")
@deffn primitive drain-input port @deffn primitive drain-input port
Drain @var{port}'s read buffers (including any pushed-back Drain @var{port}'s read buffers (including any pushed-back
characters) and returns the content as a single string. characters) and return the content as a single string.
@end deffn @end deffn
@c ARGFIXME port/input-port
@c docstring begin (texi-doc-string "guile" "port-column") @c docstring begin (texi-doc-string "guile" "port-column")
@c docstring begin (texi-doc-string "guile" "port-line") @c docstring begin (texi-doc-string "guile" "port-line")
@deffn primitive port-column port @deffn primitive port-column port
@ -147,7 +147,6 @@ because lines and column numbers traditionally start with 1, and that is
what non-programmers will find most natural.) what non-programmers will find most natural.)
@end deffn @end deffn
@c ARGFIXME port/input-port
@c docstring begin (texi-doc-string "guile" "set-port-column!") @c docstring begin (texi-doc-string "guile" "set-port-column!")
@c docstring begin (texi-doc-string "guile" "set-port-line!") @c docstring begin (texi-doc-string "guile" "set-port-line!")
@deffn primitive set-port-column! port column @deffn primitive set-port-column! port column
@ -267,12 +266,12 @@ all open output ports. The return value is unspecified.
@c docstring begin (texi-doc-string "guile" "close-port") @c docstring begin (texi-doc-string "guile" "close-port")
@deffn primitive close-port port @deffn primitive close-port port
Close the specified port object. Returns @code{#t} if it successfully Close the specified port object. Return @code{#t} if it
closes a port or @code{#f} if it was already successfully closes a port or @code{#f} if it was already
closed. An exception may be raised if an error occurs, for example closed. An exception may be raised if an error occurs, for
when flushing buffered output. example when flushing buffered output. See also @ref{Ports and
See also @ref{Ports and File Descriptors, close}, for a procedure File Descriptors, close}, for a procedure which can close file
which can close file descriptors. descriptors.
@end deffn @end deffn
@r5index close-input-port @r5index close-input-port
@ -299,21 +298,21 @@ which can close file descriptors.
@c docstring begin (texi-doc-string "guile" "port-closed?") @c docstring begin (texi-doc-string "guile" "port-closed?")
@deffn primitive port-closed? port @deffn primitive port-closed? port
Returns @code{#t} if @var{port} is closed or @code{#f} if it is open. Return @code{#t} if @var{port} is closed or @code{#f} if it is
open.
@end deffn @end deffn
@node Random Access @node Random Access
@section Random Access @section Random Access
@c ARGFIXME object/fd/port
@c docstring begin (texi-doc-string "guile" "seek") @c docstring begin (texi-doc-string "guile" "seek")
@deffn primitive seek object offset whence @deffn primitive seek fd_port offset whence
Sets the current position of @var{fd/port} to the integer @var{offset}, Sets the current position of @var{fd/port} to the integer
which is interpreted according to the value of @var{whence}. @var{offset}, which is interpreted according to the value of
@var{whence}.
One of the following variables should be supplied One of the following variables should be supplied for
for @var{whence}: @var{whence}:
@defvar SEEK_SET @defvar SEEK_SET
Seek from the beginning of the file. Seek from the beginning of the file.
@end defvar @end defvar
@ -323,46 +322,40 @@ Seek from the current position.
@defvar SEEK_END @defvar SEEK_END
Seek from the end of the file. Seek from the end of the file.
@end defvar @end defvar
If @var{fd/port} is a file descriptor, the underlying system
If @var{fd/port} is a file descriptor, the underlying system call is call is @code{lseek}. @var{port} may be a string port.
@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:
The value returned is the new position in the file. This means that @lisp
the current position of a port can be obtained using:
@smalllisp
(seek port 0 SEEK_CUR) (seek port 0 SEEK_CUR)
@end smalllisp @end lisp
@end deffn @end deffn
@c ARGFIXME object/fd/port
@c docstring begin (texi-doc-string "guile" "fseek") @c docstring begin (texi-doc-string "guile" "fseek")
@deffn primitive fseek object offset whence @deffn primitive fseek fd_port offset whence
Obsolete. Almost the same as seek, above, but the return value is Obsolete. Almost the same as @code{seek}, but the return value
unspecified. is unspecified.
@end deffn @end deffn
@c ARGFIXME object/fd/port
@c docstring begin (texi-doc-string "guile" "ftell") @c docstring begin (texi-doc-string "guile" "ftell")
@deffn primitive ftell object @deffn primitive ftell fd_port
Returns an integer representing the current position of @var{fd/port}, Return an integer representing the current position of
measured from the beginning. Equivalent to: @var{fd/port}, measured from the beginning. Equivalent to:
@smalllisp @lisp
(seek port 0 SEEK_CUR) (seek port 0 SEEK_CUR)
@end smalllisp @end lisp
@end deffn @end deffn
@findex truncate @findex truncate
@findex ftruncate @findex ftruncate
@c ARGFIXME obj/object size/length
@c docstring begin (texi-doc-string "guile" "truncate-file") @c docstring begin (texi-doc-string "guile" "truncate-file")
@deffn primitive truncate-file object [length] @deffn primitive truncate-file object [length]
Truncates the object referred to by @var{obj} to at most @var{size} bytes. Truncates the object referred to by @var{object} to at most
@var{obj} can be a string containing a file name or an integer file @var{length} bytes. @var{object} can be a string containing a
descriptor or a port. @var{size} may be omitted if @var{obj} is not file name or an integer file descriptor or a port.
a file name, in which case the truncation occurs at the current port. @var{length} may be omitted if @var{object} is not a file name,
position. in which case the truncation occurs at the current port.
position. The return value is unspecified.
The return value is unspecified.
@end deffn @end deffn
@ -444,21 +437,19 @@ char-set, not a string.
@c docstring begin (texi-doc-string "guile" "write-line") @c docstring begin (texi-doc-string "guile" "write-line")
@deffn primitive write-line obj [port] @deffn primitive write-line obj [port]
Display @var{obj} and a newline character to @var{port}. If @var{port} Display @var{obj} and a newline character to @var{port}. If
is not specified, @code{(current-output-port)} is used. This function @var{port} is not specified, @code{(current-output-port)} is
is equivalent to: used. This function is equivalent to:
@lisp
@smalllisp
(display obj [port]) (display obj [port])
(newline [port]) (newline [port])
@end smalllisp @end lisp
@end deffn @end deffn
Some of the abovementioned I/O functions rely on the following C Some of the abovementioned I/O functions rely on the following C
primitives. These will mainly be of interest to people hacking Guile primitives. These will mainly be of interest to people hacking Guile
internals. internals.
@c ARGFIXME gobble/gobble?
@c docstring begin (texi-doc-string "guile" "%read-delimited!") @c docstring begin (texi-doc-string "guile" "%read-delimited!")
@deffn primitive %read-delimited! delims str gobble [port [start [end]]] @deffn primitive %read-delimited! delims str gobble [port [start [end]]]
Read characters from @var{port} into @var{str} until one of the Read characters from @var{port} into @var{str} until one of the
@ -567,16 +558,13 @@ The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface See also @ref{Ports and File Descriptors, open}, for an interface
to the Unix @code{open} system call. to the Unix @code{open} system call.
@c ARGFIXME string/filename mode/modes
@c docstring begin (texi-doc-string "guile" "open-file") @c docstring begin (texi-doc-string "guile" "open-file")
@deffn primitive open-file filename modes @deffn primitive open-file filename mode
Open the file whose name is @var{string}, and return a port Open the file whose name is @var{filename}, and return a port
representing that file. The attributes of the port are representing that file. The attributes of the port are
determined by the @var{mode} string. The way in determined by the @var{mode} string. The way in which this is
which this is interpreted is similar to C stdio: interpreted is similar to C stdio. The first character must be
one of the following:
The first character must be one of the following:
@table @samp @table @samp
@item r @item r
Open an existing file for input. Open an existing file for input.
@ -584,34 +572,31 @@ Open an existing file for input.
Open a file for output, creating it if it doesn't already exist Open a file for output, creating it if it doesn't already exist
or removing its contents if it does. or removing its contents if it does.
@item a @item a
Open a file for output, creating it if it doesn't already exist. Open a file for output, creating it if it doesn't already
All writes to the port will go to the end of the file. 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 The "append mode" can be turned off while the port is in use
@pxref{Ports and File Descriptors, fcntl} @pxref{Ports and File Descriptors, fcntl}
@end table @end table
The following additional characters can be appended: The following additional characters can be appended:
@table @samp @table @samp
@item + @item +
Open the port for both input and output. E.g., @code{r+}: open Open the port for both input and output. E.g., @code{r+}: open
an existing file for both input and output. an existing file for both input and output.
@item 0 @item 0
Create an "unbuffered" port. In this case input and output operations Create an "unbuffered" port. In this case input and output
are passed directly to the underlying port implementation without operations are passed directly to the underlying port
additional buffering. This is likely to slow down I/O operations. implementation without additional buffering. This is likely to
The buffering mode can be changed while a port is in use slow down I/O operations. The buffering mode can be changed
@pxref{Ports and File Descriptors, setvbuf} while a port is in use @pxref{Ports and File Descriptors,
setvbuf}
@item l @item l
Add line-buffering to the port. The port output buffer will be Add line-buffering to the port. The port output buffer will be
automatically flushed whenever a newline character is written. automatically flushed whenever a newline character is written.
@end table @end table
In theory we could create read/write ports which were buffered
In theory we could create read/write ports which were buffered in one in one direction only. However this isn't included in the
direction only. However this isn't included in the current interfaces. current interfaces. If a file cannot be opened with the access
requested, @code{open-file} throws an exception.
If a file cannot be opened with the access requested,
@code{open-file} throws an exception.
@end deffn @end deffn
@r5index open-input-file @r5index open-input-file
@ -742,12 +727,11 @@ port. When the function returns, the string composed of the characters
written into the port is returned. written into the port is returned.
@end deffn @end deffn
@c ARGFIXME str/string
@c docstring begin (texi-doc-string "guile" "call-with-input-string") @c docstring begin (texi-doc-string "guile" "call-with-input-string")
@deffn primitive call-with-input-string str proc @deffn primitive call-with-input-string string proc
Calls the one-argument procedure @var{proc} with a newly created input Calls the one-argument procedure @var{proc} with a newly
port from which @var{string}'s contents may be read. The value yielded created input port from which @var{string}'s contents may be
by the @var{proc} is returned. read. The value yielded by the @var{proc} is returned.
@end deffn @end deffn
@c begin (scm-doc-string "r4rs.scm" "with-output-to-string") @c begin (scm-doc-string "r4rs.scm" "with-output-to-string")
@ -766,15 +750,15 @@ port set temporarily to a string port opened on the specified
@c docstring begin (texi-doc-string "guile" "open-input-string") @c docstring begin (texi-doc-string "guile" "open-input-string")
@deffn primitive open-input-string str @deffn primitive open-input-string str
Takes a string and returns an input port that delivers Take a string and return an input port that delivers characters
characters from the string. The port can be closed by from the string. The port can be closed by
@code{close-input-port}, though its storage will be reclaimed @code{close-input-port}, though its storage will be reclaimed
by the garbage collector if it becomes inaccessible. by the garbage collector if it becomes inaccessible.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "open-output-string") @c docstring begin (texi-doc-string "guile" "open-output-string")
@deffn primitive open-output-string @deffn primitive open-output-string
Returns an output port that will accumulate characters for Return an output port that will accumulate characters for
retrieval by @code{get-output-string}. The port can be closed retrieval by @code{get-output-string}. The port can be closed
by the procedure @code{close-output-port}, though its storage by the procedure @code{close-output-port}, though its storage
will be reclaimed by the garbage collector if it becomes will be reclaimed by the garbage collector if it becomes
@ -784,7 +768,7 @@ inaccessible.
@c docstring begin (texi-doc-string "guile" "get-output-string") @c docstring begin (texi-doc-string "guile" "get-output-string")
@deffn primitive get-output-string port @deffn primitive get-output-string port
Given an output port created by @code{open-output-string}, Given an output port created by @code{open-output-string},
returns a string consisting of the characters that have been return a string consisting of the characters that have been
output to the port so far. output to the port so far.
@end deffn @end deffn
@ -800,14 +784,12 @@ but trying to extract the file descriptor number will fail.
A @dfn{soft-port} is a port based on a vector of procedures capable of A @dfn{soft-port} is a port based on a vector of procedures capable of
accepting or delivering characters. It allows emulation of I/O ports. accepting or delivering characters. It allows emulation of I/O ports.
@c ARGFIXME pv/vector
@c docstring begin (texi-doc-string "guile" "make-soft-port") @c docstring begin (texi-doc-string "guile" "make-soft-port")
@deffn primitive make-soft-port pv modes @deffn primitive make-soft-port pv modes
Returns a port capable of receiving or delivering characters as Return a port capable of receiving or delivering characters as
specified by the @var{modes} string (@pxref{File Ports, specified by the @var{modes} string (@pxref{File Ports,
open-file}). @var{vector} must be a vector of length 6. Its components open-file}). @var{pv} must be a vector of length 5. Its
are as follows: components are as follows:
@enumerate 0 @enumerate 0
@item @item
procedure accepting one character for output procedure accepting one character for output
@ -820,17 +802,15 @@ thunk for getting one character
@item @item
thunk for closing port (not by garbage collection) thunk for closing port (not by garbage collection)
@end enumerate @end enumerate
For an output-only port only elements 0, 1, 2, and 4 need be 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. For an input-only port only elements 3 and 4 need
procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful be procedures. Thunks 2 and 4 can instead be @code{#f} if
operation for them to perform. there is no useful operation for them to perform.
If thunk 3 returns @code{#f} or an @code{eof-object}
If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input, (@pxref{Input, eof-object?, ,r4rs, The Revised^4 Report on
eof-object?, ,r4rs, The Revised^4 Report on Scheme}) it indicates that Scheme}) it indicates that the port has reached end-of-file.
the port has reached end-of-file. For example: For example:
@lisp
@example
(define stdout (current-output-port)) (define stdout (current-output-port))
(define p (make-soft-port (define p (make-soft-port
(vector (vector
@ -840,9 +820,8 @@ the port has reached end-of-file. For example:
(lambda () (char-upcase (read-char))) (lambda () (char-upcase (read-char)))
(lambda () (display "@@" stdout))) (lambda () (display "@@" stdout)))
"rw")) "rw"))
(write p p) @result{} #<input-output: soft 8081e20> (write p p) @result{} #<input-output: soft 8081e20>
@end example @end lisp
@end deffn @end deffn

39
doc/scheme-memory.texi
View file

@ -23,7 +23,8 @@ no longer accessible.
@c docstring begin (texi-doc-string "guile" "gc-stats") @c docstring begin (texi-doc-string "guile" "gc-stats")
@deffn primitive gc-stats @deffn primitive gc-stats
Returns an association list of statistics about Guile's current use of storage. Return an association list of statistics about Guile's current
use of storage.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "object-address") @c docstring begin (texi-doc-string "guile" "object-address")
@ -87,21 +88,19 @@ they constitute a doubly-weak table has to be used.
@node Weak key hashes @node Weak key hashes
@subsection Weak key hashes @subsection Weak key hashes
@c ARGFIXME k/size
@c docstring begin (texi-doc-string "guile" "make-weak-key-hash-table") @c docstring begin (texi-doc-string "guile" "make-weak-key-hash-table")
@deffn primitive make-weak-key-hash-table k @deffn primitive make-weak-key-hash-table size
@deffnx primitive make-weak-value-hash-table size @deffnx primitive make-weak-value-hash-table size
@deffnx primitive make-doubly-weak-hash-table size @deffnx primitive make-doubly-weak-hash-table size
Return a weak hash table with @var{size} buckets. As with any hash Return a weak hash table with @var{size} buckets. As with any
table, choosing a good size for the table requires some caution. 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 You can modify weak hash tables in exactly the same way you
regular hash tables. (@pxref{Hash Tables}) would modify regular hash tables. (@pxref{Hash Tables})
@end deffn @end deffn
@c ARGFIXME x/obj
@c docstring begin (texi-doc-string "guile" "weak-key-hash-table?") @c docstring begin (texi-doc-string "guile" "weak-key-hash-table?")
@deffn primitive weak-key-hash-table? x @deffn primitive weak-key-hash-table? obj
@deffnx primitive weak-value-hash-table? obj @deffnx primitive weak-value-hash-table? obj
@deffnx primitive doubly-weak-hash-table? obj @deffnx primitive doubly-weak-hash-table? obj
Return @code{#t} if @var{obj} is the specified weak hash Return @code{#t} if @var{obj} is the specified weak hash
@ -132,28 +131,26 @@ nor a weak value hash table.
Weak vectors are mainly useful in Guile's implementation of weak hash Weak vectors are mainly useful in Guile's implementation of weak hash
tables. tables.
@c ARGFIXME k/size
@c docstring begin (texi-doc-string "guile" "make-weak-vector") @c docstring begin (texi-doc-string "guile" "make-weak-vector")
@deffn primitive make-weak-vector k [fill] @deffn primitive make-weak-vector size [fill]
Return a weak vector with @var{size} elements. If the optional 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 argument @var{fill} is given, all entries in the vector will be
@var{fill}. The default value for @var{fill} is the empty list. set to @var{fill}. The default value for @var{fill} is the
empty list.
@end deffn @end deffn
@c NJFIXME should vector->list here be list->vector ?
@c docstring begin (texi-doc-string "guile" "weak-vector") @c docstring begin (texi-doc-string "guile" "weak-vector")
@c docstring begin (texi-doc-string "guile" "list->weak-vector") @c docstring begin (texi-doc-string "guile" "list->weak-vector")
@deffn primitive weak-vector . l @deffn primitive weak-vector . l
@deffnx primitive list->weak-vector l @deffnx primitive list->weak-vector l
Construct a weak vector from a list: @code{weak-vector} uses the list of Construct a weak vector from a list: @code{weak-vector} uses
its arguments while @code{list->weak-vector} uses its only argument the list of its arguments while @code{list->weak-vector} uses
@var{l} (a list) to construct a weak vector the same way its only argument @var{l} (a list) to construct a weak vector
@code{vector->list} would. the same way @code{list->vector} would.
@end deffn @end deffn
@c ARGFIXME x/obj
@c docstring begin (texi-doc-string "guile" "weak-vector?") @c docstring begin (texi-doc-string "guile" "weak-vector?")
@deffn primitive weak-vector? x @deffn primitive weak-vector? obj
Return @code{#t} if @var{obj} is a weak vector. Note that all Return @code{#t} if @var{obj} is a weak vector. Note that all
weak hashes are also weak vectors. weak hashes are also weak vectors.
@end deffn @end deffn

68
doc/scheme-modules.texi
View file

@ -182,12 +182,12 @@ written properly.
Guile's dynamic linking functions make it relatively easy to write a Guile's dynamic linking functions make it relatively easy to write a
module that incorporates code from third-party object code libraries. module that incorporates code from third-party object code libraries.
@c ARGFIXME fname/library-file
@c docstring begin (texi-doc-string "guile" "dynamic-link") @c docstring begin (texi-doc-string "guile" "dynamic-link")
@deffn primitive dynamic-link fname @deffn primitive dynamic-link filename
Open the dynamic library @var{library-file}. A library handle Open the dynamic library called @var{filename}. A library
representing the opened library is returned; this handle should be used handle representing the opened library is returned; this handle
as the @var{lib} argument to the following functions. should be used as the @var{dobj} argument to the following
functions.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "dynamic-object?") @c docstring begin (texi-doc-string "guile" "dynamic-object?")
@ -196,19 +196,14 @@ Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
otherwise. otherwise.
@end deffn @end deffn
@c ARGFIXME dobj/dynobj/library-handle
@c docstring begin (texi-doc-string "guile" "dynamic-unlink") @c docstring begin (texi-doc-string "guile" "dynamic-unlink")
@deffn primitive dynamic-unlink dobj @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 Unlink the indicated object file from the application. The
argument @var{dynobj} must have been obtained by a call to argument @var{dobj} must have been obtained by a call to
@code{dynamic-link}. After @code{dynamic-unlink} has been @code{dynamic-link}. After @code{dynamic-unlink} has been
called on @var{dynobj}, its content is no longer accessible. called on @var{dobj}, its content is no longer accessible.
@end deffn @end deffn
@c ARGFIXME symb/func/function dobj/lib/dynobj
@c docstring begin (texi-doc-string "guile" "dynamic-func") @c docstring begin (texi-doc-string "guile" "dynamic-func")
@deffn primitive dynamic-func name dobj @deffn primitive dynamic-func name dobj
Search the dynamic object @var{dobj} for the C function Search the dynamic object @var{dobj} for the C function
@ -222,54 +217,37 @@ underscore in @var{function}. Guile knows whether the underscore is
needed or not and will add it when necessary. needed or not and will add it when necessary.
@end deffn @end deffn
@c ARGFIXME lib-thunk/func/function lib/dobj/dynobj
@c docstring begin (texi-doc-string "guile" "dynamic-call") @c docstring begin (texi-doc-string "guile" "dynamic-call")
@deffn primitive dynamic-call func dobj @deffn primitive dynamic-call func dobj
Call @var{lib-thunk}, a procedure of no arguments. If @var{lib-thunk} Call the C function indicated by @var{func} and @var{dobj}.
is a string, it is assumed to be a symbol found in the dynamic library The function is passed no arguments and its return value is
@var{lib} and is fetched with @code{dynamic-func}. Otherwise, it should ignored. When @var{function} is something returned by
be a function handle returned by a previous call to @code{dynamic-func}. @code{dynamic-func}, call that function and ignore @var{dobj}.
The return value is unspecified. When @var{func} is a string , look it up in @var{dynobj}; this
GJB:FIXME:DOC 2nd version below is equivalent to
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 @smallexample
(dynamic-call (dynamic-func @var{function} @var{dynobj} #f)) (dynamic-call (dynamic-func @var{func} @var{dobj} #f))
@end smallexample @end smallexample
Interrupts are deferred while the C function is executing (with Interrupts are deferred while the C function is executing (with
@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}). @code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
@end deffn @end deffn
@c ARGFIXME func/proc/function dobj/dynobj
@c docstring begin (texi-doc-string "guile" "dynamic-args-call") @c docstring begin (texi-doc-string "guile" "dynamic-args-call")
@deffn primitive dynamic-args-call func dobj args @deffn primitive dynamic-args-call func dobj args
Call @var{proc}, a dynamically loaded function, passing it the argument Call the C function indicated by @var{func} and @var{dobj},
list @var{args} (a list of strings). As with @code{dynamic-call}, just like @code{dynamic-call}, but pass it some arguments and
@var{proc} should be either a function handle or a string, in which case return its return value. The C function is expected to take
it is first fetched from @var{lib} with @code{dynamic-func}. two arguments and return an @code{int}, just like @code{main}:
@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 @smallexample
int c_func (int argc, char **argv); int c_func (int argc, char **argv);
@end smallexample @end smallexample
The parameter @var{args} must be a list of strings and is converted into The parameter @var{args} must be a list of strings and is
an array of @code{char *}. The array is passed in @var{argv} and its converted into an array of @code{char *}. The array is passed
size in @var{argc}. The return value is converted to a Scheme number in @var{argv} and its size in @var{argc}. The return value is
and returned from the call to @code{dynamic-args-call}. converted to a Scheme number and returned from the call to
@code{dynamic-args-call}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "c-registered-modules") @c docstring begin (texi-doc-string "guile" "c-registered-modules")

4
doc/scheme-options.texi
View file

@ -284,11 +284,11 @@ Guile's configuration at run time.
Return a string describing Guile's version number, or its major or minor Return a string describing Guile's version number, or its major or minor
version numbers, respectively. version numbers, respectively.
@example @lisp
(version) @result{} "1.3a" (version) @result{} "1.3a"
(major-version) @result{} "1" (major-version) @result{} "1"
(minor-version) @result{} "3a" (minor-version) @result{} "3a"
@end example @end lisp
@end deffn @end deffn
@c NJFIXME not in libguile! @c NJFIXME not in libguile!

51
doc/scheme-procedures.texi
View file

@ -128,45 +128,44 @@ or Aubrey for help. -twp]
@c docstring begin (texi-doc-string "guile" "procedure->syntax") @c docstring begin (texi-doc-string "guile" "procedure->syntax")
@deffn primitive procedure->syntax code @deffn primitive procedure->syntax code
Returns a @dfn{macro} which, when a symbol defined to this value Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, returns the result appears as the first symbol in an expression, returns the
of applying @var{code} to the expression and the environment. result of applying @var{code} to the expression and the
environment.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "procedure->macro") @c docstring begin (texi-doc-string "guile" "procedure->macro")
@deffn primitive procedure->macro code @deffn primitive procedure->macro code
Returns a @dfn{macro} which, when a symbol defined to this value Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the result appears as the first symbol in an expression, evaluates the
of applying @var{code} to the expression and the environment. result of applying @var{code} to the expression and the
The value returned from @var{code} which has been passed to environment. The value returned from @var{code} which has been
@code{procedure->memoizing-macro} replaces the form passed to passed to @code{procedure->memoizing-macro} replaces the form
@var{code}. For example: passed to @var{code}. For example:
@lisp
@example
(define trace (define trace
(procedure->macro (procedure->macro
(lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})). (trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example @end lisp
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "procedure->memoizing-macro") @c docstring begin (texi-doc-string "guile" "procedure->memoizing-macro")
@deffn primitive procedure->memoizing-macro code @deffn primitive procedure->memoizing-macro code
Returns a @dfn{macro} which, when a symbol defined to this value Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the result appears as the first symbol in an expression, evaluates the
of applying @var{proc} to the expression and the environment. result of applying @var{proc} to the expression and the
The value returned from @var{proc} which has been passed to environment. The value returned from @var{proc} which has been
@code{procedure->memoizing-macro} replaces the form passed to passed to @code{procedure->memoizing-macro} replaces the form
@var{proc}. For example: passed to @var{proc}. For example:
@lisp
@example
(define trace (define trace
(procedure->macro (procedure->macro
(lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x)))))) (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})). (trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end example @end lisp
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "macro?") @c docstring begin (texi-doc-string "guile" "macro?")
@ -175,13 +174,13 @@ Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
syntax transformer. syntax transformer.
@end deffn @end deffn
@c ARGFIXME m/obj
@c docstring begin (texi-doc-string "guile" "macro-type") @c docstring begin (texi-doc-string "guile" "macro-type")
@deffn primitive macro-type m @deffn primitive macro-type m
Return one of the symbols @code{syntax}, @code{macro} or @code{macro!}, Return one of the symbols @code{syntax}, @code{macro} or
depending on whether @var{obj} is a syntax tranformer, a regular macro, @code{macro!}, depending on whether @var{m} is a syntax
or a memoizing macro, respectively. If @var{obj} is not a macro, tranformer, a regular macro, or a memoizing macro,
@code{#f} is returned. respectively. If @var{m} is not a macro, @code{#f} is
returned.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "macro-name") @c docstring begin (texi-doc-string "guile" "macro-name")

12
doc/scheme-scheduling.texi
View file

@ -123,7 +123,7 @@ 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 the root and a new chain started for @var{thunk}. Therefore, this call
may not do what you expect: may not do what you expect:
@example @lisp
;; Almost certainly a bug: ;; Almost certainly a bug:
(with-output-to-port (with-output-to-port
some-port some-port
@ -134,7 +134,7 @@ may not do what you expect:
(display 'fnord) (display 'fnord)
(newline)) (newline))
(lambda (errcode) errcode)))) (lambda (errcode) errcode))))
@end example @end lisp
The problem is, on what port will @samp{fnord} be displayed? You The problem is, on what port will @samp{fnord} be displayed? You
might expect that because of the @code{with-output-to-port} that might expect that because of the @code{with-output-to-port} that
@ -353,13 +353,15 @@ in its own dynamic root, you can use fluids for thread local storage.
@c docstring begin (texi-doc-string "guile" "fluid?") @c docstring begin (texi-doc-string "guile" "fluid?")
@deffn primitive fluid? obj @deffn primitive fluid? obj
Return #t iff @var{obj} is a fluid; otherwise, return #f. Return @code{#t} iff @var{obj} is a fluid; otherwise, return
@code{#f}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "fluid-ref") @c docstring begin (texi-doc-string "guile" "fluid-ref")
@deffn primitive fluid-ref fluid @deffn primitive fluid-ref fluid
Return the value associated with @var{fluid} in the current dynamic root. Return the value associated with @var{fluid} in the current
If @var{fluid} has not been set, then this returns #f. dynamic root. If @var{fluid} has not been set, then return
@code{#f}.
@end deffn @end deffn
@c docstring begin (texi-doc-string "guile" "fluid-set!") @c docstring begin (texi-doc-string "guile" "fluid-set!")

10
doc/scheme-utility.texi
View file

@ -66,9 +66,8 @@ a property list associated with a procedure object, use the
Return @var{obj}'s property list. Return @var{obj}'s property list.
@end deffn @end deffn
@c ARGFIXME alist/plist
@c docstring begin (texi-doc-string "guile" "set-object-properties!") @c docstring begin (texi-doc-string "guile" "set-object-properties!")
@deffn primitive set-object-properties! obj plist @deffn primitive set-object-properties! obj alist
@deffnx primitive set-procedure-properties! obj alist @deffnx primitive set-procedure-properties! obj alist
Set @var{obj}'s property list to @var{alist}. Set @var{obj}'s property list to @var{alist}.
@end deffn @end deffn
@ -79,12 +78,11 @@ Set @var{obj}'s property list to @var{alist}.
Return the property of @var{obj} with name @var{key}. Return the property of @var{obj} with name @var{key}.
@end deffn @end deffn
@c ARGFIXME val/value
@c docstring begin (texi-doc-string "guile" "set-object-property!") @c docstring begin (texi-doc-string "guile" "set-object-property!")
@deffn primitive set-object-property! obj key val @deffn primitive set-object-property! obj key value
@deffnx primitive set-procedure-property! obj key value @deffnx primitive set-procedure-property! obj key value
In @var{obj}'s property list, set the property named @var{key} to In @var{obj}'s property list, set the property named @var{key}
@var{value}. to @var{value}.
@end deffn @end deffn
[Interface bug: there should be a second level of interface in which [Interface bug: there should be a second level of interface in which