mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-09 23:40:29 +02:00
Code Activity

* eval.c (scm_promise_p), list.c (scm_append_x, scm_reverse_x),

Browse source 
symbols.c (scm_symbol_to_string), vports.c (scm_make_soft_port):
	Change R4RS references to R5RS.

	* guile-snarf.awk.in: Fixes so that (i) blank lines in the
	docstring source are correctly reproduced in the output (ii)
	we don't anymore get occasional trailing quotes.  Also reorganized
	and commented the code a little.

	* scmsigs.c (scm_raise), throw.c (scm_throw): Docstring format
	fixes.

	* new-docstrings.texi, posix.texi, scheme-control.texi,
	scheme-data.texi, scheme-debug.texi, scheme-evaluation.texi,
	scheme-io.texi, scheme-memory.texi, scheme-procedures.texi:
	Automatic docstring updates (mostly argument name updates and
	blank lines).

	* scheme-modules.texi: Change double hyphens to single.

	* scheme-control.texi (Lazy Catch): Completed.

	* posix.texi (Network Databases and Address Conversion): New
	subsubsection `IPv6 Address Conversion'.
This commit is contained in:
Neil Jerram 2001-05-04 21:54:00 +00:00
parent f92a9df0ff
commit 7a095584a9
20 changed files with 765 additions and 1076 deletions
Download patch file Download diff file Expand all files Collapse all files

15
doc/ChangeLog
View file

@ -1,3 +1,18 @@
2001-05-04 Neil Jerram <neil@ossau.uklinux.net>
* new-docstrings.texi, posix.texi, scheme-control.texi,
scheme-data.texi, scheme-debug.texi, scheme-evaluation.texi,
scheme-io.texi, scheme-memory.texi, scheme-procedures.texi:
Automatic docstring updates (mostly argument name updates and
blank lines).
* scheme-modules.texi: Change double hyphens to single.
* scheme-control.texi (Lazy Catch): Completed.
* posix.texi (Network Databases and Address Conversion): New
subsubsection `IPv6 Address Conversion'.
2001-05-04 Thien-Thi Nguyen <ttn@revel.glug.org> 2001-05-04 Thien-Thi Nguyen <ttn@revel.glug.org>
* preface.texi (iff): Use proper texi markup. * preface.texi (iff): Use proper texi markup.

626
doc/maint/guile.texi
View file

File diff suppressed because it is too large Load diff

494
doc/new-docstrings.texi
View file

@ -1,494 +0,0 @@
@c module (guile)
@deffn primitive environment? obj
Return @code{#t} if @var{obj} is an environment, or @code{#f}
otherwise.
@end deffn
@deffn primitive environment-bound? env sym
Return @code{#t} if @var{sym} is bound in @var{env}, or
@code{#f} otherwise.
@end deffn
@deffn primitive environment-ref env sym
Return the value of the location bound to @var{sym} in
@var{env}. If @var{sym} is unbound in @var{env}, signal an
@code{environment:unbound} error.
@end deffn
@deffn primitive environment-fold env proc init
Iterate over all the bindings in @var{env}, accumulating some
value.
For each binding in @var{env}, apply @var{proc} to the symbol
bound, its value, and the result from the previous application
of @var{proc}.
Use @var{init} as @var{proc}'s third argument the first time
@var{proc} is applied.
If @var{env} contains no bindings, this function simply returns
@var{init}.
If @var{env} binds the symbol sym1 to the value val1, sym2 to
val2, and so on, then this procedure computes:
@lisp
(proc sym1 val1
(proc sym2 val2
...
(proc symn valn
init)))
@end lisp
Each binding in @var{env} will be processed exactly once.
@code{environment-fold} makes no guarantees about the order in
which the bindings are processed.
Here is a function which, given an environment, constructs an
association list representing that environment's bindings,
using environment-fold:
@lisp
(define (environment->alist env)
(environment-fold env
(lambda (sym val tail)
(cons (cons sym val) tail))
'()))
@end lisp
@end deffn
@deffn primitive environment-define env sym val
Bind @var{sym} to a new location containing @var{val} in
@var{env}. If @var{sym} is already bound to another location
in @var{env} and the binding is mutable, that binding is
replaced. The new binding and location are both mutable. The
return value is unspecified.
If @var{sym} is already bound in @var{env}, and the binding is
immutable, signal an @code{environment:immutable-binding} error.
@end deffn
@deffn primitive environment-undefine env sym
Remove any binding for @var{sym} from @var{env}. If @var{sym}
is unbound in @var{env}, do nothing. The return value is
unspecified.
If @var{sym} is already bound in @var{env}, and the binding is
immutable, signal an @code{environment:immutable-binding} error.
@end deffn
@deffn primitive environment-set! env sym val
If @var{env} binds @var{sym} to some location, change that
location's value to @var{val}. The return value is
unspecified.
If @var{sym} is not bound in @var{env}, signal an
@code{environment:unbound} error. If @var{env} binds @var{sym}
to an immutable location, signal an
@code{environment:immutable-location} error.
@end deffn
@deffn primitive environment-cell env sym for_write
Return the value cell which @var{env} binds to @var{sym}, or
@code{#f} if the binding does not live in a value cell.
The argument @var{for-write} indicates whether the caller
intends to modify the variable's value by mutating the value
cell. If the variable is immutable, then
@code{environment-cell} signals an
@code{environment:immutable-location} error.
If @var{sym} is unbound in @var{env}, signal an
@code{environment:unbound} error.
If you use this function, you should consider using
@code{environment-observe}, to be notified when @var{sym} gets
re-bound to a new value cell, or becomes undefined.
@end deffn
@deffn primitive environment-observe env proc
Whenever @var{env}'s bindings change, apply @var{proc} to
@var{env}.
This function returns an object, token, which you can pass to
@code{environment-unobserve} to remove @var{proc} from the set
of procedures observing @var{env}. The type and value of
token is unspecified.
@end deffn
@deffn primitive environment-observe-weak env proc
This function is the same as environment-observe, except that
the reference @var{env} retains to @var{proc} is a weak
reference. This means that, if there are no other live,
non-weak references to @var{proc}, it will be
garbage-collected, and dropped from @var{env}'s
list of observing procedures.
@end deffn
@deffn primitive environment-unobserve token
Cancel the observation request which returned the value
@var{token}. The return value is unspecified.
If a call @code{(environment-observe env proc)} returns
@var{token}, then the call @code{(environment-unobserve token)}
will cause @var{proc} to no longer be called when @var{env}'s
bindings change.
@end deffn
@deffn primitive make-leaf-environment
Create a new leaf environment, containing no bindings.
All bindings and locations created in the new environment
will be mutable.
@end deffn
@deffn primitive leaf-environment? object
Return @code{#t} if object is a leaf environment, or @code{#f}
otherwise.
@end deffn
@deffn primitive make-eval-environment local imported
Return a new environment object eval whose bindings are the
union of the bindings in the environments @var{local} and
@var{imported}, with bindings from @var{local} taking
precedence. Definitions made in eval are placed in @var{local}.
Applying @code{environment-define} or
@code{environment-undefine} to eval has the same effect as
applying the procedure to @var{local}.
Note that eval incorporates @var{local} and @var{imported} by
reference:
If, after creating eval, the program changes the bindings of
@var{local} or @var{imported}, those changes will be visible
in eval.
Since most Scheme evaluation takes place in eval environments,
they transparently cache the bindings received from @var{local}
and @var{imported}. Thus, the first time the program looks up
a symbol in eval, eval may make calls to @var{local} or
@var{imported} to find their bindings, but subsequent
references to that symbol will be as fast as references to
bindings in finite environments.
In typical use, @var{local} will be a finite environment, and
@var{imported} will be an import environment
@end deffn
@deffn primitive eval-environment? object
Return @code{#t} if object is an eval environment, or @code{#f}
otherwise.
@end deffn
@deffn primitive eval-environment-local env
Return the local environment of eval environment @var{env}.
@end deffn
@deffn primitive eval-environment-set-local! env local
Change @var{env}'s local environment to @var{local}.
@end deffn
@deffn primitive eval-environment-imported env
Return the imported environment of eval environment @var{env}.
@end deffn
@deffn primitive eval-environment-set-imported! env imported
Change @var{env}'s imported environment to @var{imported}.
@end deffn
@deffn primitive make-import-environment imports conflict_proc
Return a new environment @var{imp} whose bindings are the union
of the bindings from the environments in @var{imports};
@var{imports} must be a list of environments. That is,
@var{imp} binds a symbol to a location when some element of
@var{imports} does.
If two different elements of @var{imports} have a binding for
the same symbol, the @var{conflict-proc} is called with the
following parameters: the import environment, the symbol and
the list of the imported environments that bind the symbol.
If the @var{conflict-proc} returns an environment @var{env},
the conflict is considered as resolved and the binding from
@var{env} is used. If the @var{conflict-proc} returns some
non-environment object, the conflict is considered unresolved
and the symbol is treated as unspecified in the import
environment.
The checking for conflicts may be performed lazily, i. e. at
the moment when a value or binding for a certain symbol is
requested instead of the moment when the environment is
created or the bindings of the imports change.
All bindings in @var{imp} are immutable. If you apply
@code{environment-define} or @code{environment-undefine} to
@var{imp}, Guile will signal an
@code{environment:immutable-binding} error. However,
notice that the set of bindings in @var{imp} may still change,
if one of its imported environments changes.
@end deffn
@deffn primitive import-environment? object
Return @code{#t} if object is an import environment, or
@code{#f} otherwise.
@end deffn
@deffn primitive import-environment-imports env
Return the list of environments imported by the import
environment @var{env}.
@end deffn
@deffn primitive import-environment-set-imports! env imports
Change @var{env}'s list of imported environments to
@var{imports}, and check for conflicts.
@end deffn
@deffn primitive make-export-environment private signature
Return a new environment @var{exp} containing only those
bindings in private whose symbols are present in
@var{signature}. The @var{private} argument must be an
environment.
The environment @var{exp} binds symbol to location when
@var{env} does, and symbol is exported by @var{signature}.
@var{signature} is a list specifying which of the bindings in
@var{private} should be visible in @var{exp}. Each element of
@var{signature} should be a list of the form:
(symbol attribute ...)
where each attribute is one of the following:
@table @asis
@item the symbol @code{mutable-location}
@var{exp} should treat the
location bound to symbol as mutable. That is, @var{exp}
will pass calls to @code{environment-set!} or
@code{environment-cell} directly through to private.
@item the symbol @code{immutable-location}
@var{exp} should treat
the location bound to symbol as immutable. If the program
applies @code{environment-set!} to @var{exp} and symbol, or
calls @code{environment-cell} to obtain a writable value
cell, @code{environment-set!} will signal an
@code{environment:immutable-location} error. Note that, even
if an export environment treats a location as immutable, the
underlying environment may treat it as mutable, so its
value may change.
@end table
It is an error for an element of signature to specify both
@code{mutable-location} and @code{immutable-location}. If
neither is specified, @code{immutable-location} is assumed.
As a special case, if an element of signature is a lone
symbol @var{sym}, it is equivalent to an element of the form
@code{(sym)}.
All bindings in @var{exp} are immutable. If you apply
@code{environment-define} or @code{environment-undefine} to
@var{exp}, Guile will signal an
@code{environment:immutable-binding} error. However,
notice that the set of bindings in @var{exp} may still change,
if the bindings in private change.
@end deffn
@deffn primitive export-environment? object
Return @code{#t} if object is an export environment, or
@code{#f} otherwise.
@end deffn
@deffn primitive export-environment-private env
Return the private environment of export environment @var{env}.
@end deffn
@deffn primitive export-environment-set-private! env private
Change the private environment of export environment @var{env}.
@end deffn
@deffn primitive export-environment-signature env
Return the signature of export environment @var{env}.
@end deffn
@deffn primitive export-environment-set-signature! env signature
Change the signature of export environment @var{env}.
@end deffn
@deffn primitive %compute-slots class
Return a list consisting of the names of all slots belonging to
class @var{class}, i. e. the slots of @var{class} and of all of
its superclasses.
@end deffn
@deffn primitive get-keyword key l default_value
Determine an associated value for the keyword @var{key} from
the list @var{l}. The list @var{l} has to consist of an even
number of elements, where, starting with the first, every
second element is a keyword, followed by its associated value.
If @var{l} does not hold a value for @var{key}, the value
@var{default_value} is returned.
@end deffn
@deffn primitive slot-ref-using-class class obj slot_name
@end deffn
@deffn primitive slot-set-using-class! class obj slot_name value
@end deffn
@deffn primitive class-of x
Return the class of @var{x}.
@end deffn
@deffn primitive %goops-loaded
Announce that GOOPS is loaded and perform initialization
on the C level which depends on the loaded GOOPS modules.
@end deffn
@deffn primitive %method-more-specific? m1 m2 targs
@end deffn
@deffn primitive find-method . l
@end deffn
@deffn primitive primitive-generic-generic subr
@end deffn
@deffn primitive enable-primitive-generic! . subrs
@end deffn
@deffn primitive generic-capability? proc
@end deffn
@deffn primitive %invalidate-method-cache! gf
@end deffn
@deffn primitive %invalidate-class class
@end deffn
@deffn primitive %modify-class old new
@end deffn
@deffn primitive %modify-instance old new
@end deffn
@deffn primitive %set-object-setter! obj setter
@end deffn
@deffn primitive %allocate-instance class initargs
Create a new instance of class @var{class} and initialize it
from the arguments @var{initargs}.
@end deffn
@deffn primitive slot-exists? obj slot_name
Return @code{#t} if @var{obj} has a slot named @var{slot_name}.
@end deffn
@deffn primitive slot-bound? obj slot_name
Return @code{#t} if the slot named @var{slot_name} of @var{obj}
is bound.
@end deffn
@deffn primitive slot-set! obj slot_name value
Set the slot named @var{slot_name} of @var{obj} to @var{value}.
@end deffn
@deffn primitive slot-exists-using-class? class obj slot_name
@end deffn
@deffn primitive slot-bound-using-class? class obj slot_name
@end deffn
@deffn primitive %fast-slot-set! obj index value
Set the slot with index @var{index} in @var{obj} to
@var{value}.
@end deffn
@deffn primitive %fast-slot-ref obj index
Return the slot value with index @var{index} from @var{obj}.
@end deffn
@deffn primitive @@assert-bound-ref obj index
Like @code{assert-bound}, but use @var{index} for accessing
the value from @var{obj}.
@end deffn
@deffn primitive assert-bound value obj
Return @var{value} if it is bound, and invoke the
@var{slot-unbound} method of @var{obj} if it is not.
@end deffn
@deffn primitive unbound? obj
Return @code{#t} if @var{obj} is unbound.
@end deffn
@deffn primitive make-unbound
Return the unbound value.
@end deffn
@deffn primitive accessor-method-slot-definition obj
Return the slot definition of the accessor @var{obj}.
@end deffn
@deffn primitive method-procedure obj
Return the procedure of the method @var{obj}.
@end deffn
@deffn primitive method-specializers obj
Return specializers of the method @var{obj}.
@end deffn
@deffn primitive method-generic-function obj
Return the generic function fot the method @var{obj}.
@end deffn
@deffn primitive generic-function-methods obj
Return the methods of the generic function @var{obj}.
@end deffn
@deffn primitive generic-function-name obj
Return the name of the generic function @var{obj}.
@end deffn
@deffn primitive class-environment obj
Return the environment of the class @var{obj}.
@end deffn
@deffn primitive class-slots obj
Return the slot list of the class @var{obj}.
@end deffn
@deffn primitive class-precedence-list obj
Return the class precedence list of the class @var{obj}.
@end deffn
@deffn primitive class-direct-methods obj
Return the direct methods of the class @var{obj}
@end deffn
@deffn primitive class-direct-subclasses obj
Return the direct subclasses of the class @var{obj}.
@end deffn
@deffn primitive class-direct-slots obj
Return the direct slots of the class @var{obj}.
@end deffn
@deffn primitive class-direct-supers obj
Return the direct superclasses of the class @var{obj}.
@end deffn
@deffn primitive class-name obj
Return the class name of @var{obj}.
@end deffn
@deffn primitive instance? obj
Return @code{#t} if @var{obj} is an instance.
@end deffn
@deffn primitive %inherit-magic! class dsupers
@end deffn
@deffn primitive %prep-layout! class
@end deffn
@deffn primitive %initialize-object obj initargs
Initialize the object @var{obj} with the given arguments
@var{initargs}.
@end deffn
@deffn primitive make . args
Make a new object. @var{args} must contain the class and
all necessary initialization information.
@end deffn
@deffn primitive slot-ref obj slot_name
Return the value from @var{obj}'s slot with the name
@var{slot_name}.
@end deffn
@deffn primitive builtin-bindings
Create and return a copy of the global symbol table, removing all
unbound symbols.
@end deffn
@deffn primitive %tag-body body
Internal GOOPS magic---don't use this function!
@end deffn
@deffn primitive list*
scm_cons_star
@end deffn

238
doc/posix.texi
View file

@ -295,6 +295,7 @@ flushed) to the output port can be read from the input port.
Pipes are commonly used for communication with a newly forked Pipes are commonly used for communication with a newly forked
child process. The need to flush the output port can be child process. The need to flush the output port 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 bytes
is not greater than the value of @code{PIPE_BUF}. Note that is not greater than the value of @code{PIPE_BUF}. Note that
the output port is likely to block if too much data (typically the output port is likely to block if too much data (typically
@ -511,9 +512,11 @@ and the current process has the type of access specified by
using the values of the variables listed below. Multiple using the values of the variables listed below. Multiple
values can be combined using a bitwise or, in which case values can be combined using a bitwise or, in which case
@code{#t} will only be returned if all accesses are granted. @code{#t} will only be returned if all accesses are granted.
Permissions are checked using the real id of the current Permissions are checked using the real id of the current
process, not the effective id, although it's the effective id process, not the effective id, although it's the effective id
which determines whether the access would actually be granted. 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
@ -535,9 +538,11 @@ determined by @var{obj}. @var{obj} can be a string containing
a file name or a port or integer file descriptor which is open a file name or a port or integer file descriptor which is open
on a file (in which case @code{fstat} is used as the underlying on a file (in which case @code{fstat} is used 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 to the following procedures, all of which return parameter 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.
@ -572,8 +577,10 @@ bytes.
The amount of disk space that the file occupies measured in The amount of disk space that the file occupies measured in
units of 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
@ -993,6 +1000,7 @@ reported by the following procedures.
Return an object with information about real and processor Return an object with information about real and processor
time. The following procedures accept such an object as an time. The following procedures accept such an object as an
argument and 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
@ -1262,6 +1270,7 @@ processor". Under Unix this is usually the default shell
@code{sh}. The value returned is @var{cmd}'s exit status as @code{sh}. The value returned is @var{cmd}'s exit status as
returned by @code{waitpid}, which can be interpreted using the returned by @code{waitpid}, which can be interpreted using the
functions above. functions above.
If @code{system} is called without arguments, return 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
@ -1475,6 +1484,7 @@ terminal for the current process.
Return the process group ID of the foreground process group Return the process group ID of the foreground 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
@ -1546,24 +1556,27 @@ the database routines since they are not reentrant.
@subsubsection Address Conversion @subsubsection Address Conversion
@deffn primitive inet-aton address @deffn primitive inet-aton address
Converts a string containing an Internet host address in the Convert an IPv4 Internet address from printable string
traditional dotted decimal notation into an integer. (dotted decimal notation) to an integer. E.g.,
@lisp @lisp
(inet-aton "127.0.0.1") @result{} 2130706433 (inet-aton "127.0.0.1") @result{} 2130706433
@end lisp @end lisp
@end deffn @end deffn
@deffn primitive inet-ntoa inetid @deffn primitive inet-ntoa inetid
Converts an integer Internet host address into a string with Convert an IPv4 Internet address to a printable
the traditional dotted decimal representation. (dotted decimal notation) string. E.g.,
@lisp @lisp
(inet-ntoa 2130706433) @result{} "127.0.0.1" (inet-ntoa 2130706433) @result{} "127.0.0.1"
@end lisp @end lisp
@end deffn @end deffn
@deffn primitive inet-netof address @deffn primitive inet-netof address
Return the network number part of the given integer Internet Return the network number part of the given IPv4
address. Internet address. E.g.,
@lisp @lisp
(inet-netof 2130706433) @result{} 127 (inet-netof 2130706433) @result{} 127
@end lisp @end lisp
@ -1571,21 +1584,52 @@ address.
@deffn primitive inet-lnaof address @deffn primitive inet-lnaof address
Return the local-address-with-network part of the given Return the local-address-with-network part of the given
Internet address. IPv4 Internet address, using the obsolete class A/B/C system.
E.g.,
@lisp @lisp
(inet-lnaof 2130706433) @result{} 1 (inet-lnaof 2130706433) @result{} 1
@end lisp @end lisp
@end deffn @end deffn
@deffn primitive inet-makeaddr net lna @deffn primitive inet-makeaddr net lna
Makes an Internet host address by combining the network number Make an IPv4 Internet address by combining the network number
@var{net} with the local-address-within-network number @var{net} with the local-address-within-network number
@var{lna}. @var{lna}. E.g.,
@lisp @lisp
(inet-makeaddr 127 1) @result{} 2130706433 (inet-makeaddr 127 1) @result{} 2130706433
@end lisp @end lisp
@end deffn @end deffn
@subsubsection IPv6 Address Conversion
@deffn primitive inet-ntop family address
Convert a network address into a printable string.
Note that unlike the C version of this function,
the input is an integer with normal host byte ordering.
@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
@lisp
(inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
(inet-ntop AF_INET6 (- (expt 2 128) 1)) @result{}
ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
@end lisp
@end deffn
@deffn primitive inet-pton family address
Convert a string containing a printable network address to
an integer address. Note that unlike the C version of this
function,
the result is an integer with normal host byte ordering.
@var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
@lisp
(inet-pton AF_INET "127.0.0.1") @result{} 2130706433
(inet-pton AF_INET6 "::1") @result{} 1
@end lisp
@end deffn
@subsubsection The Host Database @subsubsection The Host Database
A @dfn{host object} is a structure that represents what is known about a A @dfn{host object} is a structure that represents what is known about a
@ -1836,40 +1880,43 @@ required. The arguments and return values are thus in host order.
@deffn primitive socket family style proto @deffn primitive socket family style proto
Return a new socket port of the type specified by @var{family}, Return a new socket port of the type specified by @var{family},
@var{style} and @var{protocol}. All three parameters are @var{style} and @var{proto}. All three parameters are
integers. Supported values for @var{family} are integers. Supported values for @var{family} are
@code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}. @code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}.
Typical values for @var{style} are @code{SOCK_STREAM}, Typical values for @var{style} are @code{SOCK_STREAM},
@code{SOCK_DGRAM} and @code{SOCK_RAW}. @code{SOCK_DGRAM} and @code{SOCK_RAW}.
@var{protocol} can be obtained from a protocol name using
@var{proto} can be obtained from a protocol name using
@code{getprotobyname}. A value of zero specifies the default @code{getprotobyname}. A value of 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 it
has been connected to another socket. has been connected to another socket.
@end deffn @end deffn
@deffn primitive socketpair family style proto @deffn primitive socketpair family style proto
Return a pair of connected (but unnamed) socket ports of the Return a pair of connected (but unnamed) socket ports of the
type specified by @var{family}, @var{style} and @var{protocol}. type specified by @var{family}, @var{style} and @var{proto}.
Many systems support only socket pairs of the @code{AF_UNIX} Many systems support only socket pairs of the @code{AF_UNIX}
family. Zero is likely to be the only meaningful value for family. Zero is likely to be the only meaningful value for
@var{protocol}. @var{proto}.
@end deffn @end deffn
@deffn primitive getsockopt sock level optname @deffn primitive getsockopt sock level optname
Return 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 port @var{sock}. @var{level} is an integer code for type of
option being requested, e.g., @code{SOL_SOCKET} for option being requested, e.g., @code{SOL_SOCKET} for
socket-level options. @var{optname} is an integer code for the socket-level options. @var{optname} is an integer code for the
option required and should be specified using one of the option required and should be specified using one of 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 pair of integers. returns a pair of integers.
@end deffn @end deffn
@deffn primitive setsockopt sock level optname value @deffn primitive setsockopt sock level optname value
Sets the value of a particular socket option for the socket Set 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{sock}. @var{level} is an integer code for type of option
being set, e.g., @code{SOL_SOCKET} for socket-level options. being set, e.g., @code{SOL_SOCKET} for socket-level options.
@var{optname} is an @var{optname} is an
integer code for the option to set and should be specified using one of integer code for the option to set and should be specified using one of
@ -1902,7 +1949,7 @@ The return value is unspecified.
@end deffn @end deffn
@deffn primitive connect sock fam address . args @deffn primitive connect sock fam address . args
Initiates a connection from a socket using a specified address Initiate a connection from a socket using a specified address
family to the address family to the address
specified by @var{address} and possibly @var{args}. specified by @var{address} and possibly @var{args}.
The format required for @var{address} The format required for @var{address}
@ -1926,24 +1973,25 @@ The return value is unspecified.
@end deffn @end deffn
@deffn primitive bind sock fam address . args @deffn primitive bind sock fam address . args
Assigns an address to the socket port @var{socket}. Assign an address to the socket port @var{sock}.
Generally this only needs to be done for server sockets, Generally this only needs to be done for server sockets,
so they know where to look for incoming connections. A socket so they know where to look for incoming connections. A socket
without an address will be assigned one automatically when it without an address will be assigned one automatically when it
starts communicating. starts communicating.
The format of @var{address} and @var{ARG} @dots{} depends on the family The format of @var{address} and @var{args} depends
of the socket. on the family of the socket.
For a socket of family @code{AF_UNIX}, only @var{address} is specified For a socket of family @code{AF_UNIX}, only @var{address}
and must be a string with the filename where the socket is to be is specified and must be a string with the filename where
created. the socket is to be created.
For a socket of family @code{AF_INET}, @var{address} must be an integer For a socket of family @code{AF_INET}, @var{address}
Internet host address and @var{arg} @dots{} must be a single integer must be an integer IPv4 address and @var{args}
port number. must be a single integer port number.
The values of the following variables can also be used for @var{address}: The values of the following variables can also be used for
@var{address}:
@defvar INADDR_ANY @defvar INADDR_ANY
Allow connections from any address. Allow connections from any address.
@ -1961,33 +2009,40 @@ The broadcast address on the local network.
No address. No address.
@end defvar @end defvar
For a socket of family @code{AF_INET6}, @var{address}
must be an integer IPv6 address and @var{args}
may be up to three integers:
port [flowinfo] [scope_id],
where flowinfo and scope_id default to zero.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@deffn primitive listen sock backlog @deffn primitive listen sock backlog
This procedure enables @var{socket} to accept connection Enable @var{sock} to accept connection
requests. @var{backlog} is an integer specifying requests. @var{backlog} is an integer specifying
the maximum length of the queue for pending connections. the maximum length of the queue for pending connections.
If the queue fills, new clients will fail to connect until the If the queue fills, new clients will fail to connect until
server calls @code{accept} to accept a connection from the queue. the server calls @code{accept} to accept a connection from
the queue.
The return value is unspecified. The return value is unspecified.
@end deffn @end deffn
@deffn primitive accept sock @deffn primitive accept sock
Accepts a connection on a bound, listening socket @var{socket}. If there Accept a connection on a bound, listening socket.
are no pending connections in the queue, it waits until If there
one is available unless the non-blocking option has been set on the are no pending connections in the queue, wait until
socket. one is available unless the non-blocking option has been
set on the socket.
The return value is a The return value is a
pair in which the CAR is a new socket port for the connection and pair in which the @emph{car} is a new socket port for the
the CDR is an object with address information about the client which connection and
initiated the connection. the @emph{cdr} is an object with address information about the
client which initiated the connection.
If the address is not available then the CDR will be an empty vector. @var{sock} does not become part of the
@var{socket} does not become part of the
connection and will continue to accept new requests. connection and will continue to accept new requests.
@end deffn @end deffn
@ -2010,79 +2065,101 @@ number.
@end table @end table
@deffn primitive getsockname sock @deffn primitive getsockname sock
Return the address of @var{socket}, in the same form as the Return the address of @var{sock}, in the same form as the
object returned by @code{accept}. On many systems the address object returned by @code{accept}. On many systems the address
of a socket 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
@deffn primitive getpeername sock @deffn primitive getpeername sock
Return the address of the socket that the socket @var{socket} Return the address that @var{sock}
is connected to, in the same form as the object returned by is connected to, in the same form as the object returned by
@code{accept}. On many systems the address of a socket in the @code{accept}. On many systems the address of a socket in the
@code{AF_FILE} namespace cannot be read. @code{AF_FILE} namespace cannot be read.
@end deffn @end deffn
@deffn primitive recv! sock buf [flags] @deffn primitive recv! sock buf [flags]
Receives data from the socket port @var{socket}. @var{socket} must already Receive data from a socket port.
@var{sock} must already
be bound to the address from which data is to be received. be bound to the address from which data is to be received.
@var{buf} is a string into which @var{buf} is a string into which
the data will be written. The size of @var{buf} limits the amount of the data will be written. The size of @var{buf} limits
the amount of
data which can be received: in the case of packet data which can be received: in the case of packet
protocols, if a packet larger than this limit is encountered then some data protocols, if a packet larger than this limit is encountered
then some data
will be irrevocably lost. will be irrevocably lost.
The optional @var{flags} argument is a value or The optional @var{flags} argument is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
The value returned is the number of bytes read from the socket. The value returned is the number of bytes read from the
socket.
Note that the data is read directly from the socket file descriptor: Note that the data is read directly from the socket file
descriptor:
any unread buffered port data is ignored. any unread buffered port data is ignored.
@end deffn @end deffn
@deffn primitive send sock message [flags] @deffn primitive send sock message [flags]
Transmits the string @var{message} on the socket port @var{socket}. Transmit the string @var{message} on a socket port @var{sock}.
@var{socket} must already be bound to a destination address. The @var{sock} must already be bound to a destination address. The
value returned is the number of bytes transmitted -- it's possible for value returned is the number of bytes transmitted --
this to be less than the length of @var{message} if the socket is it's possible for
set to be non-blocking. The optional @var{flags} argument is a value or this to be less than the length of @var{message}
if the socket is
set to be non-blocking. The optional @var{flags} argument
is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
Note that the data is written directly to the socket file descriptor: Note that the data is written directly to the socket
file descriptor:
any unflushed buffered port data is ignored. any unflushed buffered port data is ignored.
@end deffn @end deffn
@deffn primitive recvfrom! sock str [flags [start [end]]] @deffn primitive recvfrom! sock str [flags [start [end]]]
Return data from the socket port @var{socket} and also Return data from the socket port @var{sock} and also
information about where the data was received from. information about where the data was received from.
@var{socket} must already be bound to the address from which @var{sock} must already be bound to the address from which
data is to be received. @code{str}, is a string into which the data is to be received. @code{str}, is a string into which the
data will be written. The size of @var{str} limits the amount data will be written. The size of @var{str} limits the amount
of data which can be received: in the case of packet protocols, of data which can be received: in the case of packet protocols,
if a packet larger than this limit is encountered then some if a packet larger than this limit is encountered then some
data 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 bitwise OR of
@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
The value returned is a pair: the @emph{car} is the number of 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 bytes read from the socket and the @emph{cdr} an address object
in the same form as returned by @code{accept}. in the same form as returned by @code{accept}. The address
will given as @code{#f} if not available, as is usually the
case for stream sockets.
The @var{start} and @var{end} arguments specify a substring of The @var{start} and @var{end} arguments specify a substring of
@var{str} to which the data should be written. @var{str} to which the data should be written.
Note that the data is read directly from the socket file Note that the data is read directly from the socket file
descriptor: any unread buffered port data is ignored. descriptor: any unread buffered port data is ignored.
@end deffn @end deffn
@deffn primitive sendto sock message fam address . args_and_flags @deffn primitive sendto sock message fam address . args_and_flags
Transmits the string @var{message} on the socket port @var{socket}. The Transmit the string @var{message} on the socket port
destination address is specified using the @var{family}, @var{address} and @var{sock}. The
@var{arg} arguments, in a similar way to the @code{connect} destination address is specified using the @var{fam},
procedure. The @var{address} and
value returned is the number of bytes transmitted -- it's possible for @var{args_and_flags} arguments, in a similar way to the
this to be less than the length of @var{message} if the socket is @code{connect} procedure. @var{args_and_flags} contains
set to be non-blocking. The optional @var{flags} argument is a value or the usual connection arguments optionally followed by
a flags argument, which is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc. bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
Note that the data is written directly to the socket file descriptor: The value returned is the number of bytes transmitted --
it's possible for
this to be less than the length of @var{message} if the
socket is
set to be non-blocking.
Note that the data is written directly to the socket
file descriptor:
any unflushed buffered port data is ignored. any unflushed buffered port data is ignored.
@end deffn @end deffn
@ -2091,28 +2168,28 @@ between "host" and "network" order. Although the procedures above do
this automatically for addresses, the conversion will still need to this automatically for addresses, the conversion will still need to
be done when sending or receiving encoded integer data from the network. be done when sending or receiving encoded integer data from the network.
@deffn primitive htons in @deffn primitive htons value
Return a new integer from @var{value} by converting from host Convert a 16 bit quantity from host to network byte ordering.
to network order. @var{value} must be within the range of a C @var{value} is packed into 2 bytes, which are then converted
unsigned short integer. and returned as a new integer.
@end deffn @end deffn
@deffn primitive ntohs in @deffn primitive ntohs value
Return a new integer from @var{value} by converting from Convert a 16 bit quantity from network to host byte ordering.
network to host order. @var{value} must be within the range of @var{value} is packed into 2 bytes, which are then converted
a C unsigned short integer. and returned as a new integer.
@end deffn @end deffn
@deffn primitive htonl in @deffn primitive htonl value
Return a new integer from @var{value} by converting from host Convert a 32 bit quantity from host to network byte ordering.
to network order. @var{value} must be within the range of a C @var{value} is packed into 4 bytes, which are then converted
unsigned long integer. and returned as a new integer.
@end deffn @end deffn
@deffn primitive ntohl in @deffn primitive ntohl value
Return a new integer from @var{value} by converting from Convert a 32 bit quantity from network to host byte ordering.
network to host order. @var{value} must be within the range of @var{value} is packed into 4 bytes, which are then converted
a C unsigned long integer. and returned as a new 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:
@ -2190,6 +2267,7 @@ If @var{locale} is omitted, return the current value of the
specified locale category as a system-dependent string. specified locale category as a system-dependent string.
@var{category} should be specified using the values @var{category} should be specified using the values
@code{LC_COLLATE}, @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 the string
@var{locale} and the new value is returned as a @var{locale} and the new value is returned as a
system-dependent string. If @var{locale} is an empty string, system-dependent string. If @var{locale} is an empty string,

110
doc/scheme-control.texi
View file

@ -409,8 +409,7 @@ more conveniently.
* Exception Terminology:: Different ways to say the same thing. * Exception Terminology:: Different ways to say the same thing.
* Catch:: Setting up to catch exceptions. * Catch:: Setting up to catch exceptions.
* Throw:: Throwing an exception. * Throw:: Throwing an exception.
* Lazy Catch:: Catch without unwinding. * Lazy Catch:: Catch without unwinding the stack.
* Stack Catch:: Capturing the stack at a throw.
* Exception Implementation:: How Guile implements exceptions. * Exception Implementation:: How Guile implements exceptions.
@end menu @end menu
@ -497,12 +496,16 @@ exceptions matching @var{key}. If thunk throws to the symbol
@lisp @lisp
(handler key args ...) (handler key args ...)
@end lisp @end lisp
@var{key} is a symbol or @code{#t}. @var{key} is a symbol or @code{#t}.
@var{thunk} takes no arguments. If @var{thunk} returns @var{thunk} takes no arguments. If @var{thunk} returns
normally, that is the return value of @code{catch}. normally, that is the return value of @code{catch}.
Handler is invoked outside the scope of its own @code{catch}. Handler is invoked outside the scope of its own @code{catch}.
If @var{handler} again throws to the same key, a new handler If @var{handler} again throws to the same key, a new handler
from further up the call chain is invoked. from further up the call chain is invoked.
If the key is @code{#t}, then a throw to @emph{any} symbol will If the key is @code{#t}, then a throw to @emph{any} symbol will
match this call to @code{catch}. match this call to @code{catch}.
@end deffn @end deffn
@ -546,7 +549,7 @@ Invoke the catch form matching @var{key}, passing @var{args} to the
@var{handler}. @var{handler}.
@var{key} is a symbol. It will match catches of the same symbol or of @var{key} is a symbol. It will match catches of the same symbol or of
#t. @code{#t}.
If there is no handler at all, Guile prints an error and then exits. If there is no handler at all, Guile prints an error and then exits.
@end deffn @end deffn
@ -596,26 +599,113 @@ expression.
@node Lazy Catch @node Lazy Catch
@subsection Catch Without Unwinding @subsection Catch Without Unwinding
A @dfn{lazy catch} is used in the same way as a normal @code{catch},
with @var{key}, @var{thunk} and @var{handler} arguments specifying the
exception type, normal case code and handler procedure, but differs in
two important respects.
@itemize
@item
The handler procedure is executed without unwinding the call stack from
the context of the @code{throw} expression that caused the handler to be
invoked.
@item
If the handler returns normally --- i.e. does not @emph{itself} throw an
exception --- then the @code{throw} expression returns normally to its
caller with the handler's value.
@end itemize
@deffn primitive lazy-catch key 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.
@end deffn @end deffn
The net result is that throwing an exception that is caught by a
@code{lazy-catch} is @emph{almost} equivalent to calling the
@code{lazy-catch}'s handler inline instead of each @code{throw}, and
then omitting the surrounding @code{lazy-catch}. In other words,
@lisp @lisp
(lazy-catch 'badex (lazy-catch 'key
(lambda () @dots{} (throw 'key args @dots{}) @dots{})
handler)
@end lisp
@noindent
is @emph{almost} equivalent to
@lisp
((lambda () @dots{} (handler 'key args @dots{}) @dots{}))
@end lisp
@noindent
But why only @emph{almost}? The difference is that with
@code{lazy-catch}, the dynamic context is unwound back to just outside
the @code{lazy-catch} expression before invoking the handler. (For an
introduction to what is meant by dynamic context, @xref{Dynamic Wind}.)
Then, if the handler @emph{itself} throws an exception, that exception
must be caught by some kind of @code{catch} (including perhaps another
@code{lazy-catch}) higher up the call stack. On the other hand, if the
handler returns normally, the dynamic context is wound back to that of
the @code{throw} expression before passing the handler's return value to
the continuation of the @code{throw}.
In most cases where @code{lazy-catch} is used, the handler does indeed
throw another exception, which is caught by a higher-level @code{catch}.
But this pattern is not mandatory, and it can be useful for the handler
to return normally. In the following example, the @code{lazy-catch}
handler is called twice and the results of the two calls added together.
@lisp
(lazy-catch 'foo
(lambda () (lambda ()
(+ (throw 'badex 1) (+ (throw 'foo 1)
(throw 'badex 2))) (throw 'foo 2)))
(lambda args (lambda args
(cadr args))) (cadr args)))
@result{} @result{}
3 3
@end lisp @end lisp
To see the point about dynamic context, consider the case where the
normal case thunk uses @code{with-fluids} (REFFIXME) to temporarily
change the value of a fluid:
@node Stack Catch @lisp
@subsection Capturing the Stack at a Throw (define f (make-fluid))
(fluid-set! f "top level value")
(define (handler . args)
(cons (fluid-ref f) args))
(lazy-catch 'foo
(lambda ()
(with-fluids ((f "local value"))
(throw 'foo)))
handler)
@result{}
("top level value" foo)
((lambda ()
(with-fluids ((f "local value"))
(handler 'foo))))
@result{}
("local value" foo)
@end lisp
@noindent
In the @code{lazy-catch} version, the unwinding of dynamic context
restores @code{f} to its value outside the @code{with-fluids} block
before the handler is invoked, so the handler's @code{(fluid-ref f)}
returns the external value.
@code{lazy-catch} is useful because it permits the implementation of
debuggers and other reflective programming tools that need to access the
state of the call stack at the exact point where an exception or an
error is thrown. For an example of this, see REFFIXME:stack-catch.
@node Exception Implementation @node Exception Implementation
@ -702,6 +792,7 @@ be reviewed]
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 of the @code{dynamic_wind} expression is escaped continuation of the @code{dynamic_wind} expression is escaped
non-locally, @var{out_guard} is called. If the continuation of non-locally, @var{out_guard} is called. If the continuation of
@ -718,15 +809,18 @@ 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:

29
doc/scheme-data.texi
View file

@ -943,6 +943,7 @@ Return the hyperbolic arctangent of @var{x}.
@deffn primitive logand n1 n2 @deffn primitive logand n1 n2
Return the integer which is the bit-wise AND of the two integer Return the integer which is the bit-wise AND of the two integer
arguments. arguments.
@lisp @lisp
(number->string (logand #b1100 #b1010) 2) (number->string (logand #b1100 #b1010) 2)
@result{} "1000" @result{} "1000"
@ -952,6 +953,7 @@ arguments.
@deffn primitive logior n1 n2 @deffn primitive logior n1 n2
Return the integer which is the bit-wise OR of the two integer Return the integer which is the bit-wise OR of the two integer
arguments. arguments.
@lisp @lisp
(number->string (logior #b1100 #b1010) 2) (number->string (logior #b1100 #b1010) 2)
@result{} "1110" @result{} "1110"
@ -961,6 +963,7 @@ arguments.
@deffn primitive logxor n1 n2 @deffn primitive logxor n1 n2
Return the integer which is the bit-wise XOR of the two integer Return the integer which is the bit-wise XOR of the two integer
arguments. arguments.
@lisp @lisp
(number->string (logxor #b1100 #b1010) 2) (number->string (logxor #b1100 #b1010) 2)
@result{} "110" @result{} "110"
@ -970,6 +973,7 @@ arguments.
@deffn primitive lognot n @deffn primitive lognot n
Return the integer which is the 2s-complement of the integer Return the integer which is the 2s-complement of the integer
argument. argument.
@lisp @lisp
(number->string (lognot #b10000000) 2) (number->string (lognot #b10000000) 2)
@result{} "-10000001" @result{} "-10000001"
@ -1007,8 +1011,10 @@ structure of @var{n}, but rather guarantees that the result
will always be rounded towards minus infinity. Therefore, the will always be rounded towards minus infinity. Therefore, the
results of ash and a corresponding bitwise shift will differ if results of ash and a corresponding bitwise shift will differ if
@var{n} is negative. @var{n} is negative.
Formally, the function returns an integer equivalent to Formally, the function returns an integer equivalent to
@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}. @code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
@lisp @lisp
(number->string (ash #b1 3) 2) @result{} "1000" (number->string (ash #b1 3) 2) @result{} "1000"
(number->string (ash #b1010 -1) 2) @result{} "101" (number->string (ash #b1010 -1) 2) @result{} "101"
@ -1020,6 +1026,7 @@ Return the number of bits in integer @var{n}. If integer is
positive, the 1-bits in its binary representation are counted. positive, the 1-bits in its binary representation are counted.
If negative, the 0-bits in its two's-complement binary If negative, the 0-bits in its two's-complement binary
representation are counted. If 0, 0 is returned. representation are counted. If 0, 0 is returned.
@lisp @lisp
(logcount #b10101010) (logcount #b10101010)
@result{} 4 @result{} 4
@ -1032,6 +1039,7 @@ representation are counted. If 0, 0 is returned.
@deffn primitive integer-length n @deffn primitive integer-length n
Return the number of bits neccessary to represent @var{n}. Return the number of bits neccessary to represent @var{n}.
@lisp @lisp
(integer-length #b10101010) (integer-length #b10101010)
@result{} 8 @result{} 8
@ -1045,6 +1053,7 @@ Return the number of bits neccessary to represent @var{n}.
@deffn primitive integer-expt n k @deffn primitive integer-expt n k
Return @var{n} raised to the non-negative integer exponent Return @var{n} raised to the non-negative integer exponent
@var{k}. @var{k}.
@lisp @lisp
(integer-expt 2 5) (integer-expt 2 5)
@result{} 32 @result{} 32
@ -1057,6 +1066,7 @@ Return @var{n} raised to the non-negative integer exponent
Return the integer composed of the @var{start} (inclusive) Return the integer composed of the @var{start} (inclusive)
through @var{end} (exclusive) bits of @var{n}. The through @var{end} (exclusive) bits of @var{n}. The
@var{start}th bit becomes the 0-th bit in the result. @var{start}th bit becomes the 0-th bit in the result.
@lisp @lisp
(number->string (bit-extract #b1101101010 0 4) 2) (number->string (bit-extract #b1101101010 0 4) 2)
@result{} "1010" @result{} "1010"
@ -1075,10 +1085,12 @@ Return a copy of the random state @var{state}.
@deffn primitive random n [state] @deffn primitive random n [state]
Return a number in [0,N). Return a number in [0,N).
Accepts a positive integer or real n and returns a Accepts a positive integer or real n and returns a
number of the same type between zero (inclusive) and number of the same type between zero (inclusive) and
N (exclusive). The values returned have a uniform N (exclusive). The values returned have a uniform
distribution. distribution.
The optional argument @var{state} must be of the type produced The optional argument @var{state} must be of the type produced
by @code{seed->random-state}. It defaults to the value of the by @code{seed->random-state}. It defaults to the value of the
variable @var{*random-state*}. This object is used to maintain variable @var{*random-state*}. This object is used to maintain
@ -1514,6 +1526,7 @@ return an unspecified value.
@deffn primitive substring-fill! str start end fill @deffn primitive substring-fill! str start end fill
Change every character in @var{str} between @var{start} and Change every character in @var{str} between @var{start} and
@var{end} to @var{fill}. @var{end} to @var{fill}.
@lisp @lisp
(define y "abcdefg") (define y "abcdefg")
(substring-fill! y 1 3 #\r) (substring-fill! y 1 3 #\r)
@ -1610,6 +1623,7 @@ ending in @code{-ci} ignore the character case when comparing strings.
Lexicographic equality predicate; return @code{#t} if the two Lexicographic equality predicate; return @code{#t} if the two
strings are the same length and contain the same characters in strings are the same length and contain the same characters in
the same positions, otherwise return @code{#f}. the same positions, otherwise return @code{#f}.
The procedure @code{string-ci=?} treats upper and lower case The procedure @code{string-ci=?} treats upper and lower case
letters as though they were the same character, but letters as though they were the same character, but
@code{string=?} treats upper and lower case as distinct @code{string=?} treats upper and lower case as distinct
@ -1689,6 +1703,7 @@ Return the index of the first occurrence of @var{chr} in
@var{to} limit the search to a portion of the string. This @var{to} limit the search to a portion of the string. This
procedure essentially implements the @code{index} or procedure essentially implements the @code{index} or
@code{strchr} functions from the C library. @code{strchr} functions from the C library.
@lisp @lisp
(string-index "weiner" #\e) (string-index "weiner" #\e)
@result{} 1 @result{} 1
@ -1706,6 +1721,7 @@ Like @code{string-index}, but search from the right of the
string rather than from the left. This procedure essentially string rather than from the left. This procedure essentially
implements the @code{rindex} or @code{strrchr} functions from implements the @code{rindex} or @code{strrchr} functions from
the C library. the C library.
@lisp @lisp
(string-rindex "weiner" #\e) (string-rindex "weiner" #\e)
@result{} 4 @result{} 4
@ -1763,6 +1779,7 @@ capitalized.
@deffn primitive string-capitalize! str @deffn primitive string-capitalize! str
Upcase the first character of every word in @var{str} Upcase the first character of every word in @var{str}
destructively and return @var{str}. destructively and return @var{str}.
@lisp @lisp
y @result{} "hello world" y @result{} "hello world"
(string-capitalize! y) @result{} "Hello World" (string-capitalize! y) @result{} "Hello World"
@ -1862,8 +1879,10 @@ Compile the regular expression described by @var{pat}, and
return the compiled regexp structure. If @var{pat} does not return the compiled regexp structure. If @var{pat} does not
describe a legal regular expression, @code{make-regexp} throws describe a legal regular expression, @code{make-regexp} throws
a @code{regular-expression-syntax} error. a @code{regular-expression-syntax} error.
The @var{flags} arguments change the behavior of the compiled The @var{flags} arguments change the behavior of the compiled
regular expression. The following flags may be supplied: regular expression. The following flags may be supplied:
@table @code @table @code
@item regexp/icase @item regexp/icase
Consider uppercase and lowercase letters to be the same when Consider uppercase and lowercase letters to be the same when
@ -2354,8 +2373,10 @@ letters in the non-standard case, but it is usually a bad idea
to create such symbols because in some implementations of to create such symbols because in some implementations of
Scheme they cannot be read as themselves. See Scheme they cannot be read as themselves. See
@code{symbol->string}. @code{symbol->string}.
The following examples assume that the implementation's The following examples assume that the implementation's
standard case is lower case: standard case is lower case:
@lisp @lisp
(eq? 'mISSISSIppi 'mississippi) @result{} #t (eq? 'mISSISSIppi 'mississippi) @result{} #t
(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"} (string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
@ -2383,8 +2404,10 @@ returned will be the same as the case in the string that was
passed to @code{string->symbol}. It is an error to apply passed to @code{string->symbol}. It is an error to apply
mutation procedures like @code{string-set!} to strings returned mutation procedures like @code{string-set!} to strings returned
by this procedure. by this procedure.
The following examples assume that the implementation's The following examples assume that the implementation's
standard case is lower case: standard case is lower case:
@lisp @lisp
(symbol->string 'flying-fish) @result{} "flying-fish" (symbol->string 'flying-fish) @result{} "flying-fish"
(symbol->string 'Martin) @result{} "martin" (symbol->string 'Martin) @result{} "martin"
@ -3804,11 +3827,13 @@ dimensions arranged in a different order. There must be one
@var{dim0}, @var{dim1}, @dots{} should be integers between 0 @var{dim0}, @var{dim1}, @dots{} should be integers between 0
and the rank of the array to be returned. Each integer in that and the rank of the array to be returned. Each integer in that
range must appear at least once in the argument list. range must appear at least once in the argument list.
The values of @var{dim0}, @var{dim1}, @dots{} correspond to The values of @var{dim0}, @var{dim1}, @dots{} correspond to
dimensions in the array to be returned, their positions in the dimensions in the array to be returned, their positions in the
argument list to dimensions of @var{array}. Several @var{dim}s argument list to dimensions of @var{array}. Several @var{dim}s
may have the same value, in which case the returned array will may have the same value, in which case the returned array will
have smaller rank than @var{array}. have smaller rank than @var{array}.
@lisp @lisp
(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d)) (transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))
(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d) (transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)
@ -4705,6 +4730,7 @@ function, but uses @var{hash} as a hash function and
that takes two arguments, a key to be hashed and a table size. that takes two arguments, a key to be hashed and a table size.
@code{assoc} must be an associator function, like @code{assoc}, @code{assoc} must be an associator function, like @code{assoc},
@code{assq} or @code{assv}. @code{assq} or @code{assv}.
By way of illustration, @code{hashq-ref table key} is By way of illustration, @code{hashq-ref table key} is
equivalent to @code{hashx-ref hashq assq table key}. equivalent to @code{hashx-ref hashq assq table key}.
@end deffn @end deffn
@ -4716,6 +4742,7 @@ function, but uses @var{hash} as a hash function and
that takes two arguments, a key to be hashed and a table size. that takes two arguments, a key to be hashed and a table size.
@code{assoc} must be an associator function, like @code{assoc}, @code{assoc} must be an associator function, like @code{assoc},
@code{assq} or @code{assv}. @code{assq} or @code{assv}.
By way of illustration, @code{hashq-set! table key} is By way of illustration, @code{hashq-set! table key} is
equivalent to @code{hashx-set! hashq assq table key}. equivalent to @code{hashx-set! hashq assq table key}.
@end deffn @end deffn
@ -4849,6 +4876,7 @@ unspecified.
@deffnx primitive list->vector l @deffnx primitive list->vector l
Return a newly allocated vector whose elements contain the Return a newly allocated vector whose elements contain the
given arguments. Analogous to @code{list}. given arguments. Analogous to @code{list}.
@lisp @lisp
(vector 'a 'b 'c) @result{} #(a b c) (vector 'a 'b 'c) @result{} #(a b c)
@end lisp @end lisp
@ -4858,6 +4886,7 @@ given arguments. Analogous to @code{list}.
@deffn primitive vector->list v @deffn primitive vector->list v
Return a newly allocated list of the objects contained in the Return a newly allocated list of the objects contained in the
elements of @var{vector}. elements of @var{vector}.
@lisp @lisp
(vector->list '#(dah dah didah)) @result{} (dah dah didah) (vector->list '#(dah dah didah)) @result{} (dah dah didah)
(list->vector '(dididit dah)) @result{} #(dididit dah) (list->vector '(dididit dah)) @result{} #(dididit dah)

2
doc/scheme-debug.texi
View file

@ -139,7 +139,7 @@ Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames, evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be otherwise the frames are taken from @var{obj} (which must be
either a debug object or a continuation). either a debug object or a continuation).
@var{args} must be a list if integers and specifies how the @var{args} must be a list of integers and specifies how the
resulting stack will be narrowed. resulting stack will be narrowed.
@end deffn @end deffn

2
doc/scheme-evaluation.texi
View file

@ -226,7 +226,7 @@ the current module.
@deffn primitive eval2 obj env_thunk @deffn primitive eval2 obj env_thunk
Evaluate @var{exp}, a Scheme expression, in the environment Evaluate @var{exp}, a Scheme expression, in the environment
designated by @var{lookup}, a symbol-lookup function." designated by @var{lookup}, a symbol-lookup function.
Do not use this version of eval, it does not play well Do not use this version of eval, it does not play well
with the module system. Use @code{eval} or with the module system. Use @code{eval} or
@code{primitive-eval} instead. @code{primitive-eval} instead.

9
doc/scheme-io.texi
View file

@ -249,6 +249,7 @@ open.
Sets the current position of @var{fd/port} to the integer Sets the current position of @var{fd/port} to the integer
@var{offset}, which is interpreted according to the value of @var{offset}, which is interpreted according to the value of
@var{whence}. @var{whence}.
One of the following variables should be supplied for One of the following variables should be supplied for
@var{whence}: @var{whence}:
@defvar SEEK_SET @defvar SEEK_SET
@ -262,6 +263,7 @@ 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 @code{lseek}. @var{port} may be a string port. call is @code{lseek}. @var{port} may be a string port.
The value returned is the new position in the file. This means The value returned is the new position in the file. This means
that the current position of a port can be obtained using: that the current position of a port can be obtained using:
@lisp @lisp
@ -272,6 +274,7 @@ that the current position of a port can be obtained using:
@deffn primitive ftell fd_port @deffn primitive ftell fd_port
Return an integer representing the current position of Return an integer representing the current position of
@var{fd/port}, measured from the beginning. Equivalent to: @var{fd/port}, measured from the beginning. Equivalent to:
@lisp @lisp
(seek port 0 SEEK_CUR) (seek port 0 SEEK_CUR)
@end lisp @end lisp
@ -378,6 +381,7 @@ otherwise, leave it in the input stream for the next read. If
specified, store data only into the substring of @var{str} specified, store data only into the substring of @var{str}
bounded by @var{start} and @var{end} (which default to the bounded by @var{start} and @var{end} (which default to the
beginning and end of the string, respectively). beginning and end of the string, respectively).
Return a pair consisting of the delimiter that terminated the Return a pair consisting of the delimiter that terminated the
string and the number of characters read. If reading stopped string and the number of characters read. If reading stopped
at the end of file, the delimiter returned is the at the end of file, the delimiter returned is the
@ -714,6 +718,7 @@ 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{pv} must be a vector of length 5. Its open-file}). @var{pv} must be a vector of length 5. Its
components 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
@ -726,14 +731,17 @@ 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 procedures. For an input-only port only elements 3 and 4 need
be procedures. Thunks 2 and 4 can instead be @code{#f} if be procedures. Thunks 2 and 4 can instead be @code{#f} if
there is no useful 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, eof-object?, ,r5rs, The Revised^5 Report on (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
Scheme}) it indicates that the port has reached end-of-file. Scheme}) it indicates that the port has reached end-of-file.
For example: For example:
@lisp @lisp
(define stdout (current-output-port)) (define stdout (current-output-port))
(define p (make-soft-port (define p (make-soft-port
@ -744,6 +752,7 @@ 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 lisp @end lisp
@end deffn @end deffn

221
doc/scheme-memory.texi
View file

@ -1,221 +0,0 @@
@page
@node Memory Management
@chapter Memory Management and Garbage Collection
@menu
* Garbage Collection::
* Weak References::
* Guardians::
@end menu
@node Garbage Collection
@section Garbage Collection
[FIXME: this is pasted in from Tom Lord's original guile.texi and should
be reviewed]
@deffn primitive gc
Scans all of SCM objects and reclaims for further use those that are
no longer accessible.
@end deffn
@deffn primitive gc-stats
Return an association list of statistics about Guile's current
use of storage.
@end deffn
@deffn primitive object-address obj
Return an integer that for the lifetime of @var{obj} is uniquely
returned by this function for @var{obj}
@end deffn
@deffn primitive unhash-name name
Flushes the glocs for @var{name}, or all glocs if @var{name}
is @code{#t}.
@end deffn
@node Weak References
@section Weak References
[FIXME: This chapter is based on Mikael Djurfeldt's answer to a question
by Michael Livshin. Any mistakes are not theirs, of course. ]
Weak references let you attach bookkeeping information to data so that
the additional information automatically disappears when the original
data is no longer in use and gets garbage collected. In a weak key hash,
the hash entry for that key disappears as soon as the key is no longer
referneced from anywhere else. For weak value hashes, the same happens
as soon as the value is no longer in use. Entries in a doubly weak hash
disappear when either the key or the value are not used anywhere else
anymore.
Property lists offer the same kind of functionality as weak key hashes
in many situations. (@pxref{Property Lists})
Here's an example (a little bit strained perhaps, but one of the
examples is actually used in Guile):
Assume that you're implementing a debugging system where you want to
associate information about filename and position of source code
expressions with the expressions themselves.
Hashtables can be used for that, but if you use ordinary hash tables
it will be impossible for the scheme interpreter to "forget" old
source when, for example, a file is reloaded.
To implement the mapping from source code expressions to positional
information it is necessary to use weak-key tables since we don't want
the expressions to be remembered just because they are in our table.
To implement a mapping from source file line numbers to source code
expressions you would use a weak-value table.
To implement a mapping from source code expressions to the procedures
they constitute a doubly-weak table has to be used.
@menu
* Weak key hashes::
* Weak vectors::
@end menu
@node Weak key hashes
@subsection Weak key hashes
@deffn primitive make-weak-key-hash-table size
@deffnx primitive make-weak-value-hash-table size
@deffnx primitive make-doubly-weak-hash-table size
Return a weak hash table with @var{size} buckets. As with any
hash table, choosing a good size for the table requires some
caution.
You can modify weak hash tables in exactly the same way you
would modify regular hash tables. (@pxref{Hash Tables})
@end deffn
@deffn primitive weak-key-hash-table? obj
@deffnx primitive weak-value-hash-table? obj
@deffnx primitive doubly-weak-hash-table? obj
Return @code{#t} if @var{obj} is the specified weak hash
table. Note that a doubly weak hash table is neither a weak key
nor a weak value hash table.
@end deffn
@deffn primitive make-weak-value-hash-table k
@end deffn
@deffn primitive weak-value-hash-table? x
@end deffn
@deffn primitive make-doubly-weak-hash-table k
@end deffn
@deffn primitive doubly-weak-hash-table? x
@end deffn
@node Weak vectors
@subsection Weak vectors
Weak vectors are mainly useful in Guile's implementation of weak hash
tables.
@deffn primitive make-weak-vector size [fill]
Return a weak vector with @var{size} elements. If the optional
argument @var{fill} is given, all entries in the vector will be
set to @var{fill}. The default value for @var{fill} is the
empty list.
@end deffn
@deffn primitive weak-vector . l
@deffnx primitive list->weak-vector l
Construct a weak vector from a list: @code{weak-vector} uses
the list of its arguments while @code{list->weak-vector} uses
its only argument @var{l} (a list) to construct a weak vector
the same way @code{list->vector} would.
@end deffn
@deffn primitive weak-vector? obj
Return @code{#t} if @var{obj} is a weak vector. Note that all
weak hashes are also weak vectors.
@end deffn
@node Guardians
@section Guardians
@deffn primitive make-guardian [greedy?]
Create a new guardian.
A guardian protects a set of objects from garbage collection,
allowing a program to apply cleanup or other actions.
@code{make-guardian} returns a procedure representing the guardian.
Calling the guardian procedure with an argument adds the
argument to the guardian's set of protected objects.
Calling the guardian procedure without an argument returns
one of the protected objects which are ready for garbage
collection, or @code{#f} if no such object is available.
Objects which are returned in this way are removed from
the guardian.
@code{make-guardian} takes one optional argument that says whether the
new guardian should be greedy or sharing. If there is any chance
that any object protected by the guardian may be resurrected,
then you should make the guardian greedy (this is the default).
See R. Kent Dybvig, Carl Bruggeman, and David Eby (1993)
"Guardians in a Generation-Based Garbage Collector".
ACM SIGPLAN Conference on Programming Language Design
and Implementation, June 1993.
(the semantics are slightly different at this point, but the
paper still (mostly) accurately describes the interface).
@end deffn
@deffn primitive destroy-guardian! guardian
Destroys @var{guardian}, by making it impossible to put any more
objects in it or get any objects from it. It also unguards any
objects guarded by @var{guardian}.
@end deffn
@deffn primitive guardian-greedy? guardian
Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
@end deffn
@deffn primitive guardian-destroyed? guardian
Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
@end deffn
@page
@node Objects
@chapter Objects
@deffn primitive entity? obj
Return @code{#t} if @var{obj} is an entity.
@end deffn
@deffn primitive operator? obj
Return @code{#t} if @var{obj} is an operator.
@end deffn
@deffn primitive set-object-procedure! obj proc
Return the object procedure of @var{obj} to @var{proc}.
@var{obj} must be either an entity or an operator.
@end deffn
@deffn primitive make-class-object metaclass layout
Create a new class object of class @var{metaclass}, with the
slot layout specified by @var{layout}.
@end deffn
@deffn primitive make-subclass-object class layout
Create a subclass object of @var{class}, with the slot layout
specified by @var{layout}.
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:

22
doc/scheme-modules.texi
View file

@ -99,7 +99,7 @@ to have access to all procedures and variables exported from the module.
* General Information about Modules:: Guile module basics. * General Information about Modules:: Guile module basics.
* Loading Guile Modules:: How to use existing modules. * Loading Guile Modules:: How to use existing modules.
* Creating Guile Modules:: How to package your code into modules. * Creating Guile Modules:: How to package your code into modules.
* More Module Procedures:: Low--level module code. * More Module Procedures:: Low-level module code.
* Included Guile Modules:: Which modules come with Guile? * Included Guile Modules:: Which modules come with Guile?
@end menu @end menu
@ -108,7 +108,7 @@ to have access to all procedures and variables exported from the module.
A Guile module is a collection of procedures, variables and syntactic A Guile module is a collection of procedures, variables and syntactic
forms (macros), which are either public or private. Public bindings are forms (macros), which are either public or private. Public bindings are
in the so--called @dfn{export list} of a module and can be made visible in the so-called @dfn{export list} of a module and can be made visible
to other modules, which import them. This @dfn{module import} is called to other modules, which import them. This @dfn{module import} is called
@dfn{using} of a module, and consists of loading of the module code (if @dfn{using} of a module, and consists of loading of the module code (if
it has not already been loaded) and making all exported items of the it has not already been loaded) and making all exported items of the
@ -132,7 +132,7 @@ example, the @code{(ice-9 popen)} module would result in the filename
Guile and in all other directories in the load path. Guile and in all other directories in the load path.
@c FIXME::martin: Not sure about this, maybe someone knows better? @c FIXME::martin: Not sure about this, maybe someone knows better?
Every module has a so--called syntax transformer associated with it. Every module has a so-called syntax transformer associated with it.
This is a procedure which performs all syntax transformation for the This is a procedure which performs all syntax transformation for the
time the module is read in and evaluated. When working with modules, time the module is read in and evaluated. When working with modules,
you can manipulate the current syntax transformer using the you can manipulate the current syntax transformer using the
@ -150,7 +150,7 @@ the expansion.
When two or more modules are imported, and they export bindings with the When two or more modules are imported, and they export bindings with the
same names, the last imported module wins, and the exported binding of same names, the last imported module wins, and the exported binding of
that last module will silently be used. This might lead to that last module will silently be used. This might lead to
hard--to--find errors because wrong procedures or variables are used. hard-to-find errors because wrong procedures or variables are used.
@node Loading Guile Modules @node Loading Guile Modules
@ -225,7 +225,7 @@ example of this is
@code{define-module} makes this module available to Guile programs under @code{define-module} makes this module available to Guile programs under
the given @var{module-specification}. the given @var{module-specification}.
The @var{options} are keyword/value--pairs which specify more about the The @var{options} are keyword/value pairs which specify more about the
defined module. The recognized options and their meaning is shown in defined module. The recognized options and their meaning is shown in
the following table. the following table.
@ -315,7 +315,7 @@ Mikael Djurfeldt's source-level debugging support for Guile
Guile's support for multi threaded execution (@pxref{Scheduling}). Guile's support for multi threaded execution (@pxref{Scheduling}).
@item (ice-9 rdelim) @item (ice-9 rdelim)
Line-- and character--delimited input (REFFIXME). Line- and character-delimited input (REFFIXME).
@item (ice-9 documentation) @item (ice-9 documentation)
Online documentation (REFFIXME). Online documentation (REFFIXME).
@ -327,26 +327,26 @@ Support for @code{and-let*} (REFFIXME).
Support for some additional string port procedures (REFFIXME). Support for some additional string port procedures (REFFIXME).
@item (srfi srfi-8) @item (srfi srfi-8)
Multiple--value handling with @code{receive} (REFFIXME). Multiple-value handling with @code{receive} (REFFIXME).
@item (srfi srfi-9) @item (srfi srfi-9)
Record definition with @code{define-record-type} (REFFIXME). Record definition with @code{define-record-type} (REFFIXME).
@item (srfi srfi-10) @item (srfi srfi-10)
Read--hash extension @code{#,()} (REFFIXME). Read hash extension @code{#,()} (REFFIXME).
@item (srfi srfi-11) @item (srfi srfi-11)
Multiple--value handling with @code{let-values} and @code{let-values*} Multiple-value handling with @code{let-values} and @code{let-values*}
(REFFIXME). (REFFIXME).
@item (srfi srfi-13) @item (srfi srfi-13)
String library (REFFIXME). String library (REFFIXME).
@item (srfi srfi-14) @item (srfi srfi-14)
Character--set library (REFFIXME). Character-set library (REFFIXME).
@item (srfi srfi-17) @item (srfi srfi-17)
Getter--with--setter support (REFFIXME). Getter-with-setter support (REFFIXME).
@item (ice-9 slib) @item (ice-9 slib)
This module contains hooks for using Aubrey Jaffer's portable Scheme This module contains hooks for using Aubrey Jaffer's portable Scheme

2
doc/scheme-procedures.texi
View file

@ -521,6 +521,7 @@ result of applying @var{code} to the expression and the
environment. The value returned from @var{code} which has been environment. The value returned from @var{code} which has been
passed to @code{procedure->memoizing-macro} replaces the form passed to @code{procedure->memoizing-macro} replaces the form
passed to @var{code}. For example: passed to @var{code}. For example:
@lisp @lisp
(define trace (define trace
(procedure->macro (procedure->macro
@ -537,6 +538,7 @@ result of applying @var{proc} to the expression and the
environment. The value returned from @var{proc} which has been environment. The value returned from @var{proc} which has been
passed to @code{procedure->memoizing-macro} replaces the form passed to @code{procedure->memoizing-macro} replaces the form
passed to @var{proc}. For example: passed to @var{proc}. For example:
@lisp @lisp
(define trace (define trace
(procedure->macro (procedure->macro

14
libguile/ChangeLog
View file

@ -1,3 +1,17 @@
2001-05-04 Neil Jerram <neil@ossau.uklinux.net>
* eval.c (scm_promise_p), list.c (scm_append_x, scm_reverse_x),
symbols.c (scm_symbol_to_string), vports.c (scm_make_soft_port):
Change R4RS references to R5RS.
* guile-snarf.awk.in: Fixes so that (i) blank lines in the
docstring source are correctly reproduced in the output (ii)
we don't anymore get occasional trailing quotes. Also reorganized
and commented the code a little.
* scmsigs.c (scm_raise), throw.c (scm_throw): Docstring format
fixes.
2001-05-04 Martin Grabmueller <mgrabmue@cs.tu-berlin.de> 2001-05-04 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
* strop.c (scm_string_split): New procedure. * strop.c (scm_string_split): New procedure.

2
libguile/eval.c
View file

@ -3809,7 +3809,7 @@ SCM_DEFINE (scm_force, "force", 1, 0, 0,
SCM_DEFINE (scm_promise_p, "promise?", 1, 0, 0, SCM_DEFINE (scm_promise_p, "promise?", 1, 0, 0,
(SCM obj), (SCM obj),
"Return true if @var{obj} is a promise, i.e. a delayed computation\n" "Return true if @var{obj} is a promise, i.e. a delayed computation\n"
"(@pxref{Delayed evaluation,,,r4rs.info,The Revised^4 Report on Scheme}).") "(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).")
#define FUNC_NAME s_scm_promise_p #define FUNC_NAME s_scm_promise_p
{ {
return SCM_BOOL (SCM_TYP16_PREDICATE (scm_tc16_promise, obj)); return SCM_BOOL (SCM_TYP16_PREDICATE (scm_tc16_promise, obj));

30
libguile/guile-snarf.awk.in
View file

@ -97,16 +97,34 @@ BEGIN { FS="|";
} }
/SCM_SNARF_DOCSTRING_START/,/SCM_SNARF_DOCSTRING_END.*$/ { copy = $0; /SCM_SNARF_DOCSTRING_START/,/SCM_SNARF_DOCSTRING_END.*$/ { copy = $0;
# Trim everything up to and including
# SCM_SNARF_DOCSTRING_START marker.
gsub(/.*SCM_SNARF_DOCSTRING_START/,"",copy); gsub(/.*SCM_SNARF_DOCSTRING_START/,"",copy);
sub(/^\#.*/,"", copy);
# Trim leading whitespace and opening quote.
sub(/^[ \t]*\"?/,"", copy); sub(/^[ \t]*\"?/,"", copy);
sub(/\"?[ \t]*SCM_SNARF_DOCSTRING_END.*$/,"", copy);
gsub(/\\n\\n\"?/,"\n",copy); # Trim closing quote and trailing whitespace, or
gsub(/\\n\"?[ \t]*$/,"",copy); # closing quote and whitespace followed by the
# SCM_SNARF_DOCSTRING_END marker.
sub(/[ \t]*\"?[ \t]*$/,"", copy);
sub(/[ \t]*\"?[ \t]*SCM_SNARF_DOCSTRING_END.*$/,"", copy);
# Replace escaped characters.
gsub(/\\n/,"\n",copy);
gsub(/\\\"/,"\"",copy); gsub(/\\\"/,"\"",copy);
gsub(/\\\\/,"\\",copy); gsub(/\\\\/,"\\",copy);
gsub(/[ \t]*$/,"", copy);
if (copy != "") { print copy > dot_doc_file } # Some docstrings end each line with "\n", while
# others don't. Therefore we always strip off one "\n"
# if present at the end of the line. Docstrings must
# therefore always use "\n\n" to indicate a blank line.
if (copy != "")
{
sub(/[ \t]*\n$/, "", copy);
print copy > dot_doc_file;
}
} }
/SCM_SNARF_DOCSTRING_END[ \t]*/ { print "@end deffn" >> dot_doc_file; } /SCM_SNARF_DOCSTRING_END[ \t]*/ { print "@end deffn" >> dot_doc_file; }

6
libguile/list.c
View file

@ -237,7 +237,7 @@ SCM_DEFINE (scm_append, "append", 0, 0, 1,
SCM_DEFINE (scm_append_x, "append!", 0, 0, 1, SCM_DEFINE (scm_append_x, "append!", 0, 0, 1,
(SCM lists), (SCM lists),
"A destructive version of @code{append} (@pxref{Pairs and\n" "A destructive version of @code{append} (@pxref{Pairs and\n"
"Lists,,,r4rs, The Revised^4 Report on Scheme}). The cdr field\n" "Lists,,,r5rs, The Revised^5 Report on Scheme}). The cdr field\n"
"of each list's final pair is changed to point to the head of\n" "of each list's final pair is changed to point to the head of\n"
"the next list, so no consing is performed. Return a pointer to\n" "the next list, so no consing is performed. Return a pointer to\n"
"the mutated list.") "the mutated list.")
@ -321,8 +321,8 @@ SCM_DEFINE (scm_reverse, "reverse", 1, 0, 0,
SCM_DEFINE (scm_reverse_x, "reverse!", 1, 1, 0, SCM_DEFINE (scm_reverse_x, "reverse!", 1, 1, 0,
(SCM lst, SCM new_tail), (SCM lst, SCM new_tail),
"A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs,\n" "A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r5rs,\n"
"The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is\n" "The Revised^5 Report on Scheme}). The cdr of each cell in @var{lst} is\n"
"modified to point to the previous list element. Return a pointer to the\n" "modified to point to the previous list element. Return a pointer to the\n"
"head of the reversed list.\n\n" "head of the reversed list.\n\n"
"Caveat: because the list is modified in place, the tail of the original\n" "Caveat: because the list is modified in place, the tail of the original\n"

1
libguile/scmsigs.c
View file

@ -470,7 +470,6 @@ SCM_DEFINE (scm_usleep, "usleep", 1, 0, 0,
SCM_DEFINE (scm_raise, "raise", 1, 0, 0, SCM_DEFINE (scm_raise, "raise", 1, 0, 0,
(SCM sig), (SCM sig),
"\n"
"Sends a specified signal @var{sig} to the current process, where\n" "Sends a specified signal @var{sig} to the current process, where\n"
"@var{sig} is as described for the kill procedure.") "@var{sig} is as described for the kill procedure.")
#define FUNC_NAME s_scm_raise #define FUNC_NAME s_scm_raise

2
libguile/symbols.c
View file

@ -430,7 +430,7 @@ SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0,
(SCM s), (SCM s),
"Return the name of @var{symbol} as a string. If the symbol was\n" "Return the name of @var{symbol} as a string. If the symbol was\n"
"part of an object returned as the value of a literal expression\n" "part of an object returned as the value of a literal expression\n"
"(section @pxref{Literal expressions,,,r4rs, The Revised^4\n" "(section @pxref{Literal expressions,,,r5rs, The Revised^5\n"
"Report on Scheme}) or by a call to the @code{read} procedure,\n" "Report on Scheme}) or by a call to the @code{read} procedure,\n"
"and its name contains alphabetic characters, then the string\n" "and its name contains alphabetic characters, then the string\n"
"returned will contain characters in the implementation's\n" "returned will contain characters in the implementation's\n"

2
libguile/throw.c
View file

@ -591,7 +591,7 @@ SCM_DEFINE (scm_throw, "throw", 1, 0, 1,
"Invoke the catch form matching @var{key}, passing @var{args} to the\n" "Invoke the catch form matching @var{key}, passing @var{args} to the\n"
"@var{handler}. \n\n" "@var{handler}. \n\n"
"@var{key} is a symbol. It will match catches of the same symbol or of\n" "@var{key} is a symbol. It will match catches of the same symbol or of\n"
"#t.\n\n" "@code{#t}.\n\n"
"If there is no handler at all, Guile prints an error and then exits.") "If there is no handler at all, Guile prints an error and then exits.")
#define FUNC_NAME s_scm_throw #define FUNC_NAME s_scm_throw
{ {

2
libguile/vports.c
View file

@ -171,7 +171,7 @@ SCM_DEFINE (scm_make_soft_port, "make-soft-port", 2, 0, 0,
"there is no useful operation for them to perform.\n" "there is no useful operation for them to perform.\n"
"\n" "\n"
"If thunk 3 returns @code{#f} or an @code{eof-object}\n" "If thunk 3 returns @code{#f} or an @code{eof-object}\n"
"(@pxref{Input, eof-object?, ,r4rs, The Revised^4 Report on\n" "(@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on\n"
"Scheme}) it indicates that the port has reached end-of-file.\n" "Scheme}) it indicates that the port has reached end-of-file.\n"
"For example:\n" "For example:\n"
"\n" "\n"