mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 03:40:34 +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>
* 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
child process. The need to flush the output port can be
avoided by making it unbuffered using @code{setvbuf}.
Writes occur atomically provided the size of the data in bytes
is not greater than the value of @code{PIPE_BUF}. Note that
the output port is likely to block if too much data (typically
@ -511,9 +512,11 @@ and the current process has the type of access specified by
using the values of the variables listed below. Multiple
values can be combined using a bitwise or, in which case
@code{#t} will only be returned if all accesses are granted.
Permissions are checked using the real id of the current
process, not the effective id, although it's the effective id
which determines whether the access would actually be granted.
@defvar R_OK
test for read permission.
@end defvar
@ -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
on a file (in which case @code{fstat} is used as the underlying
system call).
The object returned by @code{stat} can be passed as a single
parameter to the following procedures, all of which return
integers:
@table @code
@item stat:dev
The device containing the file.
@ -572,8 +577,10 @@ bytes.
The amount of disk space that the file occupies measured in
units of 512 byte blocks.
@end table
In addition, the following procedures return the information
from stat:mode in a more convenient form:
@table @code
@item stat:type
A symbol representing the type of file. Possible values are
@ -993,6 +1000,7 @@ reported by the following procedures.
Return an object with information about real and processor
time. The following procedures accept such an object as an
argument and return a selected component:
@table @code
@item tms:clock
The current real time, expressed as time units relative to an
@ -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
returned by @code{waitpid}, which can be interpreted using the
functions above.
If @code{system} is called without arguments, return a boolean
indicating whether the command processor is available.
@end deffn
@ -1475,6 +1484,7 @@ terminal for the current process.
Return the process group ID of the foreground process group
associated with the terminal open on the file descriptor
underlying @var{port}.
If there is no foreground process group, the return value is a
number greater than 1 that does not match the process group ID
of any existing process group. This can happen if all of the
@ -1546,24 +1556,27 @@ the database routines since they are not reentrant.
@subsubsection Address Conversion
@deffn primitive inet-aton address
Converts a string containing an Internet host address in the
traditional dotted decimal notation into an integer.
Convert an IPv4 Internet address from printable string
(dotted decimal notation) to an integer. E.g.,
@lisp
(inet-aton "127.0.0.1") @result{} 2130706433
@end lisp
@end deffn
@deffn primitive inet-ntoa inetid
Converts an integer Internet host address into a string with
the traditional dotted decimal representation.
Convert an IPv4 Internet address to a printable
(dotted decimal notation) string. E.g.,
@lisp
(inet-ntoa 2130706433) @result{} "127.0.0.1"
@end lisp
@end deffn
@deffn primitive inet-netof address
Return the network number part of the given integer Internet
address.
Return the network number part of the given IPv4
Internet address. E.g.,
@lisp
(inet-netof 2130706433) @result{} 127
@end lisp
@ -1571,21 +1584,52 @@ address.
@deffn primitive inet-lnaof address
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
(inet-lnaof 2130706433) @result{} 1
@end lisp
@end deffn
@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{lna}.
@var{lna}. E.g.,
@lisp
(inet-makeaddr 127 1) @result{} 2130706433
@end lisp
@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
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
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
@code{AF_UNIX}, @code{AF_INET} and @code{AF_INET6}.
Typical values for @var{style} are @code{SOCK_STREAM},
@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
protocol, which is usually right.
A single socket port cannot by used for communication until it
has been connected to another socket.
@end deffn
@deffn primitive socketpair family style proto
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}
family. Zero is likely to be the only meaningful value for
@var{protocol}.
@var{proto}.
@end deffn
@deffn primitive getsockopt sock level optname
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
socket-level options. @var{optname} is an integer code for the
option required and should be specified using one of the
symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.
The returned value is typically an integer but @code{SO_LINGER}
returns a pair of integers.
@end deffn
@deffn primitive setsockopt sock level optname value
Sets the value of a particular socket option for the socket
port @var{socket}. @var{level} is an integer code for type of option
Set the value of a particular socket option for the socket
port @var{sock}. @var{level} is an integer code for type of option
being set, e.g., @code{SOL_SOCKET} for socket-level options.
@var{optname} is an
integer code for the option to set and should be specified using one of
@ -1902,7 +1949,7 @@ The return value is unspecified.
@end deffn
@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
specified by @var{address} and possibly @var{args}.
The format required for @var{address}
@ -1926,24 +1973,25 @@ The return value is unspecified.
@end deffn
@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,
so they know where to look for incoming connections. A socket
without an address will be assigned one automatically when it
starts communicating.
The format of @var{address} and @var{ARG} @dots{} depends on the family
of the socket.
The format of @var{address} and @var{args} depends
on the family of the socket.
For a socket of family @code{AF_UNIX}, only @var{address} is specified
and must be a string with the filename where the socket is to be
created.
For a socket of family @code{AF_UNIX}, only @var{address}
is specified and must be a string with the filename where
the socket is to be created.
For a socket of family @code{AF_INET}, @var{address} must be an integer
Internet host address and @var{arg} @dots{} must be a single integer
port number.
For a socket of family @code{AF_INET}, @var{address}
must be an integer IPv4 address and @var{args}
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
Allow connections from any address.
@ -1961,33 +2009,40 @@ The broadcast address on the local network.
No address.
@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.
@end deffn
@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
the maximum length of the queue for pending connections.
If the queue fills, new clients will fail to connect until the
server calls @code{accept} to accept a connection from the queue.
If the queue fills, new clients will fail to connect until
the server calls @code{accept} to accept a connection from
the queue.
The return value is unspecified.
@end deffn
@deffn primitive accept sock
Accepts a connection on a bound, listening socket @var{socket}. If there
are no pending connections in the queue, it waits until
one is available unless the non-blocking option has been set on the
socket.
Accept a connection on a bound, listening socket.
If there
are no pending connections in the queue, wait until
one is available unless the non-blocking option has been
set on the socket.
The return value is a
pair in which the CAR is a new socket port for the connection and
the CDR is an object with address information about the client which
initiated the connection.
pair in which the @emph{car} is a new socket port for the
connection and
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{socket} does not become part of the
@var{sock} does not become part of the
connection and will continue to accept new requests.
@end deffn
@ -2010,79 +2065,101 @@ number.
@end table
@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
of a socket in the @code{AF_FILE} namespace cannot be read.
@end deffn
@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
@code{accept}. On many systems the address of a socket in the
@code{AF_FILE} namespace cannot be read.
@end deffn
@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.
@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
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.
The optional @var{flags} argument is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
The value returned is the number of bytes read from the socket.
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.
@end deffn
@deffn primitive send sock message [flags]
Transmits the string @var{message} on the socket port @var{socket}.
@var{socket} must already be bound to a destination address. The
value returned is the number of bytes transmitted -- it's possible for
this to be less than the length of @var{message} if the socket is
set to be non-blocking. The optional @var{flags} argument is a value or
Transmit the string @var{message} on a socket port @var{sock}.
@var{sock} must already be bound to a destination address. The
value returned is the number of bytes transmitted --
it's possible for
this to be less than the length of @var{message}
if the socket is
set to be non-blocking. The optional @var{flags} argument
is a value or
bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.
Note that the data is written directly to the socket file descriptor:
Note that the data is written directly to the socket
file descriptor:
any unflushed buffered port data is ignored.
@end deffn
@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.
@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 will be written. The size of @var{str} limits the amount
of data which can be received: in the case of packet protocols,
if a packet larger than this limit is encountered then some
data will be irrevocably lost.
The optional @var{flags} argument is a value or bitwise OR of
@code{MSG_OOB}, @code{MSG_PEEK}, @code{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
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
@var{str} to which the data should be written.
Note that the data is read directly from the socket file
descriptor: any unread buffered port data is ignored.
@end deffn
@deffn primitive sendto sock message fam address . args_and_flags
Transmits the string @var{message} on the socket port @var{socket}. The
destination address is specified using the @var{family}, @var{address} and
@var{arg} arguments, in a similar way to the @code{connect}
procedure. The
value returned is the number of bytes transmitted -- it's possible for
this to be less than the length of @var{message} if the socket is
set to be non-blocking. The optional @var{flags} argument is a value or
Transmit the string @var{message} on the socket port
@var{sock}. The
destination address is specified using the @var{fam},
@var{address} and
@var{args_and_flags} arguments, in a similar way to the
@code{connect} procedure. @var{args_and_flags} contains
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.
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.
@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
be done when sending or receiving encoded integer data from the network.
@deffn primitive htons in
Return a new integer from @var{value} by converting from host
to network order. @var{value} must be within the range of a C
unsigned short integer.
@deffn primitive htons value
Convert a 16 bit quantity from host to network byte ordering.
@var{value} is packed into 2 bytes, which are then converted
and returned as a new integer.
@end deffn
@deffn primitive ntohs in
Return a new integer from @var{value} by converting from
network to host order. @var{value} must be within the range of
a C unsigned short integer.
@deffn primitive ntohs value
Convert a 16 bit quantity from network to host byte ordering.
@var{value} is packed into 2 bytes, which are then converted
and returned as a new integer.
@end deffn
@deffn primitive htonl in
Return a new integer from @var{value} by converting from host
to network order. @var{value} must be within the range of a C
unsigned long integer.
@deffn primitive htonl value
Convert a 32 bit quantity from host to network byte ordering.
@var{value} is packed into 4 bytes, which are then converted
and returned as a new integer.
@end deffn
@deffn primitive ntohl in
Return a new integer from @var{value} by converting from
network to host order. @var{value} must be within the range of
a C unsigned long integer.
@deffn primitive ntohl value
Convert a 32 bit quantity from network to host byte ordering.
@var{value} is packed into 4 bytes, which are then converted
and returned as a new integer.
@end deffn
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.
@var{category} should be specified using the values
@code{LC_COLLATE}, @code{LC_ALL} etc.
Otherwise the specified locale category is set to the string
@var{locale} and the new value is returned as a
system-dependent string. If @var{locale} is an empty string,

112
doc/scheme-control.texi
View file

@ -409,8 +409,7 @@ more conveniently.
* Exception Terminology:: Different ways to say the same thing.
* Catch:: Setting up to catch exceptions.
* Throw:: Throwing an exception.
* Lazy Catch:: Catch without unwinding.
* Stack Catch:: Capturing the stack at a throw.
* Lazy Catch:: Catch without unwinding the stack.
* Exception Implementation:: How Guile implements exceptions.
@end menu
@ -497,12 +496,16 @@ exceptions matching @var{key}. If thunk throws to the symbol
@lisp
(handler key args ...)
@end lisp
@var{key} is a symbol or @code{#t}.
@var{thunk} takes no arguments. If @var{thunk} returns
normally, that is the return value of @code{catch}.
Handler is invoked outside the scope of its own @code{catch}.
If @var{handler} again throws to the same key, a new handler
from further up the call chain is invoked.
If the key is @code{#t}, then a throw to @emph{any} symbol will
match this call to @code{catch}.
@end deffn
@ -543,10 +546,10 @@ for that kind of exception.
@deffn primitive throw key . args
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
#t.
@code{#t}.
If there is no handler at all, Guile prints an error and then exits.
@end deffn
@ -596,26 +599,113 @@ expression.
@node Lazy Catch
@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
This behaves exactly like @code{catch}, except that it does
not unwind the stack (this is the major difference), and if
handler returns, its value is returned from the throw.
@end deffn
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
(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 ()
(+ (throw 'badex 1)
(throw 'badex 2)))
(+ (throw 'foo 1)
(throw 'foo 2)))
(lambda args
(cadr args)))
@result{}
3
@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
@subsection Capturing the Stack at a Throw
@lisp
(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
@ -702,6 +792,7 @@ be reviewed]
All three arguments must be 0-argument procedures.
@var{in_guard} is called, then @var{thunk}, then
@var{out_guard}.
If, any time during the execution of @var{thunk}, the
continuation of the @code{dynamic_wind} expression is escaped
non-locally, @var{out_guard} is called. If the continuation of
@ -718,15 +809,18 @@ times.
;; in-guard:
;;
(lambda () (set! x 'special-binding))
;; thunk
;;
(lambda () (display x) (newline)
(call-with-current-continuation escape)
(display x) (newline)
x)
;; out-guard:
;;
(lambda () (set! x old-x)))))))
;; Prints:
special-binding
;; Evaluates to:

29
doc/scheme-data.texi
View file

@ -943,6 +943,7 @@ Return the hyperbolic arctangent of @var{x}.
@deffn primitive logand n1 n2
Return the integer which is the bit-wise AND of the two integer
arguments.
@lisp
(number->string (logand #b1100 #b1010) 2)
@result{} "1000"
@ -952,6 +953,7 @@ arguments.
@deffn primitive logior n1 n2
Return the integer which is the bit-wise OR of the two integer
arguments.
@lisp
(number->string (logior #b1100 #b1010) 2)
@result{} "1110"
@ -961,6 +963,7 @@ arguments.
@deffn primitive logxor n1 n2
Return the integer which is the bit-wise XOR of the two integer
arguments.
@lisp
(number->string (logxor #b1100 #b1010) 2)
@result{} "110"
@ -970,6 +973,7 @@ arguments.
@deffn primitive lognot n
Return the integer which is the 2s-complement of the integer
argument.
@lisp
(number->string (lognot #b10000000) 2)
@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
results of ash and a corresponding bitwise shift will differ if
@var{n} is negative.
Formally, the function returns an integer equivalent to
@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.
@lisp
(number->string (ash #b1 3) 2) @result{} "1000"
(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.
If negative, the 0-bits in its two's-complement binary
representation are counted. If 0, 0 is returned.
@lisp
(logcount #b10101010)
@result{} 4
@ -1032,6 +1039,7 @@ representation are counted. If 0, 0 is returned.
@deffn primitive integer-length n
Return the number of bits neccessary to represent @var{n}.
@lisp
(integer-length #b10101010)
@result{} 8
@ -1045,6 +1053,7 @@ Return the number of bits neccessary to represent @var{n}.
@deffn primitive integer-expt n k
Return @var{n} raised to the non-negative integer exponent
@var{k}.
@lisp
(integer-expt 2 5)
@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)
through @var{end} (exclusive) bits of @var{n}. The
@var{start}th bit becomes the 0-th bit in the result.
@lisp
(number->string (bit-extract #b1101101010 0 4) 2)
@result{} "1010"
@ -1075,10 +1085,12 @@ Return a copy of the random state @var{state}.
@deffn primitive random n [state]
Return a number in [0,N).
Accepts a positive integer or real n and returns a
number of the same type between zero (inclusive) and
N (exclusive). The values returned have a uniform
distribution.
The optional argument @var{state} must be of the type produced
by @code{seed->random-state}. It defaults to the value of the
variable @var{*random-state*}. This object is used to maintain
@ -1514,6 +1526,7 @@ return an unspecified value.
@deffn primitive substring-fill! str start end fill
Change every character in @var{str} between @var{start} and
@var{end} to @var{fill}.
@lisp
(define y "abcdefg")
(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
strings are the same length and contain the same characters in
the same positions, otherwise return @code{#f}.
The procedure @code{string-ci=?} treats upper and lower case
letters as though they were the same character, but
@code{string=?} treats upper and lower case as distinct
@ -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
procedure essentially implements the @code{index} or
@code{strchr} functions from the C library.
@lisp
(string-index "weiner" #\e)
@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
implements the @code{rindex} or @code{strrchr} functions from
the C library.
@lisp
(string-rindex "weiner" #\e)
@result{} 4
@ -1763,6 +1779,7 @@ capitalized.
@deffn primitive string-capitalize! str
Upcase the first character of every word in @var{str}
destructively and return @var{str}.
@lisp
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
describe a legal regular expression, @code{make-regexp} throws
a @code{regular-expression-syntax} error.
The @var{flags} arguments change the behavior of the compiled
regular expression. The following flags may be supplied:
@table @code
@item regexp/icase
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
Scheme they cannot be read as themselves. See
@code{symbol->string}.
The following examples assume that the implementation's
standard case is lower case:
@lisp
(eq? 'mISSISSIppi 'mississippi) @result{} #t
(string->symbol "mISSISSIppi") @result{} @r{the symbol with name "mISSISSIppi"}
@ -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
mutation procedures like @code{string-set!} to strings returned
by this procedure.
The following examples assume that the implementation's
standard case is lower case:
@lisp
(symbol->string 'flying-fish) @result{} "flying-fish"
(symbol->string 'Martin) @result{} "martin"
@ -3804,11 +3827,13 @@ dimensions arranged in a different order. There must be one
@var{dim0}, @var{dim1}, @dots{} should be integers between 0
and the rank of the array to be returned. Each integer in that
range must appear at least once in the argument list.
The values of @var{dim0}, @var{dim1}, @dots{} correspond to
dimensions in the array to be returned, their positions in the
argument list to dimensions of @var{array}. Several @var{dim}s
may have the same value, in which case the returned array will
have smaller rank than @var{array}.
@lisp
(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)
@ -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.
@code{assoc} must be an associator function, like @code{assoc},
@code{assq} or @code{assv}.
By way of illustration, @code{hashq-ref table key} is
equivalent to @code{hashx-ref hashq assq table key}.
@end deffn
@ -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.
@code{assoc} must be an associator function, like @code{assoc},
@code{assq} or @code{assv}.
By way of illustration, @code{hashq-set! table key} is
equivalent to @code{hashx-set! hashq assq table key}.
@end deffn
@ -4849,6 +4876,7 @@ unspecified.
@deffnx primitive list->vector l
Return a newly allocated vector whose elements contain the
given arguments. Analogous to @code{list}.
@lisp
(vector 'a 'b 'c) @result{} #(a b c)
@end lisp
@ -4858,6 +4886,7 @@ given arguments. Analogous to @code{list}.
@deffn primitive vector->list v
Return a newly allocated list of the objects contained in the
elements of @var{vector}.
@lisp
(vector->list '#(dah dah didah)) @result{} (dah dah didah)
(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,
otherwise the frames are taken from @var{obj} (which must be
either a debug object or a continuation).
@var{args} must be a list if integers and specifies how the
@var{args} must be a list of integers and specifies how the
resulting stack will be narrowed.
@end deffn

2
doc/scheme-evaluation.texi
View file

@ -226,7 +226,7 @@ the current module.
@deffn primitive eval2 obj env_thunk
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
with the module system. Use @code{eval} or
@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
@var{offset}, which is interpreted according to the value of
@var{whence}.
One of the following variables should be supplied for
@var{whence}:
@defvar SEEK_SET
@ -262,6 +263,7 @@ Seek from the end of the file.
@end defvar
If @var{fd/port} is a file descriptor, the underlying system
call is @code{lseek}. @var{port} may be a string port.
The value returned is the new position in the file. This means
that the current position of a port can be obtained using:
@lisp
@ -272,6 +274,7 @@ that the current position of a port can be obtained using:
@deffn primitive ftell fd_port
Return an integer representing the current position of
@var{fd/port}, measured from the beginning. Equivalent to:
@lisp
(seek port 0 SEEK_CUR)
@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}
bounded by @var{start} and @var{end} (which default to the
beginning and end of the string, respectively).
Return a pair consisting of the delimiter that terminated the
string and the number of characters read. If reading stopped
at the end of file, the delimiter returned is the
@ -714,6 +718,7 @@ Return a port capable of receiving or delivering characters as
specified by the @var{modes} string (@pxref{File Ports,
open-file}). @var{pv} must be a vector of length 5. Its
components are as follows:
@enumerate 0
@item
procedure accepting one character for output
@ -726,14 +731,17 @@ thunk for getting one character
@item
thunk for closing port (not by garbage collection)
@end enumerate
For an output-only port only elements 0, 1, 2, and 4 need be
procedures. For an input-only port only elements 3 and 4 need
be procedures. Thunks 2 and 4 can instead be @code{#f} if
there is no useful operation for them to perform.
If thunk 3 returns @code{#f} or an @code{eof-object}
(@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
Scheme}) it indicates that the port has reached end-of-file.
For example:
@lisp
(define stdout (current-output-port))
(define p (make-soft-port
@ -744,6 +752,7 @@ For example:
(lambda () (char-upcase (read-char)))
(lambda () (display "@@" stdout)))
"rw"))
(write p p) @result{} #<input-output: soft 8081e20>
@end lisp
@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.
* Loading Guile Modules:: How to use existing 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?
@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
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
@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
@ -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.
@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
time the module is read in and evaluated. When working with modules,
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
same names, the last imported module wins, and the exported binding of
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
@ -225,7 +225,7 @@ example of this is
@code{define-module} makes this module available to Guile programs under
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
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}).
@item (ice-9 rdelim)
Line-- and character--delimited input (REFFIXME).
Line- and character-delimited input (REFFIXME).
@item (ice-9 documentation)
Online documentation (REFFIXME).
@ -327,26 +327,26 @@ Support for @code{and-let*} (REFFIXME).
Support for some additional string port procedures (REFFIXME).
@item (srfi srfi-8)
Multiple--value handling with @code{receive} (REFFIXME).
Multiple-value handling with @code{receive} (REFFIXME).
@item (srfi srfi-9)
Record definition with @code{define-record-type} (REFFIXME).
@item (srfi srfi-10)
Read--hash extension @code{#,()} (REFFIXME).
Read hash extension @code{#,()} (REFFIXME).
@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).
@item (srfi srfi-13)
String library (REFFIXME).
@item (srfi srfi-14)
Character--set library (REFFIXME).
Character-set library (REFFIXME).
@item (srfi srfi-17)
Getter--with--setter support (REFFIXME).
Getter-with-setter support (REFFIXME).
@item (ice-9 slib)
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
passed to @code{procedure->memoizing-macro} replaces the form
passed to @var{code}. For example:
@lisp
(define trace
(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
passed to @code{procedure->memoizing-macro} replaces the form
passed to @var{proc}. For example:
@lisp
(define trace
(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>
* 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 obj),
"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
{
return SCM_BOOL (SCM_TYP16_PREDICATE (scm_tc16_promise, obj));

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

@ -96,17 +96,35 @@ BEGIN { FS="|";
print "@deffn primitive " nicer_function_proto > dot_doc_file;
}
/SCM_SNARF_DOCSTRING_START/,/SCM_SNARF_DOCSTRING_END.*$/ { copy = $0;
gsub(/.*SCM_SNARF_DOCSTRING_START/,"",copy);
sub(/^\#.*/,"", copy);
sub(/^[ \t]*\"?/,"", copy);
sub(/\"?[ \t]*SCM_SNARF_DOCSTRING_END.*$/,"", copy);
gsub(/\\n\\n\"?/,"\n",copy);
gsub(/\\n\"?[ \t]*$/,"",copy);
gsub(/\\\"/,"\"",copy);
gsub(/\\\\/,"\\",copy);
gsub(/[ \t]*$/,"", copy);
if (copy != "") { print copy > dot_doc_file }
/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);
# Trim leading whitespace and opening quote.
sub(/^[ \t]*\"?/,"", copy);
# Trim closing quote and trailing whitespace, or
# 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);
# 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; }

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 lists),
"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"
"the next list, so no consing is performed. Return a pointer to\n"
"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 lst, SCM new_tail),
"A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r4rs,\n"
"The Revised^4 Report on Scheme}). The cdr of each cell in @var{lst} is\n"
"A destructive version of @code{reverse} (@pxref{Pairs and Lists,,,r5rs,\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"
"head of the reversed list.\n\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 sig),
"\n"
"Sends a specified signal @var{sig} to the current process, where\n"
"@var{sig} is as described for the kill procedure.")
#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),
"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"
"(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"
"and its name contains alphabetic characters, then the string\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"
"@var{handler}. \n\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.")
#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"
"\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"
"For example:\n"
"\n"