mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-06 12:10:28 +02:00
Code Activity

* Adding C function declarations from the SCM interface to the

Browse source 
reference manual documentation.
This commit is contained in:
Neil Jerram 2001-11-16 15:04:17 +00:00
parent cecb4a5e9d
commit 8f85c0c6c3
49 changed files with 3570 additions and 2271 deletions
Download patch file Download diff file Expand all files Collapse all files

9
doc/maint/ChangeLog
View file

@ -1,3 +1,12 @@
2001-11-16 Neil Jerram <neil@ossau.uklinux.net>
* guile.texi: Replaced by regenerated libguile version.
* docstring.el (make-module-description-list): Exclude @deffn's
with category {C Function}.
(docstring-process-alist): Bind key "d" to
docstring-ediff-this-line in the docstring output buffer.
2001-11-13 Neil Jerram <neil@ossau.uklinux.net>
* guile.texi: Replaced by libguile version (after automatically

30
doc/maint/docstring.el
View file

@ -217,19 +217,22 @@ to which new docstrings should be added.")
(match-end 1))))
(if (string-equal matched "@c module ")
(setq module (read (current-buffer)))
(setq matched
(concat (buffer-substring (match-beginning 2)
(match-end 2))
" "
(buffer-substring (match-beginning 3)
(match-end 3))))
(message "Found docstring: %S: %s" module matched)
(let ((descriptions (assoc module alist)))
(setq alist
(cons (cons module (cons matched (cdr-safe descriptions)))
(if descriptions
(delete descriptions alist)
alist))))))))
(let ((type (buffer-substring (match-beginning 2)
(match-end 2))))
(if (string-equal type "{C Function}")
nil
(setq matched
(concat type
" "
(buffer-substring (match-beginning 3)
(match-end 3))))
(message "Found docstring: %S: %s" module matched)
(let ((descriptions (assoc module alist)))
(setq alist
(cons (cons module (cons matched (cdr-safe descriptions)))
(if descriptions
(delete descriptions alist)
alist))))))))))
alist))
;; Return the docstring from the specified LOCATION. LOCATION is a
@ -428,6 +431,7 @@ new snarfed docstring file.\n\n")
(insert "\n")
(goto-char (point-min))
(local-set-key "d" 'docstring-ediff-this-line)
;; Popup the issues buffer.
(let ((pop-up-frames t))

2242
doc/maint/guile.texi
View file

File diff suppressed because it is too large Load diff

16
doc/ref/ChangeLog
View file

@ -1,3 +1,19 @@
2001-11-16 Neil Jerram <neil@ossau.uklinux.net>
* debugging.texi, deprecated.texi, intro.texi, misc-modules.texi,
new-docstrings.texi, posix.texi, scheme-binding.texi,
scheme-control.texi, scheme-data.texi, scheme-debug.texi,
scheme-evaluation.texi, scheme-io.texi, scheme-memory.texi,
scheme-modules.texi, scheme-options.texi, scheme-procedures.texi,
scheme-scheduling.texi, scheme-translation.texi,
scheme-utility.texi, script-getopt.texi, srfi-modules.texi: Change
category for "primitive" and "procedure" @deffn's to {Scheme
Procedure}; add @deffnx lines for {C Function}s; automatic updates
from libguile docstring changes.
* scheme-memory.texi (Garbage Collection): Removed doc for removed
`unhash-name'.
2001-11-14 Thien-Thi Nguyen <ttn@glug.org>
* scheme-procedures.texi: Spell "library" correctly.

34
doc/ref/debugging.texi
View file

@ -117,11 +117,11 @@ function calls, each of which is called a @dfn{frame}. The programmer
can learn more about the program's state at the point of interruption by
inspecting and modifying these frames.
@deffn primitive stack? obj
@deffn {Scheme Procedure} stack? obj
Return @code{#t} if @var{obj} is a calling stack.
@end deffn
@deffn primitive make-stack
@deffn {Scheme Procedure} make-stack
@end deffn
@deffn syntax start-stack id exp
@ -132,48 +132,48 @@ way of artificially limiting backtraces and stack procedures, largely as
a convenience to the user.
@end deffn
@deffn primitive stack-id stack
@deffn {Scheme Procedure} stack-id stack
Return the identifier given to @var{stack} by @code{start-stack}.
@end deffn
@deffn primitive stack-ref
@deffn {Scheme Procedure} stack-ref
@end deffn
@deffn primitive stack-length
@deffn {Scheme Procedure} stack-length
@end deffn
@deffn primitive frame?
@deffn {Scheme Procedure} frame?
@end deffn
@deffn primitive last-stack-frame
@deffn {Scheme Procedure} last-stack-frame
@end deffn
@deffn primitive frame-number
@deffn {Scheme Procedure} frame-number
@end deffn
@deffn primitive frame-source
@deffn {Scheme Procedure} frame-source
@end deffn
@deffn primitive frame-procedure
@deffn {Scheme Procedure} frame-procedure
@end deffn
@deffn primitive frame-arguments
@deffn {Scheme Procedure} frame-arguments
@end deffn
@deffn primitive frame-previous
@deffn {Scheme Procedure} frame-previous
@end deffn
@deffn primitive frame-next
@deffn {Scheme Procedure} frame-next
@end deffn
@deffn primitive frame-real?
@deffn {Scheme Procedure} frame-real?
@end deffn
@deffn primitive frame-procedure?
@deffn {Scheme Procedure} frame-procedure?
@end deffn
@deffn primitive frame-evaluating-args?
@deffn {Scheme Procedure} frame-evaluating-args?
@end deffn
@deffn primitive frame-overflow
@deffn {Scheme Procedure} frame-overflow
@end deffn

4
doc/ref/deprecated.texi
View file

@ -38,7 +38,7 @@ substring is an object that mostly behaves just like an ordinary
substring, except that it actually shares storage space with its parent
string.
@deffn primitive make-shared-substring str [start [end]]
@deffn {Scheme Procedure} make-shared-substring str [start [end]]
Return a shared substring of @var{str}. The arguments are the
same as for the @code{substring} function: the shared substring
returned includes all of the text from @var{str} between
@ -132,7 +132,7 @@ now require strings:
ERROR: Wrong type argument (expecting STRINGP): /home/
@end lisp
@deffn primitive read-only-string? obj
@deffn {Scheme Procedure} read-only-string? obj
Return @code{#t} if @var{obj} is either a string or a symbol,
otherwise return @code{#f}.
@end deffn

6
doc/ref/intro.texi
View file

@ -1,4 +1,4 @@
@c $Id: intro.texi,v 1.3 2001-11-11 15:01:51 ossau Exp $
@c $Id: intro.texi,v 1.4 2001-11-16 15:04:16 ossau Exp $
@page
@ -200,8 +200,8 @@ As another example, here is a simple replacement for the POSIX
(newline)
@end example
@deffn procedure command-line
@deffnx primitive program-arguments
@deffn {Scheme Procedure} command-line
@deffnx {Scheme Procedure} program-arguments
Return a list of the command-line arguments passed to the currently
running program. If the program invoked Guile with the @samp{-s},
@samp{-c} or @samp{--} switches, these procedures ignore everything up

4
doc/ref/misc-modules.texi
View file

@ -30,7 +30,7 @@ how @code{pretty-print} will format the output, see the following:
(else (if (= x 1) 2 (* x x x))))))
@end lisp
@deffn procedure pretty-print obj [port]
@deffn {Scheme Procedure} pretty-print obj [port]
Print the textual representation of the Scheme object @var{obj} to
@var{port}. @var{port} defaults to the current output port, if not
given.
@ -76,7 +76,7 @@ The @code{format} procedure, to be found in module @code{(ice-9
format)}, can do all this, and even more. If you are a C programmer,
you can think of this procedure as Guile's @code{fprintf}.
@deffn procedure format destination format-string args @dots{}
@deffn {Scheme Procedure} format destination format-string args @dots{}
The first parameter is the @var{destination}, it determines where the
output of @code{format} will go.

267
doc/ref/new-docstrings.texi
View file

@ -1,23 +1,27 @@
@c module (guile)
@deffn primitive environment? obj
@deffn {Scheme Procedure} environment? obj
@deffnx {C Function} scm_environment_p (obj)
Return @code{#t} if @var{obj} is an environment, or @code{#f}
otherwise.
@end deffn
@deffn primitive environment-bound? env sym
@deffn {Scheme Procedure} environment-bound? env sym
@deffnx {C Function} scm_environment_bound_p (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
@deffn {Scheme Procedure} environment-ref env sym
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} environment-fold env proc init
@deffnx {C Function} scm_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
@ -51,7 +55,8 @@ using environment-fold:
@end lisp
@end deffn
@deffn primitive environment-define env sym val
@deffn {Scheme Procedure} environment-define env sym val
@deffnx {C Function} scm_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
@ -61,7 +66,8 @@ 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
@deffn {Scheme Procedure} environment-undefine env sym
@deffnx {C Function} scm_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.
@ -69,7 +75,8 @@ 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
@deffn {Scheme Procedure} environment-set! env sym val
@deffnx {C Function} scm_environment_set_x (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.
@ -79,7 +86,8 @@ to an immutable location, signal an
@code{environment:immutable-location} error.
@end deffn
@deffn primitive environment-cell env sym for_write
@deffn {Scheme Procedure} environment-cell env sym for_write
@deffnx {C Function} scm_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
@ -94,7 +102,8 @@ If you use this function, you should consider using
re-bound to a new value cell, or becomes undefined.
@end deffn
@deffn primitive environment-observe env proc
@deffn {Scheme Procedure} environment-observe env proc
@deffnx {C Function} scm_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
@ -103,7 +112,8 @@ of procedures observing @var{env}. The type and value of
token is unspecified.
@end deffn
@deffn primitive environment-observe-weak env proc
@deffn {Scheme Procedure} environment-observe-weak env proc
@deffnx {C Function} scm_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,
@ -112,7 +122,8 @@ garbage-collected, and dropped from @var{env}'s
list of observing procedures.
@end deffn
@deffn primitive environment-unobserve token
@deffn {Scheme Procedure} environment-unobserve token
@deffnx {C Function} scm_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
@ -121,18 +132,21 @@ will cause @var{proc} to no longer be called when @var{env}'s
bindings change.
@end deffn
@deffn primitive make-leaf-environment
@deffn {Scheme Procedure} make-leaf-environment
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} leaf-environment? object
@deffnx {C Function} scm_leaf_environment_p (object)
Return @code{#t} if object is a leaf environment, or @code{#f}
otherwise.
@end deffn
@deffn primitive make-eval-environment local imported
@deffn {Scheme Procedure} make-eval-environment local imported
@deffnx {C Function} scm_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
@ -156,28 +170,34 @@ 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
@deffn {Scheme Procedure} eval-environment? object
@deffnx {C Function} scm_eval_environment_p (object)
Return @code{#t} if object is an eval environment, or @code{#f}
otherwise.
@end deffn
@deffn primitive eval-environment-local env
@deffn {Scheme Procedure} eval-environment-local env
@deffnx {C Function} scm_eval_environment_local (env)
Return the local environment of eval environment @var{env}.
@end deffn
@deffn primitive eval-environment-set-local! env local
@deffn {Scheme Procedure} eval-environment-set-local! env local
@deffnx {C Function} scm_eval_environment_set_local_x (env, local)
Change @var{env}'s local environment to @var{local}.
@end deffn
@deffn primitive eval-environment-imported env
@deffn {Scheme Procedure} eval-environment-imported env
@deffnx {C Function} scm_eval_environment_imported (env)
Return the imported environment of eval environment @var{env}.
@end deffn
@deffn primitive eval-environment-set-imported! env imported
@deffn {Scheme Procedure} eval-environment-set-imported! env imported
@deffnx {C Function} scm_eval_environment_set_imported_x (env, imported)
Change @var{env}'s imported environment to @var{imported}.
@end deffn
@deffn primitive make-import-environment imports conflict_proc
@deffn {Scheme Procedure} make-import-environment imports conflict_proc
@deffnx {C Function} scm_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,
@ -205,22 +225,26 @@ 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
@deffn {Scheme Procedure} import-environment? object
@deffnx {C Function} scm_import_environment_p (object)
Return @code{#t} if object is an import environment, or
@code{#f} otherwise.
@end deffn
@deffn primitive import-environment-imports env
@deffn {Scheme Procedure} import-environment-imports env
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} import-environment-set-imports! env imports
@deffnx {C Function} scm_import_environment_set_imports_x (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
@deffn {Scheme Procedure} make-export-environment private signature
@deffnx {C Function} scm_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
@ -267,34 +291,41 @@ 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
@deffn {Scheme Procedure} export-environment? object
@deffnx {C Function} scm_export_environment_p (object)
Return @code{#t} if object is an export environment, or
@code{#f} otherwise.
@end deffn
@deffn primitive export-environment-private env
@deffn {Scheme Procedure} export-environment-private env
@deffnx {C Function} scm_export_environment_private (env)
Return the private environment of export environment @var{env}.
@end deffn
@deffn primitive export-environment-set-private! env private
@deffn {Scheme Procedure} export-environment-set-private! env private
@deffnx {C Function} scm_export_environment_set_private_x (env, private)
Change the private environment of export environment @var{env}.
@end deffn
@deffn primitive export-environment-signature env
@deffn {Scheme Procedure} export-environment-signature env
@deffnx {C Function} scm_export_environment_signature (env)
Return the signature of export environment @var{env}.
@end deffn
@deffn primitive export-environment-set-signature! env signature
@deffn {Scheme Procedure} export-environment-set-signature! env signature
@deffnx {C Function} scm_export_environment_set_signature_x (env, signature)
Change the signature of export environment @var{env}.
@end deffn
@deffn primitive %compute-slots class
@deffn {Scheme Procedure} %compute-slots class
@deffnx {C Function} scm_sys_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
@deffn {Scheme Procedure} get-keyword key l default_value
@deffnx {C Function} scm_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
@ -303,222 +334,271 @@ 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
@deffn {Scheme Procedure} slot-ref-using-class class obj slot_name
@deffnx {C Function} scm_slot_ref_using_class (class, obj, slot_name)
@end deffn
@deffn primitive slot-set-using-class! class obj slot_name value
@deffn {Scheme Procedure} slot-set-using-class! class obj slot_name value
@deffnx {C Function} scm_slot_set_using_class_x (class, obj, slot_name, value)
@end deffn
@deffn primitive class-of x
@deffn {Scheme Procedure} class-of x
@deffnx {C Function} scm_class_of (x)
Return the class of @var{x}.
@end deffn
@deffn primitive %goops-loaded
@deffn {Scheme Procedure} %goops-loaded
@deffnx {C Function} scm_sys_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
@deffn {Scheme Procedure} %method-more-specific? m1 m2 targs
@deffnx {C Function} scm_sys_method_more_specific_p (m1, m2, targs)
@end deffn
@deffn primitive find-method . l
@deffn {Scheme Procedure} find-method . l
@deffnx {C Function} scm_find_method (l)
@end deffn
@deffn primitive primitive-generic-generic subr
@deffn {Scheme Procedure} primitive-generic-generic subr
@deffnx {C Function} scm_primitive_generic_generic (subr)
@end deffn
@deffn primitive enable-primitive-generic! . subrs
@deffn {Scheme Procedure} enable-primitive-generic! . subrs
@deffnx {C Function} scm_enable_primitive_generic_x (subrs)
@end deffn
@deffn primitive generic-capability? proc
@deffn {Scheme Procedure} generic-capability? proc
@deffnx {C Function} scm_generic_capability_p (proc)
@end deffn
@deffn primitive %invalidate-method-cache! gf
@deffn {Scheme Procedure} %invalidate-method-cache! gf
@deffnx {C Function} scm_sys_invalidate_method_cache_x (gf)
@end deffn
@deffn primitive %invalidate-class class
@deffn {Scheme Procedure} %invalidate-class class
@deffnx {C Function} scm_sys_invalidate_class (class)
@end deffn
@deffn primitive %modify-class old new
@deffn {Scheme Procedure} %modify-class old new
@deffnx {C Function} scm_sys_modify_class (old, new)
@end deffn
@deffn primitive %modify-instance old new
@deffn {Scheme Procedure} %modify-instance old new
@deffnx {C Function} scm_sys_modify_instance (old, new)
@end deffn
@deffn primitive %set-object-setter! obj setter
@deffn {Scheme Procedure} %set-object-setter! obj setter
@deffnx {C Function} scm_sys_set_object_setter_x (obj, setter)
@end deffn
@deffn primitive %allocate-instance class initargs
@deffn {Scheme Procedure} %allocate-instance class initargs
@deffnx {C Function} scm_sys_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
@deffn {Scheme Procedure} slot-exists? obj slot_name
@deffnx {C Function} scm_slots_exists_p (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
@deffn {Scheme Procedure} slot-bound? obj slot_name
@deffnx {C Function} scm_slot_bound_p (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
@deffn {Scheme Procedure} slot-set! obj slot_name value
@deffnx {C Function} scm_slot_set_x (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
@deffn {Scheme Procedure} slot-exists-using-class? class obj slot_name
@deffnx {C Function} scm_slot_exists_using_class_p (class, obj, slot_name)
@end deffn
@deffn primitive slot-bound-using-class? class obj slot_name
@deffn {Scheme Procedure} slot-bound-using-class? class obj slot_name
@deffnx {C Function} scm_slot_bound_using_class_p (class, obj, slot_name)
@end deffn
@deffn primitive %fast-slot-set! obj index value
@deffn {Scheme Procedure} %fast-slot-set! obj index value
@deffnx {C Function} scm_sys_fast_slot_set_x (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
@deffn {Scheme Procedure} %fast-slot-ref obj index
@deffnx {C Function} scm_sys_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
@deffn {Scheme Procedure} @@assert-bound-ref obj index
@deffnx {C Function} scm_at_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
@deffn {Scheme Procedure} assert-bound value obj
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} unbound? obj
@deffnx {C Function} scm_unbound_p (obj)
Return @code{#t} if @var{obj} is unbound.
@end deffn
@deffn primitive make-unbound
@deffn {Scheme Procedure} make-unbound
@deffnx {C Function} scm_make_unbound ()
Return the unbound value.
@end deffn
@deffn primitive accessor-method-slot-definition obj
@deffn {Scheme Procedure} accessor-method-slot-definition obj
@deffnx {C Function} scm_accessor_method_slot_definition (obj)
Return the slot definition of the accessor @var{obj}.
@end deffn
@deffn primitive method-procedure obj
@deffn {Scheme Procedure} method-procedure obj
@deffnx {C Function} scm_method_procedure (obj)
Return the procedure of the method @var{obj}.
@end deffn
@deffn primitive method-specializers obj
@deffn {Scheme Procedure} method-specializers obj
@deffnx {C Function} scm_method_specializers (obj)
Return specializers of the method @var{obj}.
@end deffn
@deffn primitive method-generic-function obj
@deffn {Scheme Procedure} method-generic-function obj
@deffnx {C Function} scm_method_generic_function (obj)
Return the generic function fot the method @var{obj}.
@end deffn
@deffn primitive generic-function-methods obj
@deffn {Scheme Procedure} generic-function-methods obj
@deffnx {C Function} scm_generic_function_methods (obj)
Return the methods of the generic function @var{obj}.
@end deffn
@deffn primitive generic-function-name obj
@deffn {Scheme Procedure} generic-function-name obj
@deffnx {C Function} scm_generic_function_name (obj)
Return the name of the generic function @var{obj}.
@end deffn
@deffn primitive class-environment obj
@deffn {Scheme Procedure} class-environment obj
@deffnx {C Function} scm_class_environment (obj)
Return the environment of the class @var{obj}.
@end deffn
@deffn primitive class-slots obj
@deffn {Scheme Procedure} class-slots obj
@deffnx {C Function} scm_class_slots (obj)
Return the slot list of the class @var{obj}.
@end deffn
@deffn primitive class-precedence-list obj
@deffn {Scheme Procedure} class-precedence-list obj
@deffnx {C Function} scm_class_precedence_list (obj)
Return the class precedence list of the class @var{obj}.
@end deffn
@deffn primitive class-direct-methods obj
@deffn {Scheme Procedure} class-direct-methods obj
@deffnx {C Function} scm_class_direct_methods (obj)
Return the direct methods of the class @var{obj}
@end deffn
@deffn primitive class-direct-subclasses obj
@deffn {Scheme Procedure} class-direct-subclasses obj
@deffnx {C Function} scm_class_direct_subclasses (obj)
Return the direct subclasses of the class @var{obj}.
@end deffn
@deffn primitive class-direct-slots obj
@deffn {Scheme Procedure} class-direct-slots obj
@deffnx {C Function} scm_class_direct_slots (obj)
Return the direct slots of the class @var{obj}.
@end deffn
@deffn primitive class-direct-supers obj
@deffn {Scheme Procedure} class-direct-supers obj
@deffnx {C Function} scm_class_direct_supers (obj)
Return the direct superclasses of the class @var{obj}.
@end deffn
@deffn primitive class-name obj
@deffn {Scheme Procedure} class-name obj
@deffnx {C Function} scm_class_name (obj)
Return the class name of @var{obj}.
@end deffn
@deffn primitive instance? obj
@deffn {Scheme Procedure} instance? obj
@deffnx {C Function} scm_instance_p (obj)
Return @code{#t} if @var{obj} is an instance.
@end deffn
@deffn primitive %inherit-magic! class dsupers
@deffn {Scheme Procedure} %inherit-magic! class dsupers
@deffnx {C Function} scm_sys_inherit_magic_x (class, dsupers)
@end deffn
@deffn primitive %prep-layout! class
@deffn {Scheme Procedure} %prep-layout! class
@deffnx {C Function} scm_sys_prep_layout_x (class)
@end deffn
@deffn primitive %initialize-object obj initargs
@deffn {Scheme Procedure} %initialize-object obj initargs
@deffnx {C Function} scm_sys_initialize_object (obj, initargs)
Initialize the object @var{obj} with the given arguments
@var{initargs}.
@end deffn
@deffn primitive make . args
@deffn {Scheme Procedure} make . args
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} slot-ref obj slot_name
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} builtin-bindings
Create and return a copy of the global symbol table, removing all
unbound symbols.
@end deffn
@deffn primitive %tag-body body
@deffn {Scheme Procedure} %tag-body body
@deffnx {C Function} scm_sys_tag_body (body)
Internal GOOPS magic---don't use this function!
@end deffn
@deffn primitive list*
@deffn {Scheme Procedure} list*
implemented by the C function "scm_cons_star"
@end deffn
@deffn primitive set-current-module module
@deffn {Scheme Procedure} set-current-module module
@deffnx {C Function} scm_set_current_module (module)
Set the current module to @var{module} and return
the previous current module.
@end deffn
@deffn primitive current-module
@deffn {Scheme Procedure} current-module
@deffnx {C Function} scm_current_module ()
Return the current module.
@end deffn
@deffn primitive c-clear-registered-modules
@deffn {Scheme Procedure} c-clear-registered-modules
Destroy the list of modules registered with the current Guile process.
The return value is unspecified. @strong{Warning:} this function does
not actually unlink or deallocate these modules, but only destroys the
@ -526,7 +606,7 @@ records of which modules have been loaded. It should therefore be used
only by module bookkeeping operations.
@end deffn
@deffn primitive c-registered-modules
@deffn {Scheme Procedure} c-registered-modules
Return a list of the object code modules that have been imported into
the current Guile process. Each element of the list is a pair whose
car is the name of the module, and whose cdr is the function handle
@ -534,12 +614,12 @@ for that module's initializer function. The name is the string that
has been passed to scm_register_module_xxx.
@end deffn
@deffn primitive include-deprecated-features
@deffn {Scheme Procedure} include-deprecated-features
Return @code{#t} iff deprecated features should be included
in public interfaces.
@end deffn
@deffn primitive issue-deprecation-warning . msgs
@deffn {Scheme Procedure} issue-deprecation-warning . msgs
Output @var{msgs} to @code{(current-error-port)} when this
is the first call to @code{issue-deprecation-warning} with
this specific @var{msg}. Do nothing otherwise.
@ -547,23 +627,28 @@ The argument @var{msgs} should be a list of strings;
they are printed in turn, each one followed by a newline.
@end deffn
@deffn primitive valid-object-procedure? proc
@deffn {Scheme Procedure} valid-object-procedure? proc
@deffnx {C Function} scm_valid_object_procedure_p (proc)
Return @code{#t} iff @var{proc} is a procedure that can be used with @code{set-object-procedure}. It is always valid to use a closure constructed by @code{lambda}.
@end deffn
@deffn primitive %get-pre-modules-obarray
@deffn {Scheme Procedure} %get-pre-modules-obarray
@deffnx {C Function} scm_get_pre_modules_obarray ()
Return the obarray that is used for all new bindings before the module system is booted. The first call to @code{set-current-module} will boot the module system.
@end deffn
@deffn primitive standard-interface-eval-closure module
@deffn {Scheme Procedure} standard-interface-eval-closure module
@deffnx {C Function} scm_standard_interface_eval_closure (module)
Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
@end deffn
@deffn primitive env-module env
@deffn {Scheme Procedure} env-module env
@deffnx {C Function} scm_env_module (env)
Return the module of @var{ENV}, a lexical environment.
@end deffn
@deffn primitive load-extension lib init
@deffn {Scheme Procedure} load-extension lib init
@deffnx {C Function} scm_load_extension (lib, init)
Load and initialize the extension designated by LIB and INIT.
When there is no pre-registered function for LIB/INIT, this is
equivalent to

599
doc/ref/posix.texi
View file

File diff suppressed because it is too large Load diff

3
doc/ref/scheme-binding.texi
View file

@ -232,7 +232,8 @@ bound in expression, you can use the @code{bound?} macro from the module
@code{(ice-9 optargs)}, documented in @ref{Optional Arguments}.
@c NJFIXME explain [env]
@deffn primitive defined? sym [env]
@deffn {Scheme Procedure} defined? sym [env]
@deffnx {C Function} scm_definedp (sym, env)
Return @code{#t} if @var{sym} is defined in the lexical environment @var{env}. When @var{env} is not specified, look in the top-level environment as defined by the current module.
@end deffn

31
doc/ref/scheme-control.texi
View file

@ -273,7 +273,7 @@ for escape procedures and your program is running too slow, you might
want to use exceptions (@pxref{Exceptions}) instead.
@rnindex call-with-current-continuation
@deffn primitive call-with-current-continuation proc
@deffn {Scheme Procedure} call-with-current-continuation proc
Capture the current continuation and call @var{proc} with the captured
continuation as the single argument. This continuation can then be
called with arbitrarily many arguments. Such a call will work like a
@ -325,7 +325,8 @@ multiple values with a procedure which accepts these values as
parameters.
@rnindex values
@deffn primitive values expr @dots{}
@deffn {Scheme Procedure} values . args
@deffnx {C Function} scm_values (args)
Delivers all of its arguments to its continuation. Except for
continuations created by the @code{call-with-values} procedure,
all continuations take exactly one value. The effect of
@ -334,7 +335,7 @@ were not created by @code{call-with-values} is unspecified.
@end deffn
@rnindex call-with-values
@deffn primitive call-with-values producer consumer
@deffn {Scheme Procedure} call-with-values producer consumer
Calls its @var{producer} argument with no values and a
continuation that, when passed some values, calls the
@var{consumer} procedure with those values as arguments. The
@ -490,7 +491,8 @@ procedure must be designed to accept a number of arguments that
corresponds to the number of arguments in all @code{throw} expressions
that can be caught by this @code{catch}.
@deffn primitive catch key thunk handler
@deffn {Scheme Procedure} catch key thunk handler
@deffnx {C Function} scm_catch (key, thunk, handler)
Invoke @var{thunk} in the dynamic context of @var{handler} for
exceptions matching @var{key}. If thunk throws to the symbol
@var{key}, then @var{handler} is invoked this way:
@ -545,7 +547,8 @@ depends on the exception type. The documentation for each possible type
of exception should specify the additional arguments that are expected
for that kind of exception.
@deffn primitive throw key . args
@deffn {Scheme Procedure} throw key . args
@deffnx {C Function} scm_throw (key, args)
Invoke the catch form matching @var{key}, passing @var{args} to the
@var{handler}.
@ -607,7 +610,8 @@ one important respect: 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.
@deffn primitive lazy-catch key thunk handler
@deffn {Scheme Procedure} lazy-catch key thunk handler
@deffnx {C Function} scm_lazy_catch (key, thunk, handler)
This behaves exactly like @code{catch}, except that it does
not unwind the stack before invoking @var{handler}.
The @var{handler} procedure is not allowed to return:
@ -728,12 +732,13 @@ Guile provides a set of convenience procedures for signaling error
conditions that are implemented on top of the exception primitives just
described.
@deffn procedure error msg args @dots{}
@deffn {Scheme Procedure} error msg args @dots{}
Raise an error with key @code{misc-error} and a message constructed by
displaying @var{msg} and writing @var{args}.
@end deffn
@deffn primitive scm-error key subr message args data
@deffn {Scheme Procedure} scm-error key subr message args data
@deffnx {C Function} scm_error_scm (key, subr, message, args, data)
Raise an error with key @var{key}. @var{subr} can be a string
naming the procedure associated with the error, or @code{#f}.
@var{message} is the error message string, possibly containing
@ -749,7 +754,8 @@ should be a list containing the Unix signal number; otherwise
it will usually be @code{#f}.
@end deffn
@deffn primitive strerror err
@deffn {Scheme Procedure} strerror err
@deffnx {C Function} scm_strerror (err)
Return the Unix error message corresponding to @var{err}, which
must be an integer value.
@end deffn
@ -769,7 +775,8 @@ if an exception occurs then @code{#f} is returned instead.
be reviewed]
@rnindex dynamic-wind
@deffn primitive dynamic-wind in_guard thunk out_guard
@deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
@deffnx {C Function} scm_dynamic_wind (in_guard, thunk, out_guard)
All three arguments must be 0-argument procedures.
@var{in_guard} is called, then @var{thunk}, then
@var{out_guard}.
@ -861,12 +868,12 @@ be @code{#f} if no additional objects are required.
In addition to @code{catch} and @code{throw}, the following Scheme
facilities are available:
@deffn primitive scm-error key subr message args rest
@deffn {Scheme Procedure} scm-error key subr message args rest
Throw an error, with arguments
as described above.
@end deffn
@deffn procedure error msg arg @dots{}
@deffn {Scheme Procedure} error msg arg @dots{}
Throw an error using the key @code{'misc-error}. The error
message is created by displaying @var{msg} and writing the @var{args}.
@end deffn

1050
doc/ref/scheme-data.texi
View file

File diff suppressed because it is too large Load diff

92
doc/ref/scheme-debug.texi
View file

@ -6,7 +6,8 @@
from the appendix describing the debugger UI. The intro
should have a pointer to the UI appendix.
@deffn primitive display-error stack port subr message args rest
@deffn {Scheme Procedure} display-error stack port subr message args rest
@deffnx {C Function} scm_display_error (stack, port, subr, message, args, rest)
Display an error message to the output port @var{port}.
@var{stack} is the saved stack for the error, @var{subr} is
the name of the procedure in which the error occured and
@ -16,13 +17,15 @@ the list @var{args} accordingly. @var{rest} is currently
ignored.
@end deffn
@deffn primitive display-application frame [port [indent]]
@deffn {Scheme Procedure} display-application frame [port [indent]]
@deffnx {C Function} scm_display_application (frame, port, indent)
Display a procedure application @var{frame} to the output port
@var{port}. @var{indent} specifies the indentation of the
output.
@end deffn
@deffn primitive display-backtrace stack port [first [depth]]
@deffn {Scheme Procedure} display-backtrace stack port [first [depth]]
@deffnx {C Function} scm_display_backtrace (stack, port, first, depth)
Display a backtrace to the output port @var{port}. @var{stack}
is the stack to take the backtrace from, @var{first} specifies
where in the stack to start and @var{depth} how much frames
@ -30,12 +33,13 @@ to display. Both @var{first} and @var{depth} can be @code{#f},
which means that default values will be used.
@end deffn
@deffn primitive backtrace
@deffn {Scheme Procedure} backtrace
@deffnx {C Function} scm_backtrace ()
Display a backtrace of the stack saved by the last error
to the current output port.
@end deffn
@deffn primitive malloc-stats
@deffn {Scheme Procedure} malloc-stats
Return an alist ((@var{what} . @var{n}) ...) describing number
of malloced objects.
@var{what} is the second argument to @code{scm_must_malloc},
@ -43,98 +47,120 @@ of malloced objects.
allocated.
@end deffn
@deffn primitive debug-options-interface [setting]
@deffn {Scheme Procedure} debug-options-interface [setting]
@deffnx {C Function} scm_debug_options (setting)
Option interface for the debug options. Instead of using
this procedure directly, use the procedures @code{debug-enable},
@code{debug-disable}, @code{debug-set!} and @var{debug-options}.
@end deffn
@deffn primitive with-traps thunk
@deffn {Scheme Procedure} with-traps thunk
@deffnx {C Function} scm_with_traps (thunk)
Call @var{thunk} with traps enabled.
@end deffn
@deffn primitive memoized? obj
@deffn {Scheme Procedure} memoized? obj
@deffnx {C Function} scm_memoized_p (obj)
Return @code{#t} if @var{obj} is memoized.
@end deffn
@deffn primitive unmemoize m
@deffn {Scheme Procedure} unmemoize m
@deffnx {C Function} scm_unmemoize (m)
Unmemoize the memoized expression @var{m},
@end deffn
@deffn primitive memoized-environment m
@deffn {Scheme Procedure} memoized-environment m
@deffnx {C Function} scm_memoized_environment (m)
Return the environment of the memoized expression @var{m}.
@end deffn
@deffn primitive procedure-name proc
@deffn {Scheme Procedure} procedure-name proc
@deffnx {C Function} scm_procedure_name (proc)
Return the name of the procedure @var{proc}
@end deffn
@deffn primitive procedure-source proc
@deffn {Scheme Procedure} procedure-source proc
@deffnx {C Function} scm_procedure_source (proc)
Return the source of the procedure @var{proc}.
@end deffn
@deffn primitive procedure-environment proc
@deffn {Scheme Procedure} procedure-environment proc
@deffnx {C Function} scm_procedure_environment (proc)
Return the environment of the procedure @var{proc}.
@end deffn
@deffn primitive debug-object? obj
@deffn {Scheme Procedure} debug-object? obj
@deffnx {C Function} scm_debug_object_p (obj)
Return @code{#t} if @var{obj} is a debug object.
@end deffn
@deffn primitive frame-arguments frame
@deffn {Scheme Procedure} frame-arguments frame
@deffnx {C Function} scm_frame_arguments (frame)
Return the arguments of @var{frame}.
@end deffn
@deffn primitive frame-evaluating-args? frame
@deffn {Scheme Procedure} frame-evaluating-args? frame
@deffnx {C Function} scm_frame_evaluating_args_p (frame)
Return @code{#t} if @var{frame} contains evaluated arguments.
@end deffn
@deffn primitive frame-next frame
@deffn {Scheme Procedure} frame-next frame
@deffnx {C Function} scm_frame_next (frame)
Return the next frame of @var{frame}, or @code{#f} if
@var{frame} is the last frame in its stack.
@end deffn
@deffn primitive frame-number frame
@deffn {Scheme Procedure} frame-number frame
@deffnx {C Function} scm_frame_number (frame)
Return the frame number of @var{frame}.
@end deffn
@deffn primitive frame-overflow? frame
@deffn {Scheme Procedure} frame-overflow? frame
@deffnx {C Function} scm_frame_overflow_p (frame)
Return @code{#t} if @var{frame} is an overflow frame.
@end deffn
@deffn primitive frame-previous frame
@deffn {Scheme Procedure} frame-previous frame
@deffnx {C Function} scm_frame_previous (frame)
Return the previous frame of @var{frame}, or @code{#f} if
@var{frame} is the first frame in its stack.
@end deffn
@deffn primitive frame-procedure frame
@deffn {Scheme Procedure} frame-procedure frame
@deffnx {C Function} scm_frame_procedure (frame)
Return the procedure for @var{frame}, or @code{#f} if no
procedure is associated with @var{frame}.
@end deffn
@deffn primitive frame-procedure? frame
@deffn {Scheme Procedure} frame-procedure? frame
@deffnx {C Function} scm_frame_procedure_p (frame)
Return @code{#t} if a procedure is associated with @var{frame}.
@end deffn
@deffn primitive frame-real? frame
@deffn {Scheme Procedure} frame-real? frame
@deffnx {C Function} scm_frame_real_p (frame)
Return @code{#t} if @var{frame} is a real frame.
@end deffn
@deffn primitive frame-source frame
@deffn {Scheme Procedure} frame-source frame
@deffnx {C Function} scm_frame_source (frame)
Return the source of @var{frame}.
@end deffn
@deffn primitive frame? obj
@deffn {Scheme Procedure} frame? obj
@deffnx {C Function} scm_frame_p (obj)
Return @code{#t} if @var{obj} is a stack frame.
@end deffn
@deffn primitive last-stack-frame obj
@deffn {Scheme Procedure} last-stack-frame obj
@deffnx {C Function} scm_last_stack_frame (obj)
Return a stack which consists of a single frame, which is the
last stack frame for @var{obj}. @var{obj} must be either a
debug object or a continuation.
@end deffn
@deffn primitive make-stack obj . args
@deffn {Scheme Procedure} make-stack obj . args
@deffnx {C Function} scm_make_stack (obj, args)
Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be
@ -165,19 +191,23 @@ If the @var{outer_cut_N} of the last pair is missing, it is
taken as 0.
@end deffn
@deffn primitive stack-id stack
@deffn {Scheme Procedure} stack-id stack
@deffnx {C Function} scm_stack_id (stack)
Return the identifier given to @var{stack} by @code{start-stack}.
@end deffn
@deffn primitive stack-length stack
@deffn {Scheme Procedure} stack-length stack
@deffnx {C Function} scm_stack_length (stack)
Return the length of @var{stack}.
@end deffn
@deffn primitive stack-ref stack index
@deffn {Scheme Procedure} stack-ref stack index
@deffnx {C Function} scm_stack_ref (stack, index)
Return the @var{index}'th frame from @var{stack}.
@end deffn
@deffn primitive stack? obj
@deffn {Scheme Procedure} stack? obj
@deffnx {C Function} scm_stack_p (obj)
Return @code{#t} if @var{obj} is a calling stack.
@end deffn

92
doc/ref/scheme-evaluation.texi
View file

@ -122,7 +122,8 @@ to use uppercase letters in their identifiers anyway.
@node Reader Extensions
@subsection Reader Extensions
@deffn primitive read-hash-extend chr proc
@deffn {Scheme Procedure} read-hash-extend chr proc
@deffnx {C Function} scm_read_hash_extend (chr, proc)
Install the procedure @var{proc} for reading expressions
starting with the character sequence @code{#} and @var{chr}.
@var{proc} will be called with two arguments: the character
@ -135,7 +136,8 @@ returned will be the return value of @code{read}.
@section Reading Scheme Code
@rnindex read
@deffn primitive read [port]
@deffn {Scheme Procedure} read [port]
@deffnx {C Function} scm_read (port)
Read an s-expression from the input port @var{port}, or from
the current input port if @var{port} is not specified.
Any whitespace before the next token is discarded.
@ -149,7 +151,7 @@ available, @xref{Reader options}.
@c FIXME::martin: This is taken from libguile/options.c. Is there
@c actually a difference between 'help and 'full?
@deffn procedure read-options [setting]
@deffn {Scheme Procedure} read-options [setting]
Display the current settings of the read options. If @var{setting} is
omitted, only a short form of the current read options is printed.
Otherwise, @var{setting} should be one of the following symbols:
@ -161,18 +163,19 @@ Like @code{help}, but also print programmer options.
@end table
@end deffn
@deffn procedure read-enable option-name
@deffnx procedure read-disable option-name
@deffnx procedure read-set! option-name value
@deffn {Scheme Procedure} read-enable option-name
@deffnx {Scheme Procedure} read-disable option-name
@deffnx {Scheme Procedure} read-set! option-name value
Modify the read options. @code{read-enable} should be used with boolean
options and switches them on, @code{read-disable} switches them off.
@code{read-set!} can be used to set an option to a specific value.
@end deffn
@deffn primitive read-options-interface [setting]
@deffn {Scheme Procedure} read-options-interface [setting]
@deffnx {C Function} scm_read_options (setting)
Option interface for the read options. Instead of using
this procedure directly, use the procedures @code{read-enable},
@code{read-disable}, @code{read-set!} and @code{read-options}.
@code{read-disable}, @code{read-set!} and @var{read-options}.
@end deffn
@ -181,13 +184,18 @@ this procedure directly, use the procedures @code{read-enable},
@rnindex eval
@c ARGFIXME environment/environment specifier
@deffn primitive eval exp environment
Evaluate @var{exp}, a list representing a Scheme expression, in the
environment given by @var{environment specifier}.
@deffn {Scheme Procedure} eval exp module
@deffnx {C Function} scm_eval (exp, module)
Evaluate @var{exp}, a list representing a Scheme expression,
in the top-level environment specified by @var{module}.
While @var{exp} is evaluated (using @code{primitive-eval}),
@var{module} is made the current module. The current module
is reset to its previous value when @var{eval} returns.
@end deffn
@rnindex interaction-environment
@deffn primitive interaction-environment
@deffn {Scheme Procedure} interaction-environment
@deffnx {C Function} scm_interaction_environment ()
Return a specifier for the environment that contains
implementation--defined bindings, typically a superset of those
listed in the report. The intent is that this procedure will
@ -195,14 +203,16 @@ return the environment in which the implementation would
evaluate expressions dynamically typed by the user.
@end deffn
@deffn primitive eval-string string
@deffn {Scheme Procedure} eval-string string
@deffnx {C Function} scm_eval_string (string)
Evaluate @var{string} as the text representation of a Scheme
form or forms, and return whatever value they produce.
Evaluation takes place in the environment returned by the
procedure @code{interaction-environment}.
@end deffn
@deffn primitive apply:nconc2last lst
@deffn {Scheme Procedure} apply:nconc2last lst
@deffnx {C Function} scm_nconc2last (lst)
Given a list (@var{arg1} @dots{} @var{args}), this function
conses the @var{arg1} @dots{} arguments onto the front of
@var{args}, and returns the resulting list. Note that
@ -213,13 +223,14 @@ destroys its argument, so use with care.
@end deffn
@rnindex apply
@deffn primitive apply proc arg1 @dots{} args
@deffn {Scheme Procedure} apply proc arg1 @dots{} args
@var{proc} must be a procedure and @var{args} must be a list. Call
@var{proc} with the elements of the list @code{(append (list @var{arg1}
@dots{}) @var{args})} as the actual arguments.
@end deffn
@deffn primitive primitive-eval exp
@deffn {Scheme Procedure} primitive-eval exp
@deffnx {C Function} scm_primitive_eval (exp)
Evaluate @var{exp} in the top-level environment specified by
the current module.
@end deffn
@ -229,7 +240,7 @@ the current module.
@section Loading Scheme Code from File
@rnindex load
@deffn procedure load filename
@deffn {Scheme Procedure} load filename
Load @var{filename} and evaluate its contents in the top-level
environment. The load paths are not searched. If the variable
@code{%load-hook} is defined, it should be bound to a procedure that
@ -237,12 +248,13 @@ will be called before any code is loaded. See documentation for
@code{%load-hook} later in this section.
@end deffn
@deffn procedure load-from-path filename
@deffn {Scheme Procedure} load-from-path filename
Similar to @code{load}, but searches for @var{filename} in the load
paths.
@end deffn
@deffn primitive primitive-load filename
@deffn {Scheme Procedure} primitive-load filename
@deffnx {C Function} scm_primitive_load (filename)
Load the file named @var{filename} and evaluate its contents in
the top-level environment. The load paths are not searched;
@var{filename} must either be a full pathname or be a pathname
@ -252,14 +264,16 @@ that will be called before any code is loaded. See the
documentation for @code{%load-hook} later in this section.
@end deffn
@deffn primitive primitive-load-path filename
@deffn {Scheme Procedure} primitive-load-path filename
@deffnx {C Function} scm_primitive_load_path (filename)
Search @var{%load-path} for the file named @var{filename} and
load it into the top-level environment. If @var{filename} is a
relative pathname and is not found in the list of search paths,
an error is signalled.
@end deffn
@deffn primitive %search-load-path filename
@deffn {Scheme Procedure} %search-load-path filename
@deffnx {C Function} scm_sys_search_load_path (filename)
Search @var{%load-path} for the file named @var{filename},
which must be readable by the current user. If @var{filename}
is found in the list of paths to search or is an absolute
@ -285,7 +299,8 @@ was passed to @code{primitive-load}.
@end defvar
@deffn primitive current-load-port
@deffn {Scheme Procedure} current-load-port
@deffnx {C Function} scm_current_load_port ()
Return the current-load-port.
The load port is used internally by @code{primitive-load}.
@end deffn
@ -303,13 +318,15 @@ list @code{("" ".scm")}.
[delay]
@deffn primitive promise? obj
@deffn {Scheme Procedure} promise? obj
@deffnx {C Function} scm_promise_p (obj)
Return true if @var{obj} is a promise, i.e. a delayed computation
(@pxref{Delayed evaluation,,,r5rs.info,The Revised^5 Report on Scheme}).
@end deffn
@rnindex force
@deffn primitive force x
@deffn {Scheme Procedure} force x
@deffnx {C Function} scm_force (x)
If the promise @var{x} has not been computed yet, compute and
return @var{x}, otherwise just return the previously computed
value.
@ -321,7 +338,8 @@ value.
[the-environment]
@deffn primitive local-eval exp [env]
@deffn {Scheme Procedure} local-eval exp [env]
@deffnx {C Function} scm_local_eval (exp, env)
Evaluate @var{exp} in its environment. If @var{env} is supplied,
it is the environment in which to evaluate @var{exp}. Otherwise,
@var{exp} must be a memoized code object (in which case, its environment
@ -343,7 +361,7 @@ available, @xref{Evaluator options}.
@c FIXME::martin: This is taken from libguile/options.c. Is there
@c actually a difference between 'help and 'full?
@deffn procedure eval-options [setting]
@deffn {Scheme Procedure} eval-options [setting]
Display the current settings of the evaluator options. If @var{setting}
is omitted, only a short form of the current evaluator options is
printed. Otherwise, @var{setting} should be one of the following
@ -356,24 +374,25 @@ Like @code{help}, but also print programmer options.
@end table
@end deffn
@deffn procedure eval-enable option-name
@deffnx procedure eval-disable option-name
@deffnx procedure eval-set! option-name value
@deffn {Scheme Procedure} eval-enable option-name
@deffnx {Scheme Procedure} eval-disable option-name
@deffnx {Scheme Procedure} eval-set! option-name value
Modify the evaluator options. @code{eval-enable} should be used with boolean
options and switches them on, @code{eval-disable} switches them off.
@code{eval-set!} can be used to set an option to a specific value.
@end deffn
@deffn primitive eval-options-interface [setting]
@deffn {Scheme Procedure} eval-options-interface [setting]
@deffnx {C Function} scm_eval_options_interface (setting)
Option interface for the evaluation options. Instead of using
this procedure directly, use the procedures @code{eval-enable},
@code{eval-disable}, @code{eval-set!} and @code{eval-options}.
@code{eval-disable}, @code{eval-set!} and @var{eval-options}.
@end deffn
@c FIXME::martin: Why aren't these procedure named like the other options
@c procedures?
@deffn procedure traps [setting]
@deffn {Scheme Procedure} traps [setting]
Display the current settings of the evaluator traps options. If
@var{setting} is omitted, only a short form of the current evaluator
traps options is printed. Otherwise, @var{setting} should be one of the
@ -386,15 +405,16 @@ Like @code{help}, but also print programmer options.
@end table
@end deffn
@deffn procedure trap-enable option-name
@deffnx procedure trap-disable option-name
@deffnx procedure trap-set! option-name value
@deffn {Scheme Procedure} trap-enable option-name
@deffnx {Scheme Procedure} trap-disable option-name
@deffnx {Scheme Procedure} trap-set! option-name value
Modify the evaluator options. @code{trap-enable} should be used with boolean
options and switches them on, @code{trap-disable} switches them off.
@code{trap-set!} can be used to set an option to a specific value.
@end deffn
@deffn primitive evaluator-traps-interface [setting]
@deffn {Scheme Procedure} evaluator-traps-interface [setting]
@deffnx {C Function} scm_evaluator_traps (setting)
Option interface for the evaluator trap options.
@end deffn

205
doc/ref/scheme-io.texi
View file

@ -34,20 +34,23 @@ that simulate ports in software. @dfn{Soft ports} and @dfn{string
ports} are two interesting and powerful examples of this technique.
@rnindex input-port?
@deffn primitive input-port? x
@deffn {Scheme Procedure} input-port? x
@deffnx {C Function} scm_input_port_p (x)
Return @code{#t} if @var{x} is an input port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@rnindex output-port?
@deffn primitive output-port? x
@deffn {Scheme Procedure} output-port? x
@deffnx {C Function} scm_output_port_p (x)
Return @code{#t} if @var{x} is an output port, otherwise return
@code{#f}. Any object satisfying this predicate also satisfies
@code{port?}.
@end deffn
@deffn primitive port? x
@deffn {Scheme Procedure} port? x
@deffnx {C Function} scm_port_p (x)
Return a boolean indicating whether @var{x} is a port.
Equivalent to @code{(or (input-port? @var{x}) (output-port?
@var{x}))}.
@ -60,13 +63,15 @@ Equivalent to @code{(or (input-port? @var{x}) (output-port?
[Generic procedures for reading from ports.]
@rnindex eof-object?
@deffn primitive eof-object? x
@deffn {Scheme Procedure} eof-object? x
@deffnx {C Function} scm_eof_object_p (x)
Return @code{#t} if @var{x} is an end-of-file object; otherwise
return @code{#f}.
@end deffn
@rnindex char-ready?
@deffn primitive char-ready? [port]
@deffn {Scheme Procedure} char-ready? [port]
@deffnx {C Function} scm_char_ready_p (port)
Return @code{#t} if a character is ready on input @var{port}
and return @code{#f} otherwise. If @code{char-ready?} returns
@code{#t} then the next @code{read-char} operation on
@ -83,14 +88,16 @@ interactive port that has no ready characters.}
@end deffn
@rnindex read-char?
@deffn primitive read-char [port]
@deffn {Scheme Procedure} read-char [port]
@deffnx {C Function} scm_read_char (port)
Return the next character available from @var{port}, updating
@var{port} to point to the following character. If no more
characters are available, the end-of-file object is returned.
@end deffn
@rnindex peek-char?
@deffn primitive peek-char [port]
@deffn {Scheme Procedure} peek-char [port]
@deffnx {C Function} scm_peek_char (port)
Return the next character available from @var{port},
@emph{without} updating @var{port} to point to the following
character. If no more characters are available, the
@ -105,21 +112,24 @@ an interactive port will hang waiting for input whenever a call
to @code{read-char} would have hung.}
@end deffn
@deffn primitive unread-char cobj port
@deffn {Scheme Procedure} unread-char cobj [port]
@deffnx {C Function} scm_unread_char (cobj, port)
Place @var{char} in @var{port} so that it will be read by the
next read operation. If called multiple times, the unread characters
will be read again in last-in first-out order. If @var{port} is
not supplied, the current input port is used.
@end deffn
@deffn primitive unread-string str port
@deffn {Scheme Procedure} unread-string str port
@deffnx {C Function} scm_unread_string (str, port)
Place the string @var{str} in @var{port} so that its characters will be
read in subsequent read operations. If called multiple times, the
unread characters will be read again in last-in first-out order. If
@var{port} is not supplied, the current-input-port is used.
@end deffn
@deffn primitive drain-input port
@deffn {Scheme Procedure} drain-input port
@deffnx {C Function} scm_drain_input (port)
This procedure clears a port's input buffers, similar
to the way that force-output clears the output buffer. The
contents of the buffers are returned as a single string, e.g.,
@ -136,8 +146,10 @@ buffered I/O so that the file descriptor can be used directly
for further input.
@end deffn
@deffn primitive port-column port
@deffnx primitive port-line port
@deffn {Scheme Procedure} port-column port
@deffnx {Scheme Procedure} port-line port
@deffnx {C Function} scm_port_column (port)
@deffnx {C Function} scm_port_line (port)
Return the current column number or line number of @var{port},
using the current input port if none is specified. If the number is
unknown, the result is #f. Otherwise, the result is a 0-origin integer
@ -148,8 +160,10 @@ because lines and column numbers traditionally start with 1, and that is
what non-programmers will find most natural.)
@end deffn
@deffn primitive set-port-column! port column
@deffnx primitive set-port-line! port line
@deffn {Scheme Procedure} set-port-column! port column
@deffnx {Scheme Procedure} set-port-line! port line
@deffnx {C Function} scm_set_port_column_x (port, column)
@deffnx {C Function} scm_set_port_line_x (port, line)
Set the current column or line number of @var{port}, using the
current input port if none is specified.
@end deffn
@ -159,13 +173,14 @@ current input port if none is specified.
[Generic procedures for writing to ports.]
@deffn primitive get-print-state port
@deffn {Scheme Procedure} get-print-state port
@deffnx {C Function} scm_get_print_state (port)
Return the print state of the port @var{port}. If @var{port}
has no associated print state, @code{#f} is returned.
@end deffn
@rnindex display
@deffn primitive display obj [port]
@deffn {Scheme Procedure} display obj [port]
Send a representation of @var{obj} to @var{current-output-port}.
Optional second arg @var{port} specifies an alternative output port.
The representation is similar to that produced by @code{write} (REFFIXME),
@ -174,23 +189,28 @@ escaped), and characters are rendered as if with @code{write-char}.
@end deffn
@rnindex newline
@deffn primitive newline [port]
Send a newline to @var{port} (default @var{current-output-port} if omitted).
@deffn {Scheme Procedure} newline [port]
@deffnx {C Function} scm_newline (port)
Send a newline to @var{port}.
If @var{port} is omitted, send to the current output port.
@end deffn
@deffn primitive port-with-print-state port pstate
@deffn {Scheme Procedure} port-with-print-state port pstate
@deffnx {C Function} scm_port_with_print_state (port, pstate)
Create a new port which behaves like @var{port}, but with an
included print state @var{pstate}.
@end deffn
@deffn primitive print-options-interface [setting]
@deffn {Scheme Procedure} print-options-interface [setting]
@deffnx {C Function} scm_print_options (setting)
Option interface for the print options. Instead of using
this procedure directly, use the procedures
@code{print-enable}, @code{print-disable}, @code{print-set!}
and @code{print-options}.
@end deffn
@deffn primitive simple-format destination message . args
@deffn {Scheme Procedure} simple-format destination message . args
@deffnx {C Function} scm_simple_format (destination, message, args)
Write @var{message} to @var{destination}, defaulting to
the current output port.
@var{message} can contain @code{~A} (was @code{%s}) and
@ -205,12 +225,14 @@ containing the formatted text. Does not add a trailing newline.
@end deffn
@rnindex write-char
@deffn primitive write-char chr [port]
@deffn {Scheme Procedure} write-char chr [port]
@deffnx {C Function} scm_write_char (chr, port)
Send character @var{chr} to @var{port}.
@end deffn
@findex fflush
@deffn primitive force-output [port]
@deffn {Scheme Procedure} force-output [port]
@deffnx {C Function} scm_force_output (port)
Flush the specified output port, or the current output port if @var{port}
is omitted. The current output buffer contents are passed to the
underlying port implementation (e.g., in the case of fports, the
@ -220,7 +242,8 @@ It has no effect on an unbuffered port.
The return value is unspecified.
@end deffn
@deffn primitive flush-all-ports
@deffn {Scheme Procedure} flush-all-ports
@deffnx {C Function} scm_flush_all_ports ()
Equivalent to calling @code{force-output} on
all open output ports. The return value is unspecified.
@end deffn
@ -229,7 +252,8 @@ all open output ports. The return value is unspecified.
@node Closing
@section Closing
@deffn primitive close-port port
@deffn {Scheme Procedure} close-port port
@deffnx {C Function} scm_close_port (port)
Close the specified port object. Return @code{#t} if it
successfully closes a port or @code{#f} if it was already
closed. An exception may be raised if an error occurs, for
@ -239,7 +263,8 @@ descriptors.
@end deffn
@rnindex close-input-port
@deffn primitive close-input-port port
@deffn {Scheme Procedure} close-input-port port
@deffnx {C Function} scm_close_input_port (port)
Close the specified input port object. The routine has no effect if
the file has already been closed. An exception may be raised if an
error occurs. The value returned is unspecified.
@ -249,7 +274,8 @@ which can close file descriptors.
@end deffn
@rnindex close-output-port
@deffn primitive close-output-port port
@deffn {Scheme Procedure} close-output-port port
@deffnx {C Function} scm_close_output_port (port)
Close the specified output port object. The routine has no effect if
the file has already been closed. An exception may be raised if an
error occurs. The value returned is unspecified.
@ -258,7 +284,8 @@ See also @ref{Ports and File Descriptors, close}, for a procedure
which can close file descriptors.
@end deffn
@deffn primitive port-closed? port
@deffn {Scheme Procedure} port-closed? port
@deffnx {C Function} scm_port_closed_p (port)
Return @code{#t} if @var{port} is closed or @code{#f} if it is
open.
@end deffn
@ -267,7 +294,8 @@ open.
@node Random Access
@section Random Access
@deffn primitive seek fd_port offset whence
@deffn {Scheme Procedure} seek fd_port offset whence
@deffnx {C Function} scm_seek (fd_port, offset, whence)
Sets the current position of @var{fd/port} to the integer
@var{offset}, which is interpreted according to the value of
@var{whence}.
@ -293,7 +321,8 @@ that the current position of a port can be obtained using:
@end lisp
@end deffn
@deffn primitive ftell fd_port
@deffn {Scheme Procedure} ftell fd_port
@deffnx {C Function} scm_ftell (fd_port)
Return an integer representing the current position of
@var{fd/port}, measured from the beginning. Equivalent to:
@ -304,7 +333,8 @@ Return an integer representing the current position of
@findex truncate
@findex ftruncate
@deffn primitive truncate-file object [length]
@deffn {Scheme Procedure} truncate-file object [length]
@deffnx {C Function} scm_truncate_file (object, length)
Truncates the object referred to by @var{object} to at most
@var{length} bytes. @var{object} can be a string containing a
file name or an integer file descriptor or a port.
@ -328,7 +358,7 @@ module from guile-scsh, but does not use multiple values or character
sets and has an extra procedure @code{write-line}.
@c begin (scm-doc-string "rdelim.scm" "read-line")
@deffn procedure read-line [port] [handle-delim]
@deffn {Scheme Procedure} read-line [port] [handle-delim]
Return a line of text from @var{port} if specified, otherwise from the
value returned by @code{(current-input-port)}. Under Unix, a line of text
is terminated by the first end-of-line character or by end-of-file.
@ -351,7 +381,7 @@ terminating delimiter or end-of-file object.
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-line!")
@deffn procedure read-line! buf [port]
@deffn {Scheme Procedure} read-line! buf [port]
Read a line of text into the supplied string @var{buf} and return the
number of characters added to @var{buf}. If @var{buf} is filled, then
@code{#f} is returned.
@ -360,7 +390,7 @@ specified, otherwise from the value returned by @code{(current-input-port)}.
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-delimited")
@deffn procedure read-delimited delims [port] [handle-delim]
@deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
Read text until one of the characters in the string @var{delims} is found
or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
@ -368,7 +398,7 @@ from the value returned by @code{(current-input-port)}.
@end deffn
@c begin (scm-doc-string "rdelim.scm" "read-delimited!")
@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end]
@deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
Read text into the supplied string @var{buf} and return the number of
characters added to @var{buf} (subject to @var{handle-delim}, which takes
the same values specified for @code{read-line}. If @var{buf} is filled,
@ -379,7 +409,8 @@ or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
@end deffn
@deffn primitive write-line obj [port]
@deffn {Scheme Procedure} write-line obj [port]
@deffnx {C Function} scm_write_line (obj, port)
Display @var{obj} and a newline character to @var{port}. If
@var{port} is not specified, @code{(current-output-port)} is
used. This function is equivalent to:
@ -393,7 +424,8 @@ Some of the abovementioned I/O functions rely on the following C
primitives. These will mainly be of interest to people hacking Guile
internals.
@deffn primitive %read-delimited! delims str gobble [port [start [end]]]
@deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
@deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
Read characters from @var{port} into @var{str} until one of the
characters in the @var{delims} string is encountered. If
@var{gobble} is true, discard the delimiter character;
@ -411,7 +443,8 @@ at the end of file, the delimiter returned is the
a delimiter, this value is @code{#f}.
@end deffn
@deffn primitive %read-line [port]
@deffn {Scheme Procedure} %read-line [port]
@deffnx {C Function} scm_read_line (port)
Read a newline-terminated line from @var{port}, allocating storage as
necessary. The newline terminator (if any) is removed from the string,
and a pair consisting of the line and its delimiter is returned. The
@ -432,7 +465,8 @@ The Block-string-I/O module can be accessed with:
It currently contains procedures that help to implement the
@code{(scsh rw)} module in guile-scsh.
@deffn primitive read-string!/partial str [port_or_fdes [start [end]]]
@deffn {Scheme Procedure} read-string!/partial str [port_or_fdes [start [end]]]
@deffnx {C Function} scm_read_string_x_partial (str, port_or_fdes, start, end)
Read characters from a port or file descriptor into a
string @var{str}. A port must have an underlying file
descriptor --- a so-called fport. This procedure is
@ -472,7 +506,8 @@ end-of-file check.
@end itemize
@end deffn
@deffn primitive write-string/partial str [port_or_fdes start end]
@deffn {Scheme Procedure} write-string/partial str [port_or_fdes [start [end]]]
@deffnx {C Function} scm_write_string_partial (str, port_or_fdes, start, end)
Write characters from a string @var{str} to a port or file
descriptor. A port must have an underlying file descriptor
--- a so-called fport. This procedure is
@ -520,38 +555,44 @@ return 0 immediately if the request size is 0 bytes.
@section Default Ports for Input, Output and Errors
@rnindex current-input-port
@deffn primitive current-input-port
@deffn {Scheme Procedure} current-input-port
@deffnx {C Function} scm_current_input_port ()
Return the current input port. This is the default port used
by many input procedures. Initially, @code{current-input-port}
returns the @dfn{standard input} in Unix and C terminology.
@end deffn
@rnindex current-output-port
@deffn primitive current-output-port
@deffn {Scheme Procedure} current-output-port
@deffnx {C Function} scm_current_output_port ()
Return the current output port. This is the default port used
by many output procedures. Initially,
@code{current-output-port} returns the @dfn{standard output} in
Unix and C terminology.
@end deffn
@deffn primitive current-error-port
@deffn {Scheme Procedure} current-error-port
@deffnx {C Function} scm_current_error_port ()
Return the port to which errors and warnings should be sent (the
@dfn{standard error} in Unix and C terminology).
@end deffn
@deffn primitive set-current-input-port port
@deffnx primitive set-current-output-port port
@deffnx primitive set-current-error-port port
@deffn {Scheme Procedure} set-current-input-port port
@deffnx {Scheme Procedure} set-current-output-port port
@deffnx {Scheme Procedure} set-current-error-port port
@deffnx {C Function} scm_set_current_input_port (port)
@deffnx {C Function} scm_set_current_output_port (port)
@deffnx {C Function} scm_set_current_error_port (port)
Change the ports returned by @code{current-input-port},
@code{current-output-port} and @code{current-error-port}, respectively,
so that they use the supplied @var{port} for input or output.
@end deffn
@deffn primitive set-current-output-port port
@deffn {Scheme Procedure} set-current-output-port port
Set the current default output port to PORT.
@end deffn
@deffn primitive set-current-error-port port
@deffn {Scheme Procedure} set-current-error-port port
Set the current default error port to PORT.
@end deffn
@ -576,7 +617,8 @@ The following procedures are used to open file ports.
See also @ref{Ports and File Descriptors, open}, for an interface
to the Unix @code{open} system call.
@deffn primitive open-file filename mode
@deffn {Scheme Procedure} open-file filename mode
@deffnx {C Function} scm_open_file (filename, mode)
Open the file whose name is @var{filename}, and return a port
representing that file. The attributes of the port are
determined by the @var{mode} string. The way in which this is
@ -617,7 +659,7 @@ requested, @code{open-file} throws an exception.
@end deffn
@rnindex open-input-file
@deffn procedure open-input-file filename
@deffn {Scheme Procedure} open-input-file filename
Open @var{filename} for input. Equivalent to
@smalllisp
(open-file @var{filename} "r")
@ -625,7 +667,7 @@ Open @var{filename} for input. Equivalent to
@end deffn
@rnindex open-output-file
@deffn procedure open-output-file filename
@deffn {Scheme Procedure} open-output-file filename
Open @var{filename} for output. Equivalent to
@smalllisp
(open-file @var{filename} "w")
@ -633,7 +675,7 @@ Open @var{filename} for output. Equivalent to
@end deffn
@rnindex call-with-input-file
@deffn procedure call-with-input-file file proc
@deffn {Scheme Procedure} call-with-input-file file proc
@var{proc} should be a procedure of one argument, and @var{file} should
be a string naming a file. The file must already exist. These
procedures call @var{proc} with one argument: the port obtained by
@ -646,7 +688,7 @@ never again be used for a read or write operation.
@end deffn
@rnindex call-with-output-file
@deffn procedure call-with-output-file file proc
@deffn {Scheme Procedure} call-with-output-file file proc
@var{proc} should be a procedure of one argument, and @var{file} should
be a string naming a file. The behaviour is unspecified if the file
already exists. These procedures call @var{proc} with one argument: the
@ -659,7 +701,7 @@ port will never again be used for a read or write operation.
@end deffn
@rnindex with-input-from-file
@deffn procedure with-input-from-file file thunk
@deffn {Scheme Procedure} with-input-from-file file thunk
@var{thunk} must be a procedure of no arguments, and @var{file} must be
a string naming a file. The file must already exist. The file is opened
for input, an input port connected to it is made the default value
@ -672,7 +714,7 @@ dependent.
@end deffn
@rnindex with-output-to-file
@deffn procedure with-output-to-file file thunk
@deffn {Scheme Procedure} with-output-to-file file thunk
@var{thunk} must be a procedure of no arguments, and @var{file} must be
a string naming a file. The effect is unspecified if the file already
exists. The file is opened for output, an output port connected to it
@ -684,7 +726,7 @@ used to escape from the continuation of these procedures, their behavior
is implementation dependent.
@end deffn
@deffn procedure with-error-to-file file thunk
@deffn {Scheme Procedure} with-error-to-file file thunk
@var{thunk} must be a procedure of no arguments, and @var{file} must be
a string naming a file. The effect is unspecified if the file already
exists. The file is opened for output, an output port connected to it
@ -696,27 +738,31 @@ from the continuation of these procedures, their behavior is
implementation dependent.
@end deffn
@deffn primitive port-mode port
Returns the port modes associated with the open port @var{port}. These
will not necessarily be identical to the modes used when the port was
opened, since modes such as "append" which are used only during
port creation are not retained.
@deffn {Scheme Procedure} port-mode port
@deffnx {C Function} scm_port_mode (port)
Return the port modes associated with the open port @var{port}.
These will not necessarily be identical to the modes used when
the port was opened, since modes such as "append" which are
used only during port creation are not retained.
@end deffn
@deffn primitive port-filename port
@deffn {Scheme Procedure} port-filename port
@deffnx {C Function} scm_port_filename (port)
Return the filename associated with @var{port}. This function returns
the strings "standard input", "standard output" and "standard error"
when called on the current input, output and error ports respectively.
@end deffn
@deffn primitive set-port-filename! port filename
@deffn {Scheme Procedure} set-port-filename! port filename
@deffnx {C Function} scm_set_port_filename_x (port, filename)
Change the filename associated with @var{port}, using the current input
port if none is specified. Note that this does not change the port's
source of data, but only the value that is returned by
@code{port-filename} and reported in diagnostic output.
@end deffn
@deffn primitive file-port? obj
@deffn {Scheme Procedure} file-port? obj
@deffnx {C Function} scm_file_port_p (obj)
Determine whether @var{obj} is a port that is related to a file.
@end deffn
@ -727,38 +773,42 @@ Determine whether @var{obj} is a port that is related to a file.
The following allow string ports to be opened by analogy to R4R*
file port facilities:
@deffn primitive call-with-output-string proc
@deffn {Scheme Procedure} call-with-output-string proc
@deffnx {C Function} scm_call_with_output_string (proc)
Calls the one-argument procedure @var{proc} with a newly created output
port. When the function returns, the string composed of the characters
written into the port is returned.
@end deffn
@deffn primitive call-with-input-string string proc
@deffn {Scheme Procedure} call-with-input-string string proc
@deffnx {C Function} scm_call_with_input_string (string, proc)
Calls the one-argument procedure @var{proc} with a newly
created input port from which @var{string}'s contents may be
read. The value yielded by the @var{proc} is returned.
@end deffn
@deffn procedure with-output-to-string thunk
@deffn {Scheme Procedure} with-output-to-string thunk
Calls the zero-argument procedure @var{thunk} with the current output
port set temporarily to a new string port. It returns a string
composed of the characters written to the current output.
@end deffn
@deffn procedure with-input-from-string string thunk
@deffn {Scheme Procedure} with-input-from-string string thunk
Calls the zero-argument procedure @var{thunk} with the current input
port set temporarily to a string port opened on the specified
@var{string}. The value yielded by @var{thunk} is returned.
@end deffn
@deffn primitive open-input-string str
@deffn {Scheme Procedure} open-input-string str
@deffnx {C Function} scm_open_input_string (str)
Take a string and return an input port that delivers characters
from the string. The port can be closed by
@code{close-input-port}, though its storage will be reclaimed
by the garbage collector if it becomes inaccessible.
@end deffn
@deffn primitive open-output-string
@deffn {Scheme Procedure} open-output-string
@deffnx {C Function} scm_open_output_string ()
Return an output port that will accumulate characters for
retrieval by @code{get-output-string}. The port can be closed
by the procedure @code{close-output-port}, though its storage
@ -766,7 +816,8 @@ will be reclaimed by the garbage collector if it becomes
inaccessible.
@end deffn
@deffn primitive get-output-string port
@deffn {Scheme Procedure} get-output-string port
@deffnx {C Function} scm_get_output_string (port)
Given an output port created by @code{open-output-string},
return a string consisting of the characters that have been
output to the port so far.
@ -784,7 +835,8 @@ but trying to extract the file descriptor number will fail.
A @dfn{soft-port} is a port based on a vector of procedures capable of
accepting or delivering characters. It allows emulation of I/O ports.
@deffn primitive make-soft-port pv modes
@deffn {Scheme Procedure} make-soft-port pv modes
@deffnx {C Function} scm_make_soft_port (pv, modes)
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
@ -835,11 +887,12 @@ For example:
This kind of port causes any data to be discarded when written to, and
always returns the end-of-file object when read from.
@deffn primitive %make-void-port mode
@deffn {Scheme Procedure} %make-void-port mode
@deffnx {C Function} scm_sys_make_void_port (mode)
Create and return a new void port. A void port acts like
@code{/dev/null}. The @var{mode} argument specifies the input/output
modes for this port: see the documentation for @code{open-file} in
@ref{File Ports}.
/dev/null. The @var{mode} argument
specifies the input/output modes for this port: see the
documentation for @code{open-file} in @ref{File Ports}.
@end deffn

78
doc/ref/scheme-memory.texi
View file

@ -15,26 +15,24 @@
[FIXME: this is pasted in from Tom Lord's original guile.texi and should
be reviewed]
@deffn primitive gc
@deffn {Scheme Procedure} gc
@deffnx {C Function} scm_gc ()
Scans all of SCM objects and reclaims for further use those that are
no longer accessible.
@end deffn
@deffn primitive gc-stats
@deffn {Scheme Procedure} gc-stats
@deffnx {C Function} scm_gc_stats ()
Return an association list of statistics about Guile's current
use of storage.
@end deffn
@deffn primitive object-address obj
@deffn {Scheme Procedure} object-address obj
@deffnx {C Function} scm_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
@ -84,9 +82,12 @@ they constitute a doubly-weak table has to be used.
@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
@deffn {Scheme Procedure} make-weak-key-hash-table size
@deffnx {Scheme Procedure} make-weak-value-hash-table size
@deffnx {Scheme Procedure} make-doubly-weak-hash-table size
@deffnx {C Function} scm_make_weak_key_hash_table (size)
@deffnx {C Function} scm_make_weak_value_hash_table (size)
@deffnx {C Function} scm_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.
@ -95,24 +96,27 @@ 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
@deffn {Scheme Procedure} weak-key-hash-table? obj
@deffnx {Scheme Procedure} weak-value-hash-table? obj
@deffnx {Scheme Procedure} doubly-weak-hash-table? obj
@deffnx {C Function} scm_weak_key_hash_table_p (obj)
@deffnx {C Function} scm_weak_value_hash_table_p (obj)
@deffnx {C Function} scm_doubly_weak_hash_table_p (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
@deffn {Scheme Procedure} make-weak-value-hash-table k
@end deffn
@deffn primitive weak-value-hash-table? x
@deffn {Scheme Procedure} weak-value-hash-table? x
@end deffn
@deffn primitive make-doubly-weak-hash-table k
@deffn {Scheme Procedure} make-doubly-weak-hash-table k
@end deffn
@deffn primitive doubly-weak-hash-table? x
@deffn {Scheme Procedure} doubly-weak-hash-table? x
@end deffn
@ -122,22 +126,25 @@ nor a weak value hash table.
Weak vectors are mainly useful in Guile's implementation of weak hash
tables.
@deffn primitive make-weak-vector size [fill]
@deffn {Scheme Procedure} make-weak-vector size [fill]
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} weak-vector . l
@deffnx {Scheme Procedure} list->weak-vector l
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} weak-vector? obj
@deffnx {C Function} scm_weak_vector_p (obj)
Return @code{#t} if @var{obj} is a weak vector. Note that all
weak hashes are also weak vectors.
@end deffn
@ -146,7 +153,8 @@ weak hashes are also weak vectors.
@node Guardians
@section Guardians
@deffn primitive make-guardian [greedy?]
@deffn {Scheme Procedure} make-guardian [greedy?]
@deffnx {C Function} scm_make_guardian (greedy_p)
Create a new guardian.
A guardian protects a set of objects from garbage collection,
allowing a program to apply cleanup or other actions.
@ -174,17 +182,20 @@ and Implementation, June 1993.
paper still (mostly) accurately describes the interface).
@end deffn
@deffn primitive destroy-guardian! guardian
@deffn {Scheme Procedure} destroy-guardian! guardian
@deffnx {C Function} scm_destroy_guardian_x (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
@deffn {Scheme Procedure} guardian-greedy? guardian
@deffnx {C Function} scm_guardian_greedy_p (guardian)
Return @code{#t} if @var{guardian} is a greedy guardian, otherwise @code{#f}.
@end deffn
@deffn primitive guardian-destroyed? guardian
@deffn {Scheme Procedure} guardian-destroyed? guardian
@deffnx {C Function} scm_guardian_destroyed_p (guardian)
Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
@end deffn
@ -193,25 +204,30 @@ Return @code{#t} if @var{guardian} has been destroyed, otherwise @code{#f}.
@node Objects
@chapter Objects
@deffn primitive entity? obj
@deffn {Scheme Procedure} entity? obj
@deffnx {C Function} scm_entity_p (obj)
Return @code{#t} if @var{obj} is an entity.
@end deffn
@deffn primitive operator? obj
@deffn {Scheme Procedure} operator? obj
@deffnx {C Function} scm_operator_p (obj)
Return @code{#t} if @var{obj} is an operator.
@end deffn
@deffn primitive set-object-procedure! obj proc
@deffn {Scheme Procedure} set-object-procedure! obj proc
@deffnx {C Function} scm_set_object_procedure_x (obj, proc)
Set 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
@deffn {Scheme Procedure} make-class-object metaclass layout
@deffnx {C Function} scm_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
@deffn {Scheme Procedure} make-subclass-object class layout
@deffnx {C Function} scm_make_subclass_object (class, layout)
Create a subclass object of @var{class}, with the slot layout
specified by @var{layout}.
@end deffn

76
doc/ref/scheme-modules.texi
View file

@ -193,7 +193,7 @@ This example also shows how to use the convenience procedure
@code{symbol-prefix-proc}.
@c begin (scm-doc-string "boot-9.scm" "symbol-prefix-proc")
@deffn procedure symbol-prefix-proc prefix-sym
@deffn {Scheme Procedure} symbol-prefix-proc prefix-sym
Return a procedure that prefixes its arg (a symbol) with
@var{prefix-sym}.
@c Insert gratuitous C++ slam here. --ttn
@ -332,7 +332,8 @@ The procedures in this section are useful if you want to dig into the
innards of Guile's module system. If you don't know precisely what you
do, you should probably avoid using any of them.
@deffn primitive standard-eval-closure module
@deffn {Scheme Procedure} standard-eval-closure module
@deffnx {C Function} scm_standard_eval_closure (module)
Return an eval closure for the module @var{module}.
@end deffn
@ -495,7 +496,8 @@ When using the low level procedures to do your dynamic linking, you have
complete control over which library is loaded when and what get's done
with it.
@deffn primitive dynamic-link library
@deffn {Scheme Procedure} dynamic-link library
@deffnx {C Function} scm_dynamic_link (library)
Find the shared library denoted by @var{library} (a string) and link it
into the running Guile application. When everything works out, return a
Scheme object suitable for representing the linked object file.
@ -507,24 +509,26 @@ that will be searched for in the places where shared libraries usually
reside, such as in @file{/usr/lib} and @file{/usr/local/lib}.
@end deffn
@deffn primitive dynamic-object? val
Determine whether @var{val} represents a dynamically linked object file.
@deffn {Scheme Procedure} dynamic-object? obj
@deffnx {C Function} scm_dynamic_object_p (obj)
Return @code{#t} if @var{obj} is a dynamic library handle, or @code{#f}
otherwise.
@end deffn
@deffn primitive dynamic-unlink dynobj
Unlink the indicated object file from the application. The argument
@var{dynobj} should be one of the values returned by
@code{dynamic-link}. When @code{dynamic-unlink} has been called on
@var{dynobj}, it is no longer usable as an argument to the functions
below and you will get type mismatch errors when you try to.
@deffn {Scheme Procedure} dynamic-unlink dobj
@deffnx {C Function} scm_dynamic_unlink (dobj)
Unlink the indicated object file from the application. The
argument @var{dobj} must have been obtained by a call to
@code{dynamic-link}. After @code{dynamic-unlink} has been
called on @var{dobj}, its content is no longer accessible.
@end deffn
@deffn primitive dynamic-func function dynobj
Search the C function indicated by @var{function} (a string or symbol)
in @var{dynobj} and return some Scheme object that can later be used
with @code{dynamic-call} to actually call this function. Right now,
these Scheme objects are formed by casting the address of the function
to @code{long} and converting this number to its Scheme representation.
@deffn {Scheme Procedure} dynamic-func name dobj
@deffnx {C Function} scm_dynamic_func (name, dobj)
Search the dynamic object @var{dobj} for the C function
indicated by the string @var{name} and return some Scheme
handle that can later be used with @code{dynamic-call} to
actually call the function.
Regardless whether your C compiler prepends an underscore @samp{_} to
the global names in a program, you should @strong{not} include this
@ -532,35 +536,37 @@ underscore in @var{function}. Guile knows whether the underscore is
needed or not and will add it when necessary.
@end deffn
@deffn primitive dynamic-call function dynobj
Call the C function indicated by @var{function} and @var{dynobj}. The
function is passed no arguments and its return value is ignored. When
@var{function} is something returned by @code{dynamic-func}, call that
function and ignore @var{dynobj}. When @var{function} is a string (or
symbol, etc.), look it up in @var{dynobj}; this is equivalent to
@deffn {Scheme Procedure} dynamic-call func dobj
@deffnx {C Function} scm_dynamic_call (func, dobj)
Call the C function indicated by @var{func} and @var{dobj}.
The function is passed no arguments and its return value is
ignored. When @var{function} is something returned by
@code{dynamic-func}, call that function and ignore @var{dobj}.
When @var{func} is a string , look it up in @var{dynobj}; this
is equivalent to
@smallexample
(dynamic-call (dynamic-func @var{function} @var{dynobj} #f))
(dynamic-call (dynamic-func @var{func} @var{dobj} #f))
@end smallexample
Interrupts are deferred while the C function is executing (with
@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).
@end deffn
@deffn primitive dynamic-args-call function dynobj args
Call the C function indicated by @var{function} and @var{dynobj}, just
like @code{dynamic-call}, but pass it some arguments and return its
return value. The C function is expected to take two arguments and
return an @code{int}, just like @code{main}:
@deffn {Scheme Procedure} dynamic-args-call func dobj args
@deffnx {C Function} scm_dynamic_args_call (func, dobj, args)
Call the C function indicated by @var{func} and @var{dobj},
just like @code{dynamic-call}, but pass it some arguments and
return its return value. The C function is expected to take
two arguments and return an @code{int}, just like @code{main}:
@smallexample
int c_func (int argc, char **argv);
@end smallexample
The parameter @var{args} must be a list of strings and is converted into
an array of @code{char *}. The array is passed in @var{argv} and its
size in @var{argc}. The return value is converted to a Scheme number
and returned from the call to @code{dynamic-args-call}.
The parameter @var{args} must be a list of strings and is
converted into an array of @code{char *}. The array is passed
in @var{argv} and its size in @var{argc}. The return value is
converted to a Scheme number and returned from the call to
@code{dynamic-args-call}.
@end deffn
When dynamic linking is disabled or not supported on your system,

69
doc/ref/scheme-options.texi
View file

@ -34,11 +34,11 @@ We will use the expression @code{<group>} to represent @code{read},
@subheading Low level
@c NJFIXME
@deffn primitive <group>-options-interface
@deffnx primitive read-options-interface [SOME-INT]
@deffnx primitive print-options-interface [SOME-INT]
@deffnx primitive evaluator-traps-interface [SOME-INT]
@deffnx primitive read-options-interface [SOME-INT]
@deffn {Scheme Procedure} <group>-options-interface
@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
@deffnx {Scheme Procedure} print-options-interface [SOME-INT]
@deffnx {Scheme Procedure} evaluator-traps-interface [SOME-INT]
@deffnx {Scheme Procedure} read-options-interface [SOME-INT]
[FIXME: I have just taken the comments for C routine scm_options that
implements all of these. It needs to be presented better.]
@ -59,11 +59,11 @@ and documentation string.
@c @end deftp
@c NJFIXME
@deffn procedure <group>-options [arg]
@deffnx procedure read-options [arg]
@deffnx procedure print-options [arg]
@deffnx procedure debug-options [arg]
@deffnx procedure traps [arg]
@deffn {Scheme Procedure} <group>-options [arg]
@deffnx {Scheme Procedure} read-options [arg]
@deffnx {Scheme Procedure} print-options [arg]
@deffnx {Scheme Procedure} debug-options [arg]
@deffnx {Scheme Procedure} traps [arg]
These functions list the options in their group. The optional argument
@var{arg} is a symbol which modifies the form in which the options are
presented.
@ -81,22 +81,22 @@ options) and symbols followed by values.
up?]
@c NJFIXME
@deffn procedure <group>-enable option-symbol
@deffnx procedure read-enable option-symbol
@deffnx procedure print-enable option-symbol
@deffnx procedure debug-enable option-symbol
@deffnx procedure trap-enable option-symbol
@deffn {Scheme Procedure} <group>-enable option-symbol
@deffnx {Scheme Procedure} read-enable option-symbol
@deffnx {Scheme Procedure} print-enable option-symbol
@deffnx {Scheme Procedure} debug-enable option-symbol
@deffnx {Scheme Procedure} trap-enable option-symbol
These functions set the specified @var{option-symbol} in their options
group. They only work if the option is boolean, and throw an error
otherwise.
@end deffn
@c NJFIXME
@deffn procedure <group>-disable option-symbol
@deffnx procedure read-disable option-symbol
@deffnx procedure print-disable option-symbol
@deffnx procedure debug-disable option-symbol
@deffnx procedure trap-disable option-symbol
@deffn {Scheme Procedure} <group>-disable option-symbol
@deffnx {Scheme Procedure} read-disable option-symbol
@deffnx {Scheme Procedure} print-disable option-symbol
@deffnx {Scheme Procedure} debug-disable option-symbol
@deffnx {Scheme Procedure} trap-disable option-symbol
These functions turn off the specified @var{option-symbol} in their
options group. They only work if the option is boolean, and throw an
error otherwise.
@ -331,10 +331,14 @@ It is often useful to have site-specific information about the current
Guile installation. This chapter describes how to find out about
Guile's configuration at run time.
@deffn primitive version
@deffnx primitive major-version
@deffnx primitive minor-version
@deffnx primitive micro-version
@deffn {Scheme Procedure} version
@deffnx {Scheme Procedure} major-version
@deffnx {Scheme Procedure} minor-version
@deffnx {Scheme Procedure} micro-version
@deffnx {C Function} scm_version ()
@deffnx {C Function} scm_major_version ()
@deffnx {C Function} scm_minor_version ()
@deffnx {C Function} scm_micro_version ()
Return a string describing Guile's version number, or its major, minor
or micro version number, respectively.
@ -347,37 +351,42 @@ or micro version number, respectively.
@end deffn
@c NJFIXME not in libguile!
@deffn primitive libguile-config-stamp
@deffn {Scheme Procedure} libguile-config-stamp
Return a string describing the date on which @code{libguile} was
configured. This is used to determine whether the Guile core
interpreter and the ice-9 runtime have grown out of date with one
another.
@end deffn
@deffn primitive %package-data-dir
@deffn {Scheme Procedure} %package-data-dir
@deffnx {C Function} scm_sys_package_data_dir ()
Return the name of the directory where Scheme packages, modules and
libraries are kept. On most Unix systems, this will be
@samp{/usr/local/share/guile}.
@end deffn
@deffn primitive %library-dir
@deffn {Scheme Procedure} %library-dir
@deffnx {C Function} scm_sys_library_dir ()
Return the directory where the Guile Scheme library files are installed.
E.g., may return "/usr/share/guile/1.3.5".
@end deffn
@deffn primitive %site-dir
@deffn {Scheme Procedure} %site-dir
@deffnx {C Function} scm_sys_site_dir ()
Return the directory where the Guile site files are installed.
E.g., may return "/usr/share/guile/site".
@end deffn
@deffn primitive parse-path path [tail]
@deffn {Scheme Procedure} parse-path path [tail]
@deffnx {C Function} scm_parse_path (path, tail)
Parse @var{path}, which is expected to be a colon-separated
string, into a list and return the resulting list with
@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
is returned.
@end deffn
@deffn primitive search-path path filename [extensions]
@deffn {Scheme Procedure} search-path path filename [extensions]
@deffnx {C Function} scm_search_path (path, filename, extensions)
Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory.
If we find one, return its full filename; otherwise, return

94
doc/ref/scheme-procedures.texi
View file

@ -347,15 +347,18 @@ for primitive procedures, and @code{thunk?} only returns @code{#t} for
procedures which do not accept any arguments.
@rnindex procedure?
@deffn primitive procedure? obj
@deffn {Scheme Procedure} procedure? obj
@deffnx {C Function} scm_procedure_p (obj)
Return @code{#t} if @var{obj} is a procedure.
@end deffn
@deffn primitive closure? obj
@deffn {Scheme Procedure} closure? obj
@deffnx {C Function} scm_closure_p (obj)
Return @code{#t} if @var{obj} is a closure.
@end deffn
@deffn primitive thunk? obj
@deffn {Scheme Procedure} thunk? obj
@deffnx {C Function} scm_thunk_p (obj)
Return @code{#t} if @var{obj} is a thunk.
@end deffn
@ -365,19 +368,23 @@ Procedure properties are general properties to be attached to
procedures. These can be the name of a procedure or other relevant
information, such as debug hints.
@deffn primitive procedure-properties proc
@deffn {Scheme Procedure} procedure-properties proc
@deffnx {C Function} scm_procedure_properties (proc)
Return @var{obj}'s property list.
@end deffn
@deffn primitive procedure-property p k
@deffn {Scheme Procedure} procedure-property obj key
@deffnx {C Function} scm_procedure_property (obj, key)
Return the property of @var{obj} with name @var{key}.
@end deffn
@deffn primitive set-procedure-properties! proc new_val
@deffn {Scheme Procedure} set-procedure-properties! proc alist
@deffnx {C Function} scm_set_procedure_properties_x (proc, alist)
Set @var{obj}'s property list to @var{alist}.
@end deffn
@deffn primitive set-procedure-property! p k v
@deffn {Scheme Procedure} set-procedure-property! obj key value
@deffnx {C Function} scm_set_procedure_property_x (obj, key, value)
In @var{obj}'s property list, set the property named @var{key} to
@var{value}.
@end deffn
@ -386,7 +393,8 @@ In @var{obj}'s property list, set the property named @var{key} to
Documentation for a procedure can be accessed with the procedure
@code{procedure-documentation}.
@deffn primitive procedure-documentation proc
@deffn {Scheme Procedure} procedure-documentation proc
@deffnx {C Function} scm_procedure_documentation (proc)
Return the documentation string associated with @code{proc}. By
convention, if a procedure contains more than one expression and the
first expression is a string constant, that string is assumed to contain
@ -398,22 +406,26 @@ documentation for that procedure.
Source properties are properties which are related to the source code of
a procedure, such as the line and column numbers, the file name etc.
@deffn primitive set-source-properties! obj plist
@deffn {Scheme Procedure} set-source-properties! obj plist
@deffnx {C Function} scm_set_source_properties_x (obj, plist)
Install the association list @var{plist} as the source property
list for @var{obj}.
@end deffn
@deffn primitive set-source-property! obj key datum
@deffn {Scheme Procedure} set-source-property! obj key datum
@deffnx {C Function} scm_set_source_property_x (obj, key, datum)
Set the source property of object @var{obj}, which is specified by
@var{key} to @var{datum}. Normally, the key will be a symbol.
@end deffn
@deffn primitive source-properties obj
@deffn {Scheme Procedure} source-properties obj
@deffnx {C Function} scm_source_properties (obj)
Return the source property association list of @var{obj}.
@end deffn
@deffn primitive source-property obj key
@deffn {Scheme Procedure} source-property obj key
@deffnx {C Function} scm_source_property (obj, key)
Return the source property specified by @var{key} from
@var{obj}'s source property list.
@end deffn
@ -480,22 +492,25 @@ structure stored in @code{f}, or to write into the structure.
(foo f 0) @result{} dum
@end lisp
@deffn primitive make-procedure-with-setter procedure setter
@deffn {Scheme Procedure} make-procedure-with-setter procedure setter
@deffnx {C Function} scm_make_procedure_with_setter (procedure, setter)
Create a new procedure which behaves like @var{procedure}, but
with the associated setter @var{setter}.
@end deffn
@deffn primitive procedure-with-setter? obj
@deffn {Scheme Procedure} procedure-with-setter? obj
@deffnx {C Function} scm_procedure_with_setter_p (obj)
Return @code{#t} if @var{obj} is a procedure with an
associated setter procedure.
@end deffn
@deffn primitive procedure proc
@deffn {Scheme Procedure} procedure proc
@deffnx {C Function} scm_procedure (proc)
Return the procedure of @var{proc}, which must be either a
procedure with setter, or an operator struct.
@end deffn
@deffn primitive setter proc
@deffn {Scheme Procedure} setter proc
Return the setter of @var{proc}, which must be either a procedure with
setter or an operator struct.
@end deffn
@ -710,30 +725,34 @@ change. Use @code{defmacro}, @code{define-macro} (@pxref{Macros}) or
terms, @code{defmacro}, @code{define-macro} and @code{define-syntax} are
all implemented as mmacros.)
@deffn primitive procedure->syntax code
Return a macro which, when a symbol defined to this value appears as the
first symbol in an expression, returns the result of applying @var{code}
to the expression and the environment.
@deffn {Scheme Procedure} procedure->syntax code
@deffnx {C Function} scm_makacro (code)
Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, returns the
result of applying @var{code} to the expression and the
environment.
@end deffn
@deffn primitive procedure->macro code
Return a macro which, when a symbol defined to this value appears as the
first symbol in an expression, evaluates the result of applying
@var{code} to the expression and the environment. For example:
@deffn {Scheme Procedure} procedure->macro code
@deffnx {C Function} scm_makmacro (code)
Return a @dfn{macro} which, when a symbol defined to this value
appears as the first symbol in an expression, evaluates the
result of applying @var{code} to the expression and the
environment. The value returned from @var{code} which has been
passed to @code{procedure->memoizing-macro} replaces the form
passed to @var{code}. For example:
@lisp
(define trace
(procedure->macro
(lambda (x env)
`(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
(lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
(trace @i{foo})
@equiv{}
(set! @i{foo} (tracef @i{foo} '@i{foo})).
(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).
@end lisp
@end deffn
@deffn primitive procedure->memoizing-macro code
@deffn {Scheme Procedure} procedure->memoizing-macro code
@deffnx {C Function} scm_makmmacro (code)
Return a macro which, when a symbol defined to this value appears as the
first symbol in an expression, evaluates the result of applying
@var{code} to the expression and the environment.
@ -746,12 +765,14 @@ of the containing code.
In the following primitives, @dfn{acro} flavour macros are referred to
as @dfn{syntax transformers}.
@deffn primitive macro? obj
@deffn {Scheme Procedure} macro? obj
@deffnx {C Function} scm_macro_p (obj)
Return @code{#t} if @var{obj} is a regular macro, a memoizing macro or a
syntax transformer.
@end deffn
@deffn primitive macro-type m
@deffn {Scheme Procedure} macro-type m
@deffnx {C Function} scm_macro_type (m)
Return one of the symbols @code{syntax}, @code{macro} or
@code{macro!}, depending on whether @var{m} is a syntax
transformer, a regular macro, or a memoizing macro,
@ -759,15 +780,18 @@ respectively. If @var{m} is not a macro, @code{#f} is
returned.
@end deffn
@deffn primitive macro-name m
@deffn {Scheme Procedure} macro-name m
@deffnx {C Function} scm_macro_name (m)
Return the name of the macro @var{m}.
@end deffn
@deffn primitive macro-transformer m
@deffn {Scheme Procedure} macro-transformer m
@deffnx {C Function} scm_macro_transformer (m)
Return the transformer of the macro @var{m}.
@end deffn
@deffn primitive cons-source xorig x y
@deffn {Scheme Procedure} cons-source xorig x y
@deffnx {C Function} scm_cons_source (xorig, x, y)
Create and return a new pair whose car and cdr are @var{x} and @var{y}.
Any source properties associated with @var{xorig} are also associated
with the new pair.

80
doc/ref/scheme-scheduling.texi
View file

@ -30,18 +30,21 @@ otherwise it will fail and return @code{#f}. Once an arbiter is
successfully locked, it cannot be locked by another thread until the
thread holding the arbiter calls @code{release-arbiter} to unlock it.
@deffn primitive make-arbiter name
@deffn {Scheme Procedure} make-arbiter name
@deffnx {C Function} scm_make_arbiter (name)
Return an object of type arbiter and name @var{name}. Its
state is initially unlocked. Arbiters are a way to achieve
process synchronization.
@end deffn
@deffn primitive try-arbiter arb
@deffn {Scheme Procedure} try-arbiter arb
@deffnx {C Function} scm_try_arbiter (arb)
Return @code{#t} and lock the arbiter @var{arb} if the arbiter
was unlocked. Otherwise, return @code{#f}.
@end deffn
@deffn primitive release-arbiter arb
@deffn {Scheme Procedure} release-arbiter arb
@deffnx {C Function} scm_release_arbiter (arb)
Return @code{#t} and unlock the arbiter @var{arb} if the
arbiter was locked. Otherwise, return @code{#f}.
@end deffn
@ -70,20 +73,24 @@ Normal asyncs are created with @code{async}, system asyncs with
@code{system-async}. They are marked with @code{async-mark} or
@code{system-async-mark}, respectively.
@deffn primitive async thunk
@deffn {Scheme Procedure} async thunk
@deffnx {C Function} scm_async (thunk)
Create a new async for the procedure @var{thunk}.
@end deffn
@deffn primitive system-async thunk
@deffn {Scheme Procedure} system-async thunk
@deffnx {C Function} scm_system_async (thunk)
Create a new async for the procedure @var{thunk}. Also
add it to the system's list of active async objects.
@end deffn
@deffn primitive async-mark a
@deffn {Scheme Procedure} async-mark a
@deffnx {C Function} scm_async_mark (a)
Mark the async @var{a} for future execution.
@end deffn
@deffn primitive system-async-mark a
@deffn {Scheme Procedure} system-async-mark a
@deffnx {C Function} scm_system_async_mark (a)
Mark the async @var{a} for future execution.
@end deffn
@ -91,7 +98,8 @@ As already mentioned above, system asyncs are executed automatically.
Normal asyncs have to be explicitly invoked by storing one or more of
them into a list and passing them to @code{run-asyncs}.
@deffn primitive run-asyncs list_of_a
@deffn {Scheme Procedure} run-asyncs list_of_a
@deffnx {C Function} scm_run_asyncs (list_of_a)
Execute all thunks from the asyncs of the list @var{list_of_a}.
@end deffn
@ -102,18 +110,21 @@ run once execution is enabled again. Please note that calls to these
procedures should always be paired, and they must not be nested, e.g. no
@code{mask-signals} is allowed if another one is still active.
@deffn primitive mask-signals
@deffn {Scheme Procedure} mask-signals
@deffnx {C Function} scm_mask_signals ()
Mask signals. The returned value is not specified.
@end deffn
@deffn primitive unmask-signals
@deffn {Scheme Procedure} unmask-signals
@deffnx {C Function} scm_unmask_signals ()
Unmask signals. The returned value is not specified.
@end deffn
@c FIXME::martin: Find an example for usage of `noop'. What is that
@c procedure for anyway?
@deffn primitive noop . args
@deffn {Scheme Procedure} noop . args
@deffnx {C Function} scm_noop (args)
Do nothing. When called without arguments, return @code{#f},
otherwise return the first argument.
@end deffn
@ -139,7 +150,8 @@ dynamic root. For example, if you want to apply a procedure, but to
not allow that procedure to capture the current continuation, calling
the procedure under a new dynamic root will do the job.
@deffn primitive call-with-dynamic-root thunk handler
@deffn {Scheme Procedure} call-with-dynamic-root thunk handler
@deffnx {C Function} scm_call_with_dynamic_root (thunk, handler)
Evaluate @code{(thunk)} in a new dynamic context, returning its value.
If an error occurs during evaluation, apply @var{handler} to the
@ -185,7 +197,8 @@ be under a new dynamic root.)
@end deffn
@deffn primitive dynamic-root
@deffn {Scheme Procedure} dynamic-root
@deffnx {C Function} scm_dynamic_root ()
Return an object representing the current dynamic root.
These objects are only useful for comparison using @code{eq?}.
@ -194,7 +207,7 @@ in no way depend on this.
@end deffn
@c begin (scm-doc-string "boot-9.scm" "quit")
@deffn procedure quit [exit_val]
@deffn {Scheme Procedure} quit [exit_val]
Throw back to the error handler of the current dynamic root.
If integer @var{exit_val} is specified and if Guile is being used
@ -215,12 +228,12 @@ from Scheme code to be removed. An example of where this is useful is
after forking a new process intended to run non-interactively.
@c begin (scm-doc-string "boot-9.scm" "batch-mode?")
@deffn procedure batch-mode?
@deffn {Scheme Procedure} batch-mode?
Returns a boolean indicating whether the interpreter is in batch mode.
@end deffn
@c begin (scm-doc-string "boot-9.scm" "set-batch-mode?!")
@deffn procedure set-batch-mode?! arg
@deffn {Scheme Procedure} set-batch-mode?! arg
If @var{arg} is true, switches the interpreter to batch mode.
The @code{#f} case has not been implemented.
@end deffn
@ -258,7 +271,7 @@ executed in a new dynamic root.
@c are in sync.
@c begin (texi-doc-string "guile" "call-with-new-thread")
@deffn primitive call-with-new-thread thunk error-handler
@deffn {Scheme Procedure} call-with-new-thread thunk error-handler
Evaluate @code{(thunk)} in a new thread, and new dynamic context,
returning a new thread object representing the thread.
@ -273,31 +286,31 @@ All the evaluation rules for dynamic roots apply to threads.
@end deffn
@c begin (texi-doc-string "guile" "join-thread")
@deffn primitive join-thread thread
@deffn {Scheme Procedure} join-thread thread
Suspend execution of the calling thread until the target @var{thread}
terminates, unless the target @var{thread} has already terminated.
@end deffn
@c begin (texi-doc-string "guile" "yield")
@deffn primitive yield
@deffn {Scheme Procedure} yield
If one or more threads are waiting to execute, calling yield forces an
immediate context switch to one of them. Otherwise, yield has no effect.
@end deffn
@c begin (texi-doc-string "guile" "make-mutex")
@deffn primitive make-mutex
@deffn {Scheme Procedure} make-mutex
Create a new mutex object.
@end deffn
@c begin (texi-doc-string "guile" "lock-mutex")
@deffn primitive lock-mutex mutex
@deffn {Scheme Procedure} lock-mutex mutex
Lock @var{mutex}. If the mutex is already locked, the calling thread
blocks until the mutex becomes available. The function returns when
the calling thread owns the lock on @var{mutex}.
@end deffn
@c begin (texi-doc-string "guile" "unlock-mutex")
@deffn primitive unlock-mutex mutex
@deffn {Scheme Procedure} unlock-mutex mutex
Unlocks @var{mutex} if the calling thread owns the lock on @var{mutex}.
Calling unlock-mutex on a mutex not owned by the current thread results
in undefined behaviour. Once a mutex has been unlocked, one thread
@ -305,15 +318,15 @@ blocked on @var{mutex} is awakened and grabs the mutex lock.
@end deffn
@c begin (texi-doc-string "guile" "make-condition-variable")
@deffn primitive make-condition-variable
@deffn {Scheme Procedure} make-condition-variable
@end deffn
@c begin (texi-doc-string "guile" "wait-condition-variable")
@deffn primitive wait-condition-variable cond-var mutex
@deffn {Scheme Procedure} wait-condition-variable cond-var mutex
@end deffn
@c begin (texi-doc-string "guile" "signal-condition-variable")
@deffn primitive signal-condition-variable cond-var
@deffn {Scheme Procedure} signal-condition-variable cond-var
@end deffn
@ -326,7 +339,7 @@ Higher level thread procedures are available by loading the
@code{(ice-9 threads)} module. These provide standardized
thread creation and mutex interaction.
@deffn primitive %thread-handler tag args@dots{}
@deffn {Scheme Procedure} %thread-handler tag args@dots{}
This procedure is specified as the standard error-handler for
@code{make-thread} and @code{begin-thread}. If the number of @var{args}
@ -390,7 +403,8 @@ in Scheme---this cannot happen. See the description of
New fluids are created with @code{make-fluid} and @code{fluid?} is used
for testing whether an object is actually a fluid.
@deffn primitive make-fluid
@deffn {Scheme Procedure} make-fluid
@deffnx {C Function} scm_make_fluid ()
Return a newly created fluid.
Fluids are objects of a certain type (a smob) that can hold one SCM
value per dynamic root. That is, modifications to this value are
@ -400,7 +414,8 @@ inherits the values from its parent. Because each thread executes
in its own dynamic root, you can use fluids for thread local storage.
@end deffn
@deffn primitive fluid? obj
@deffn {Scheme Procedure} fluid? obj
@deffnx {C Function} scm_fluid_p (obj)
Return @code{#t} iff @var{obj} is a fluid; otherwise, return
@code{#f}.
@end deffn
@ -408,13 +423,15 @@ Return @code{#t} iff @var{obj} is a fluid; otherwise, return
The values stored in a fluid can be accessed with @code{fluid-ref} and
@code{fluid-set!}.
@deffn primitive fluid-ref fluid
@deffn {Scheme Procedure} fluid-ref fluid
@deffnx {C Function} scm_fluid_ref (fluid)
Return the value associated with @var{fluid} in the current
dynamic root. If @var{fluid} has not been set, then return
@code{#f}.
@end deffn
@deffn primitive fluid-set! fluid value
@deffn {Scheme Procedure} fluid-set! fluid value
@deffnx {C Function} scm_fluid_set_x (fluid, value)
Set the value associated with @var{fluid} in the current dynamic root.
@end deffn
@ -422,7 +439,8 @@ Set the value associated with @var{fluid} in the current dynamic root.
so that the given procedure and each procedure called by it access the
given values. After the procedure returns, the old values are restored.
@deffn primitive with-fluids* fluids values thunk
@deffn {Scheme Procedure} with-fluids* fluids values thunk
@deffnx {C Function} scm_with_fluids (fluids, values, thunk)
Set @var{fluids} to @var{values} temporary, and call @var{thunk}.
@var{fluids} must be a list of fluids and @var{values} must be the same
number of their values to be applied. Each substitution is done

14
doc/ref/scheme-translation.texi
View file

@ -12,28 +12,32 @@
@node Emacs Lisp Support
@section Emacs Lisp Support
@deffn primitive nil-car x
@deffn {Scheme Procedure} nil-car x
@deffnx {C Function} scm_nil_car (x)
Return the car of @var{x}, but convert it to LISP nil if it
is Scheme's end-of-list.
@end deffn
@deffn primitive nil-cdr x
@deffn {Scheme Procedure} nil-cdr x
@deffnx {C Function} scm_nil_cdr (x)
Return the cdr of @var{x}, but convert it to LISP nil if it
is Scheme's end-of-list.
@end deffn
@deffn primitive nil-cons x y
@deffn {Scheme Procedure} nil-cons x y
@deffnx {C Function} scm_nil_cons (x, y)
Create a new cons cell with @var{x} as the car and @var{y} as
the cdr, but convert @var{y} to Scheme's end-of-list if it is
a LISP nil.
@end deffn
@deffn primitive nil-eq x y
@deffn {Scheme Procedure} nil-eq x y
Compare @var{x} and @var{y} and return LISP's t if they are
@code{eq?}, return LISP's nil otherwise.
@end deffn
@deffn primitive null x
@deffn {Scheme Procedure} null x
@deffnx {C Function} scm_null (x)
Return LISP's @code{t} if @var{x} is nil in the LISP sense,
return LISP's nil otherwise.
@end deffn

78
doc/ref/scheme-utility.texi
View file

@ -47,7 +47,7 @@ procedures for testing for equality are provided, which correspond to
the three kinds of @dfn{sameness} defined above.
@rnindex eq?
@deffn primitive eq? x y
@deffn {Scheme Procedure} eq? x y
Return @code{#t} iff @var{x} references the same object as @var{y}.
@code{eq?} is similar to @code{eqv?} except that in some cases it is
capable of discerning distinctions finer than those detectable by
@ -55,7 +55,7 @@ capable of discerning distinctions finer than those detectable by
@end deffn
@rnindex eqv?
@deffn primitive eqv? x y
@deffn {Scheme Procedure} eqv? x y
The @code{eqv?} procedure defines a useful equivalence relation on objects.
Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
regarded as the same object. This relation is left slightly open to
@ -64,7 +64,7 @@ and inexact numbers.
@end deffn
@rnindex equal?
@deffn primitive equal? x y
@deffn {Scheme Procedure} equal? x y
Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
@code{equal?} recursively compares the contents of pairs,
vectors, and strings, applying @code{eqv?} on other objects such as
@ -89,23 +89,23 @@ closures than for other kinds of objects. Therefore, when manipulating
a property list associated with a procedure object, use the
@code{procedure} functions; otherwise, use the @code{object} functions.
@deffn primitive object-properties obj
@deffnx primitive procedure-properties obj
@deffn {Scheme Procedure} object-properties obj
@deffnx {C Function} scm_object_properties (obj)
Return @var{obj}'s property list.
@end deffn
@deffn primitive set-object-properties! obj alist
@deffnx primitive set-procedure-properties! obj alist
@deffn {Scheme Procedure} set-object-properties! obj alist
@deffnx {C Function} scm_set_object_properties_x (obj, alist)
Set @var{obj}'s property list to @var{alist}.
@end deffn
@deffn primitive object-property obj key
@deffnx primitive procedure-property obj key
@deffn {Scheme Procedure} object-property obj key
@deffnx {C Function} scm_object_property (obj, key)
Return the property of @var{obj} with name @var{key}.
@end deffn
@deffn primitive set-object-property! obj key value
@deffnx primitive set-procedure-property! obj key value
@deffn {Scheme Procedure} set-object-property! obj key value
@deffnx {C Function} scm_set_object_property_x (obj, key, value)
In @var{obj}'s property list, set the property named @var{key}
to @var{value}.
@end deffn
@ -117,14 +117,16 @@ the user provides a "property table" that is possibly private.]
@node Primitive Properties
@section Primitive Properties
@deffn primitive primitive-make-property not_found_proc
@deffn {Scheme Procedure} primitive-make-property not_found_proc
@deffnx {C Function} scm_primitive_make_property (not_found_proc)
Create a @dfn{property token} that can be used with
@code{primitive-property-ref} and @code{primitive-property-set!}.
See @code{primitive-property-ref} for the significance of
@var{not_found_proc}.
@end deffn
@deffn primitive primitive-property-ref prop obj
@deffn {Scheme Procedure} primitive-property-ref prop obj
@deffnx {C Function} scm_primitive_property_ref (prop, obj)
Return the property @var{prop} of @var{obj}. When no value
has yet been associated with @var{prop} and @var{obj}, call
@var{not-found-proc} instead (see @code{primitive-make-property})
@ -134,11 +136,13 @@ and use its return value. That value is also associated with
default value of @var{prop}.
@end deffn
@deffn primitive primitive-property-set! prop obj val
@deffn {Scheme Procedure} primitive-property-set! prop obj val
@deffnx {C Function} scm_primitive_property_set_x (prop, obj, val)
Associate @var{code} with @var{prop} and @var{obj}.
@end deffn
@deffn primitive primitive-property-del! prop obj
@deffn {Scheme Procedure} primitive-property-del! prop obj
@deffnx {C Function} scm_primitive_property_del_x (prop, obj)
Remove any value associated with @var{prop} and @var{obj}.
@end deffn
@ -161,15 +165,19 @@ The first group of procedures can be used to merge two lists (which must
be already sorted on their own) and produce sorted lists containing
all elements of the input lists.
@deffn primitive merge alist blist less
Take two lists @var{alist} and @var{blist} such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
returns a new list in which the elements of @var{alist} and
@deffn {Scheme Procedure} merge alist blist less
@deffnx {C Function} scm_merge (alist, blist, less)
Merge two already sorted lists into one.
Given two lists @var{alist} and @var{blist}, such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)},
return a new list in which the elements of @var{alist} and
@var{blist} have been stably interleaved so that
@code{(sorted? (merge alist blist less?) less?)}.
Note: this does _not_ accept vectors.
@end deffn
@deffn primitive merge! alist blist less
@deffn {Scheme Procedure} merge! alist blist less
@deffnx {C Function} scm_merge_x (alist, blist, less)
Takes two lists @var{alist} and @var{blist} such that
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
returns a new list in which the elements of @var{alist} and
@ -189,19 +197,22 @@ If two or more elements are the same according to the comparison
predicate, they are left in the same order as they appeared in the
input.
@deffn primitive sorted? items less
@deffn {Scheme Procedure} sorted? items less
@deffnx {C Function} scm_sorted_p (items, less)
Return @code{#t} iff @var{items} is a list or a vector such that
for all 1 <= i <= m, the predicate @var{less} returns true when
applied to all elements i - 1 and i
@end deffn
@deffn primitive sort items less
@deffn {Scheme Procedure} sort items less
@deffnx {C Function} scm_sort (items, less)
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence
elements. This is not a stable sort.
@end deffn
@deffn primitive sort! items less
@deffn {Scheme Procedure} sort! items less
@deffnx {C Function} scm_sort_x (items, less)
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence
elements. The sorting is destructive, that means that the
@ -209,13 +220,15 @@ input sequence is modified to produce the sorted result.
This is not a stable sort.
@end deffn
@deffn primitive stable-sort items less
@deffn {Scheme Procedure} stable-sort items less
@deffnx {C Function} scm_stable_sort (items, less)
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
This is a stable sort.
@end deffn
@deffn primitive stable-sort! items less
@deffn {Scheme Procedure} stable-sort! items less
@deffnx {C Function} scm_stable_sort_x (items, less)
Sort the sequence @var{items}, which may be a list or a
vector. @var{less} is used for comparing the sequence elements.
The sorting is destructive, that means that the input sequence
@ -226,19 +239,22 @@ This is a stable sort.
The procedures in the last group only accept lists or vectors as input,
as their names indicate.
@deffn primitive sort-list items less
@deffn {Scheme Procedure} sort-list items less
@deffnx {C Function} scm_sort_list (items, less)
Sort the list @var{items}, using @var{less} for comparing the
list elements. This is a stable sort.
@end deffn
@deffn primitive sort-list! items less
@deffn {Scheme Procedure} sort-list! items less
@deffnx {C Function} scm_sort_list_x (items, less)
Sort the list @var{items}, using @var{less} for comparing the
list elements. The sorting is destructive, that means that the
input list is modified to produce the sorted result.
This is a stable sort.
@end deffn
@deffn primitive restricted-vector-sort! vec less startpos endpos
@deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos
@deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos)
Sort the vector @var{vec}, using @var{less} for comparing
the vector elements. @var{startpos} and @var{endpos} delimit
the range of the vector which gets sorted. The return value
@ -257,7 +273,8 @@ procedures for copying vectors. @code{copy-tree} can be used for these
application, as it does not only copy the spine of a list, but also
copies any pairs in the cars of the input lists.
@deffn primitive copy-tree obj
@deffn {Scheme Procedure} copy-tree obj
@deffnx {C Function} scm_copy_tree (obj)
Recursively copy the data tree that is bound to @var{obj}, and return a
pointer to the new data structure. @code{copy-tree} recurses down the
contents of both pairs and vectors (since both cons cells and vector
@ -283,7 +300,8 @@ Converting an object back from the string is only possible if the object
type has a read syntax and the read syntax is preserved by the printing
procedure.
@deffn primitive object->string obj [printer]
@deffn {Scheme Procedure} object->string obj [printer]
@deffnx {C Function} scm_object_to_string (obj, printer)
Return a Scheme string obtained by printing @var{obj}.
Printing function can be specified by the optional second
argument @var{printer} (default: @code{write}).

4
doc/ref/script-getopt.texi
View file

@ -343,7 +343,7 @@ as ordinary argument strings.
@node getopt-long Reference
@subsection Reference Documentation for @code{getopt-long}
@deffn procedure getopt-long args grammar
@deffn {Scheme Procedure} getopt-long args grammar
Parse the command line given in @var{args} (which must be a list of
strings) according to the option specification @var{grammar}.
@ -416,7 +416,7 @@ An option predicate fails.
@node option-ref Reference
@subsection Reference Documentation for @code{option-ref}
@deffn procedure option-ref options key default
@deffn {Scheme Procedure} option-ref options key default
Search @var{options} for a command line option named @var{key} and
return its value, if found. If the option has no value, but was given,
return @code{#t}. If the option was not given, return @var{default}.

460
doc/ref/srfi-modules.texi
View file

File diff suppressed because it is too large Load diff

25
libguile/ChangeLog
View file

@ -1,5 +1,30 @@
2001-11-16 Neil Jerram <neil@ossau.uklinux.net>
* gc.h (scm_unhash_name): Old declaration removed.
* eval.c (s_scm_eval): Change @var{primitive-eval} to
@code{primitive-eval}.
* feature.c, vectors.c, net_db.c, unif.c, weaks.c, struct.c,
version.c, alist.c, ports.c, ramap.c, unif.c, strings.c, list.c:
Change @deffnx lines in docstrings to say {Scheme Procedure}
rather than primitive or procedure.
* posix.c (scm_execl), filesys.c (scm_close), unif.c
(scm_array_set_x, scm_array_contents, scm_uniform_array_read_x,
scm_bit_set_star_x, scm_bit_invert_x), ramap.c (scm_array_fill_x,
scm_array_for_each, scm_array_index_map_x), vectors.c (scm_vector,
scm_make_vector, scm_vector_to_list, scm_vector_fill_x), strop.c
(scm_string_split, scm_string_ci_to_symbol), strings.c
(scm_string_p), sort.c (scm_merge), print.c (scm_newline),
macros.c (scm_macro_type), alist.c (scm_acons, scm_assq):
Docstring fixes and improvements reflecting edits that have been
made in the reference manual source.
* objprop.c (scm_object_properties, scm_set_object_properties_x,
scm_object_property, scm_set_object_property_x): Remove invalid
@deffnx lines for corresponding procedure property primitives.
These changes add a @deffnx C function declaration and function
index entries for each Guile primitive to the copy of the doc
snarf output that is used for reference manual synchronization.

22
libguile/alist.c
View file

@ -52,7 +52,7 @@
SCM_DEFINE (scm_acons, "acons", 3, 0, 0,
(SCM key, SCM value, SCM alist),
"Adds a new key-value pair to @var{alist}. A new pair is\n"
"Add a new key-value pair to @var{alist}. A new pair is\n"
"created whose car is @var{key} and whose cdr is @var{value}, and the\n"
"pair is consed onto @var{alist}, and the new list is returned. This\n"
"function is @emph{not} destructive; @var{alist} is not modified.")
@ -133,14 +133,14 @@ SCM_DEFINE (scm_sloppy_assoc, "sloppy-assoc", 2, 0, 0,
SCM_DEFINE (scm_assq, "assq", 2, 0, 0,
(SCM key, SCM alist),
"@deffnx primitive assv key alist\n"
"@deffnx primitive assoc key alist\n"
"Fetches the entry in @var{alist} that is associated with @var{key}. To\n"
"@deffnx {Scheme Procedure} assv key alist\n"
"@deffnx {Scheme Procedure} assoc key alist\n"
"Fetch the entry in @var{alist} that is associated with @var{key}. To\n"
"decide whether the argument @var{key} matches a particular entry in\n"
"@var{alist}, @code{assq} compares keys with @code{eq?}, @code{assv}\n"
"uses @code{eqv?} and @code{assoc} uses @code{equal?}. If @var{key}\n"
"cannot be found in @var{alist} (according to whichever equality\n"
"predicate is in use), then @code{#f} is returned. These functions\n"
"predicate is in use), then return @code{#f}. These functions\n"
"return the entire alist entry found (i.e. both the key and the value).")
#define FUNC_NAME s_scm_assq
{
@ -218,8 +218,8 @@ SCM_DEFINE (scm_assoc, "assoc", 2, 0, 0,
*/
SCM_DEFINE (scm_assq_ref, "assq-ref", 2, 0, 0,
(SCM alist, SCM key),
"@deffnx primitive assv-ref alist key\n"
"@deffnx primitive assoc-ref alist key\n"
"@deffnx {Scheme Procedure} assv-ref alist key\n"
"@deffnx {Scheme Procedure} assoc-ref alist key\n"
"Like @code{assq}, @code{assv} and @code{assoc}, except that only the\n"
"value associated with @var{key} in @var{alist} is returned. These\n"
"functions are equivalent to\n\n"
@ -282,8 +282,8 @@ SCM_DEFINE (scm_assoc_ref, "assoc-ref", 2, 0, 0,
SCM_DEFINE (scm_assq_set_x, "assq-set!", 3, 0, 0,
(SCM alist, SCM key, SCM val),
"@deffnx primitive assv-set! alist key value\n"
"@deffnx primitive assoc-set! alist key value\n"
"@deffnx {Scheme Procedure} assv-set! alist key value\n"
"@deffnx {Scheme Procedure} assoc-set! alist key value\n"
"Reassociate @var{key} in @var{alist} with @var{value}: find any existing\n"
"@var{alist} entry for @var{key} and associate it with the new\n"
"@var{value}. If @var{alist} does not contain an entry for @var{key},\n"
@ -347,8 +347,8 @@ SCM_DEFINE (scm_assoc_set_x, "assoc-set!", 3, 0, 0,
SCM_DEFINE (scm_assq_remove_x, "assq-remove!", 2, 0, 0,
(SCM alist, SCM key),
"@deffnx primitive assv-remove! alist key\n"
"@deffnx primitive assoc-remove! alist key\n"
"@deffnx {Scheme Procedure} assv-remove! alist key\n"
"@deffnx {Scheme Procedure} assoc-remove! alist key\n"
"Delete the first entry in @var{alist} associated with @var{key}, and return\n"
"the resulting alist.")
#define FUNC_NAME s_scm_assq_remove_x

2
libguile/eval.c
View file

@ -4069,7 +4069,7 @@ SCM_DEFINE (scm_eval, "eval", 2, 0, 0,
(SCM exp, SCM module),
"Evaluate @var{exp}, a list representing a Scheme expression,\n"
"in the top-level environment specified by @var{module}.\n"
"While @var{exp} is evaluated (using @var{primitive-eval}),\n"
"While @var{exp} is evaluated (using @code{primitive-eval}),\n"
"@var{module} is made the current module. The current module\n"
"is reset to its previous value when @var{eval} returns.")
#define FUNC_NAME s_scm_eval

2
libguile/feature.c
View file

@ -70,7 +70,7 @@ scm_add_feature (const char *str)
SCM_DEFINE (scm_program_arguments, "program-arguments", 0, 0, 0,
(),
"@deffnx procedure command-line\n"
"@deffnx {Scheme Procedure} command-line\n"
"Return the list of command line arguments passed to Guile, as a list of\n"
"strings. The list includes the invoked program name, which is usually\n"
"@code{\"guile\"}, but excludes switches and parameters for command line\n"

2
libguile/filesys.c
View file

@ -382,7 +382,7 @@ SCM_DEFINE (scm_open, "open", 2, 1, 0,
SCM_DEFINE (scm_close, "close", 1, 0, 0,
(SCM fd_or_port),
"Similar to close-port (@pxref{Generic Port Operations, close-port}),\n"
"Similar to close-port (@pxref{Closing, close-port}),\n"
"but also works on file descriptors. A side\n"
"effect of closing a file descriptor is that any ports using that file\n"
"descriptor are moved to a different file descriptor and have\n"

1
libguile/gc.h
View file

@ -351,7 +351,6 @@ SCM_API void scm_assert_cell_valid (SCM);
SCM_API SCM scm_set_debug_cell_accesses_x (SCM flag);
#endif
SCM_API SCM scm_object_address (SCM obj);
SCM_API SCM scm_unhash_name (SCM name);
SCM_API SCM scm_gc_stats (void);
SCM_API SCM scm_gc (void);
SCM_API void scm_gc_for_alloc (struct scm_t_freelist *freelist);

6
libguile/list.c
View file

@ -445,7 +445,7 @@ SCM_REGISTER_PROC(s_list_cdr_ref, "list-cdr-ref", 2, 0, 0, scm_list_tail);
SCM_DEFINE (scm_list_tail, "list-tail", 2, 0, 0,
(SCM lst, SCM k),
"@deffnx primitive list-cdr-ref lst k\n"
"@deffnx {Scheme Procedure} list-cdr-ref lst k\n"
"Return the \"tail\" of @var{lst} beginning with its @var{k}th element.\n"
"The first element of the list is considered to be element 0.\n\n"
"@code{list-tail} and @code{list-cdr-ref} are identical. It may help to\n"
@ -628,8 +628,8 @@ SCM_DEFINE (scm_member, "member", 2, 0, 0,
SCM_DEFINE (scm_delq_x, "delq!", 2, 0, 0,
(SCM item, SCM lst),
"@deffnx primitive delv! item lst\n"
"@deffnx primitive delete! item lst\n"
"@deffnx {Scheme Procedure} delv! item lst\n"
"@deffnx {Scheme Procedure} delete! item lst\n"
"These procedures are destructive versions of @code{delq}, @code{delv}\n"
"and @code{delete}: they modify the pointers in the existing @var{lst}\n"
"rather than creating a new list. Caveat evaluator: Like other\n"

2
libguile/macros.c
View file

@ -175,7 +175,7 @@ SCM_DEFINE (scm_macro_type, "macro-type", 1, 0, 0,
(SCM m),
"Return one of the symbols @code{syntax}, @code{macro} or\n"
"@code{macro!}, depending on whether @var{m} is a syntax\n"
"tranformer, a regular macro, or a memoizing macro,\n"
"transformer, a regular macro, or a memoizing macro,\n"
"respectively. If @var{m} is not a macro, @code{#f} is\n"
"returned.")
#define FUNC_NAME s_scm_macro_type

16
libguile/net_db.c
View file

@ -136,8 +136,8 @@ static void scm_resolv_error (const char *subr, SCM bad_value)
SCM_DEFINE (scm_gethost, "gethost", 0, 1, 0,
(SCM host),
"@deffnx procedure gethostbyname hostname\n"
"@deffnx procedure gethostbyaddr address\n"
"@deffnx {Scheme Procedure} gethostbyname hostname\n"
"@deffnx {Scheme Procedure} gethostbyaddr address\n"
"Look up a host by name or address, returning a host object. The\n"
"@code{gethost} procedure will accept either a string name or an integer\n"
"address; if given no arguments, it behaves like @code{gethostent} (see\n"
@ -219,8 +219,8 @@ SCM_DEFINE (scm_gethost, "gethost", 0, 1, 0,
#if defined(HAVE_GETNETENT) && defined(HAVE_GETNETBYNAME) && defined(HAVE_GETNETBYADDR)
SCM_DEFINE (scm_getnet, "getnet", 0, 1, 0,
(SCM net),
"@deffnx procedure getnetbyname net-name\n"
"@deffnx procedure getnetbyaddr net-number\n"
"@deffnx {Scheme Procedure} getnetbyname net-name\n"
"@deffnx {Scheme Procedure} getnetbyaddr net-number\n"
"Look up a network by name or net number in the network database. The\n"
"@var{net-name} argument must be a string, and the @var{net-number}\n"
"argument must be an integer. @code{getnet} will accept either type of\n"
@ -269,8 +269,8 @@ SCM_DEFINE (scm_getnet, "getnet", 0, 1, 0,
#ifdef HAVE_GETPROTOENT
SCM_DEFINE (scm_getproto, "getproto", 0, 1, 0,
(SCM protocol),
"@deffnx procedure getprotobyname name\n"
"@deffnx procedure getprotobynumber number\n"
"@deffnx {Scheme Procedure} getprotobyname name\n"
"@deffnx {Scheme Procedure} getprotobynumber number\n"
"Look up a network protocol by name or by number. @code{getprotobyname}\n"
"takes a string argument, and @code{getprotobynumber} takes an integer\n"
"argument. @code{getproto} will accept either type, behaving like\n"
@ -332,8 +332,8 @@ scm_return_entry (struct servent *entry)
SCM_DEFINE (scm_getserv, "getserv", 0, 2, 0,
(SCM name, SCM protocol),
"@deffnx procedure getservbyname name protocol\n"
"@deffnx procedure getservbyport port protocol\n"
"@deffnx {Scheme Procedure} getservbyname name protocol\n"
"@deffnx {Scheme Procedure} getservbyport port protocol\n"
"Look up a network service by name or by service number, and return a\n"
"network service object. The @var{protocol} argument specifies the name\n"
"of the desired protocol; if the protocol found in the network service\n"

4
libguile/objprop.c
View file

@ -56,7 +56,6 @@
SCM_DEFINE (scm_object_properties, "object-properties", 1, 0, 0,
(SCM obj),
"@deffnx primitive procedure-properties obj\n"
"Return @var{obj}'s property list.")
#define FUNC_NAME s_scm_object_properties
{
@ -67,7 +66,6 @@ SCM_DEFINE (scm_object_properties, "object-properties", 1, 0, 0,
SCM_DEFINE (scm_set_object_properties_x, "set-object-properties!", 2, 0, 0,
(SCM obj, SCM alist),
"@deffnx primitive set-procedure-properties! obj alist\n"
"Set @var{obj}'s property list to @var{alist}.")
#define FUNC_NAME s_scm_set_object_properties_x
{
@ -79,7 +77,6 @@ SCM_DEFINE (scm_set_object_properties_x, "set-object-properties!", 2, 0, 0,
SCM_DEFINE (scm_object_property, "object-property", 2, 0, 0,
(SCM obj, SCM key),
"@deffnx primitive procedure-property obj key\n"
"Return the property of @var{obj} with name @var{key}.")
#define FUNC_NAME s_scm_object_property
{
@ -91,7 +88,6 @@ SCM_DEFINE (scm_object_property, "object-property", 2, 0, 0,
SCM_DEFINE (scm_set_object_property_x, "set-object-property!", 3, 0, 0,
(SCM obj, SCM key, SCM value),
"@deffnx primitive set-procedure-property! obj key value\n"
"In @var{obj}'s property list, set the property named @var{key}\n"
"to @var{value}.")
#define FUNC_NAME s_scm_set_object_property_x

8
libguile/ports.c
View file

@ -395,8 +395,8 @@ SCM_DEFINE (scm_current_load_port, "current-load-port", 0, 0, 0,
SCM_DEFINE (scm_set_current_input_port, "set-current-input-port", 1, 0, 0,
(SCM port),
"@deffnx primitive set-current-output-port port\n"
"@deffnx primitive set-current-error-port port\n"
"@deffnx {Scheme Procedure} set-current-output-port port\n"
"@deffnx {Scheme Procedure} set-current-error-port port\n"
"Change the ports returned by @code{current-input-port},\n"
"@code{current-output-port} and @code{current-error-port}, respectively,\n"
"so that they use the supplied @var{port} for input or output.")
@ -1400,7 +1400,7 @@ SCM_DEFINE (scm_set_port_line_x, "set-port-line!", 2, 0, 0,
SCM_DEFINE (scm_port_column, "port-column", 1, 0, 0,
(SCM port),
"@deffnx primitive port-line port\n"
"@deffnx {Scheme Procedure} port-line port\n"
"Return the current column number or line number of @var{port},\n"
"using the current input port if none is specified. If the number is\n"
"unknown, the result is #f. Otherwise, the result is a 0-origin integer\n"
@ -1419,7 +1419,7 @@ SCM_DEFINE (scm_port_column, "port-column", 1, 0, 0,
SCM_DEFINE (scm_set_port_column_x, "set-port-column!", 2, 0, 0,
(SCM port, SCM column),
"@deffnx primitive set-port-line! port line\n"
"@deffnx {Scheme Procedure} set-port-line! port line\n"
"Set the current column or line number of @var{port}, using the\n"
"current input port if none is specified.")
#define FUNC_NAME s_scm_set_port_column_x

2
libguile/posix.c
View file

@ -867,7 +867,7 @@ SCM_DEFINE (scm_execl, "execl", 1, 0, 1,
"The remaining arguments are supplied to the process; from a C program\n"
"they are accessable as the @code{argv} argument to @code{main}.\n"
"Conventionally the first @var{arg} is the same as @var{path}.\n"
"All arguments must be strings. \n\n"
"All arguments must be strings.\n\n"
"If @var{arg} is missing, @var{path} is executed with a null\n"
"argument list, which may have system-dependent side-effects.\n\n"
"This procedure is currently implemented using the @code{execv} system\n"

3
libguile/print.c
View file

@ -992,7 +992,8 @@ SCM_DEFINE (scm_simple_format, "simple-format", 2, 0, 1,
SCM_DEFINE (scm_newline, "newline", 0, 1, 0,
(SCM port),
"Send a newline to @var{port}.")
"Send a newline to @var{port}.\n"
"If @var{port} is omitted, send to the current output port.")
#define FUNC_NAME s_scm_newline
{
if (SCM_UNBNDP (port))

12
libguile/ramap.c
View file

@ -458,7 +458,7 @@ scm_ramapc (int (*cproc)(), SCM data, SCM ra0, SCM lra, const char *what)
SCM_DEFINE (scm_array_fill_x, "array-fill!", 2, 0, 0,
(SCM ra, SCM fill),
"Stores @var{fill} in every element of @var{array}. The value returned\n"
"Store @var{fill} in every element of @var{array}. The value returned\n"
"is unspecified.")
#define FUNC_NAME s_scm_array_fill_x
{
@ -829,8 +829,8 @@ SCM_REGISTER_PROC(s_array_copy_in_order_x, "array-copy-in-order!", 2, 0, 0, scm_
SCM_DEFINE (scm_array_copy_x, "array-copy!", 2, 0, 0,
(SCM src, SCM dst),
"@deffnx primitive array-copy-in-order! src dst\n"
"Copies every element from vector or array @var{source} to the\n"
"@deffnx {Scheme Procedure} array-copy-in-order! src dst\n"
"Copy every element from vector or array @var{source} to the\n"
"corresponding element of @var{destination}. @var{destination} must have\n"
"the same rank as @var{source}, and be at least as large in each\n"
"dimension. The order is unspecified.")
@ -1512,7 +1512,7 @@ SCM_REGISTER_PROC(s_array_map_in_order_x, "array-map-in-order!", 2, 0, 1, scm_ar
SCM_DEFINE (scm_array_map_x, "array-map!", 2, 0, 1,
(SCM ra0, SCM proc, SCM lra),
"@deffnx primitive array-map-in-order! ra0 proc . lra\n"
"@deffnx {Scheme Procedure} array-map-in-order! ra0 proc . lra\n"
"@var{array1}, @dots{} must have the same number of dimensions as\n"
"@var{array0} and have a range for each index which includes the range\n"
"for the corresponding index in @var{array0}. @var{proc} is applied to\n"
@ -1664,7 +1664,7 @@ rafe (SCM ra0,SCM proc,SCM ras)
SCM_DEFINE (scm_array_for_each, "array-for-each", 2, 0, 1,
(SCM proc, SCM ra0, SCM lra),
"@var{proc} is applied to each tuple of elements of @var{array0} @dots{}\n"
"Apply @var{proc} to each tuple of elements of @var{array0} @dots{}\n"
"in row-major order. The value returned is unspecified.")
#define FUNC_NAME s_scm_array_for_each
{
@ -1677,7 +1677,7 @@ SCM_DEFINE (scm_array_for_each, "array-for-each", 2, 0, 1,
SCM_DEFINE (scm_array_index_map_x, "array-index-map!", 2, 0, 0,
(SCM ra, SCM proc),
"applies @var{proc} to the indices of each element of @var{array} in\n"
"Apply @var{proc} to the indices of each element of @var{array} in\n"
"turn, storing the result in the corresponding element. The value\n"
"returned and the order of application are unspecified.\n\n"
"One can implement @var{array-indexes} as\n"

7
libguile/sort.c
View file

@ -516,9 +516,10 @@ SCM_DEFINE (scm_sorted_p, "sorted?", 2, 0, 0,
Note: this does _not_ accept vectors. */
SCM_DEFINE (scm_merge, "merge", 3, 0, 0,
(SCM alist, SCM blist, SCM less),
"Takes two lists @var{alist} and @var{blist} such that\n"
"@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and\n"
"returns a new list in which the elements of @var{alist} and\n"
"Merge two already sorted lists into one.\n"
"Given two lists @var{alist} and @var{blist}, such that\n"
"@code{(sorted? alist less?)} and @code{(sorted? blist less?)},\n"
"return a new list in which the elements of @var{alist} and\n"
"@var{blist} have been stably interleaved so that\n"
"@code{(sorted? (merge alist blist less?) less?)}.\n"
"Note: this does _not_ accept vectors.")

5
libguile/strings.c
View file

@ -58,8 +58,7 @@
SCM_DEFINE (scm_string_p, "string?", 1, 0, 0,
(SCM obj),
"Return @code{#t} iff @var{obj} is a string, else returns\n"
"@code{#f}.")
"Return @code{#t} iff @var{obj} is a string, else @code{#f}.")
#define FUNC_NAME s_scm_string_p
{
return SCM_BOOL (SCM_STRINGP (obj));
@ -71,7 +70,7 @@ SCM_REGISTER_PROC (s_scm_list_to_string, "list->string", 1, 0, 0, scm_string);
SCM_DEFINE (scm_string, "string", 0, 0, 1,
(SCM chrs),
"@deffnx primitive list->string chrs\n"
"@deffnx {Scheme Procedure} list->string chrs\n"
"Return a newly allocated string composed of the arguments,\n"
"@var{chrs}.")
#define FUNC_NAME s_scm_string

8
libguile/strop.c
View file

@ -472,15 +472,15 @@ SCM_DEFINE (scm_string_split, "string-split", 2, 0, 0,
"result list.\n"
"\n"
"@lisp\n"
"(string-split \"root:x:0:0:root:/root:/bin/bash\" #\:)\n"
"(string-split \"root:x:0:0:root:/root:/bin/bash\" #\\:)\n"
"@result{}\n"
"(\"root\" \"x\" \"0\" \"0\" \"root\" \"/root\" \"/bin/bash\")\n"
"\n"
"(string-split \"::\" #\:)\n"
"(string-split \"::\" #\\:)\n"
"@result{}\n"
"(\"\" \"\" \"\")\n"
"\n"
"(string-split \"\" #\:)\n"
"(string-split \"\" #\\:)\n"
"@result{}\n"
"(\"\")\n"
"@end lisp")
@ -518,7 +518,7 @@ SCM_DEFINE (scm_string_ci_to_symbol, "string-ci->symbol", 1, 0, 0,
(SCM str),
"Return the symbol whose name is @var{str}. @var{str} is\n"
"converted to lowercase before the conversion is done, if Guile\n"
"is currently reading symbols case--insensitively.")
"is currently reading symbols case-insensitively.")
#define FUNC_NAME s_scm_string_ci_to_symbol
{
return scm_string_to_symbol (SCM_CASE_INSENSITIVE_P

2
libguile/struct.c
View file

@ -560,7 +560,7 @@ SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
SCM_DEFINE (scm_struct_ref, "struct-ref", 2, 0, 0,
(SCM handle, SCM pos),
"@deffnx primitive struct-set! struct n value\n"
"@deffnx {Scheme Procedure} struct-set! struct n value\n"
"Access (or modify) the @var{n}th field of @var{struct}.\n\n"
"If the field is of type 'p', then it can be set to an arbitrary value.\n\n"
"If the field is of type 'u', then it can only be set to a non-negative\n"

25
libguile/unif.c
View file

@ -582,7 +582,7 @@ scm_shap2ra (SCM args, const char *what)
SCM_DEFINE (scm_dimensions_to_uniform_array, "dimensions->uniform-array", 2, 1, 0,
(SCM dims, SCM prot, SCM fill),
"@deffnx primitive make-uniform-vector length prototype [fill]\n"
"@deffnx {Scheme Procedure} make-uniform-vector length prototype [fill]\n"
"Create and return a uniform array or vector of type\n"
"corresponding to @var{prototype} with dimensions @var{dims} or\n"
"length @var{length}. If @var{fill} is supplied, it's used to\n"
@ -1084,7 +1084,7 @@ SCM_REGISTER_PROC(s_array_ref, "array-ref", 1, 0, 1, scm_uniform_vector_ref);
SCM_DEFINE (scm_uniform_vector_ref, "uniform-vector-ref", 2, 0, 0,
(SCM v, SCM args),
"@deffnx primitive array-ref v . args\n"
"@deffnx {Scheme Procedure} array-ref v . args\n"
"Return the element at the @code{(index1, index2)} element in\n"
"@var{array}.")
#define FUNC_NAME s_scm_uniform_vector_ref
@ -1262,8 +1262,8 @@ SCM_REGISTER_PROC(s_uniform_array_set1_x, "uniform-array-set1!", 3, 0, 0, scm_ar
PROC is used (and it's called from C too). */
SCM_DEFINE (scm_array_set_x, "array-set!", 2, 0, 1,
(SCM v, SCM obj, SCM args),
"@deffnx primitive uniform-array-set1! v obj args\n"
"Sets the element at the @code{(index1, index2)} element in @var{array} to\n"
"@deffnx {Scheme Procedure} uniform-array-set1! v obj args\n"
"Set the element at the @code{(index1, index2)} element in @var{array} to\n"
"@var{new-value}. The value returned by array-set! is unspecified.")
#define FUNC_NAME s_scm_array_set_x
{
@ -1371,7 +1371,6 @@ SCM_DEFINE (scm_array_set_x, "array-set!", 2, 0, 1,
wouldn't have contiguous elements. */
SCM_DEFINE (scm_array_contents, "array-contents", 1, 1, 0,
(SCM ra, SCM strict),
"@deffnx primitive array-contents array strict\n"
"If @var{array} may be @dfn{unrolled} into a one dimensional shared array\n"
"without changing their order (last subscript changing fastest), then\n"
"@code{array-contents} returns that shared array, otherwise it returns\n"
@ -1482,11 +1481,11 @@ scm_ra2contig (SCM ra, int copy)
SCM_DEFINE (scm_uniform_array_read_x, "uniform-array-read!", 1, 3, 0,
(SCM ra, SCM port_or_fd, SCM start, SCM end),
"@deffnx primitive uniform-vector-read! uve [port-or-fdes] [start] [end]\n"
"Attempts to read all elements of @var{ura}, in lexicographic order, as\n"
"@deffnx {Scheme Procedure} uniform-vector-read! uve [port-or-fdes] [start] [end]\n"
"Attempt to read all elements of @var{ura}, in lexicographic order, as\n"
"binary objects from @var{port-or-fdes}.\n"
"If an end of file is encountered during\n"
"uniform-array-read! the objects up to that point only are put into @var{ura}\n"
"If an end of file is encountered,\n"
"the objects up to that point are put into @var{ura}\n"
"(starting at the beginning) and the remainder of the array is\n"
"unchanged.\n\n"
"The optional arguments @var{start} and @var{end} allow\n"
@ -1650,7 +1649,7 @@ loop:
SCM_DEFINE (scm_uniform_array_write, "uniform-array-write", 1, 3, 0,
(SCM v, SCM port_or_fd, SCM start, SCM end),
"@deffnx primitive uniform-vector-write uve [port-or-fdes] [start] [end]\n"
"@deffnx {Scheme Procedure} uniform-vector-write uve [port-or-fdes] [start] [end]\n"
"Writes all elements of @var{ura} as binary objects to\n"
"@var{port-or-fdes}.\n\n"
"The optional arguments @var{start}\n"
@ -1890,7 +1889,7 @@ SCM_DEFINE (scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
"length. If @var{bool} is @code{#t}, uve is OR'ed into\n"
"@var{bv}; If @var{bool} is @code{#f}, the inversion of uve is\n"
"AND'ed into @var{bv}.\n\n"
"If uve is a unsigned integer vector all the elements of uve\n"
"If uve is a unsigned long integer vector all the elements of uve\n"
"must be between 0 and the @code{length} of @var{bv}. The bits\n"
"of @var{bv} corresponding to the indexes in uve are set to\n"
"@var{bool}. The return value is unspecified.")
@ -2011,7 +2010,7 @@ SCM_DEFINE (scm_bit_count_star, "bit-count*", 3, 0, 0,
SCM_DEFINE (scm_bit_invert_x, "bit-invert!", 1, 0, 0,
(SCM v),
"Modifies @var{bv} by replacing each element with its negation.")
"Modify @var{bv} by replacing each element with its negation.")
#define FUNC_NAME s_scm_bit_invert_x
{
long int k;
@ -2187,7 +2186,7 @@ static int l2ra(SCM lst, SCM ra, unsigned long base, unsigned long k);
SCM_DEFINE (scm_list_to_uniform_array, "list->uniform-array", 3, 0, 0,
(SCM ndim, SCM prot, SCM lst),
"@deffnx procedure list->uniform-vector prot lst\n"
"@deffnx {Scheme Procedure} list->uniform-vector prot lst\n"
"Return a uniform array of the type indicated by prototype\n"
"@var{prot} with elements the same as those of @var{lst}.\n"
"Elements must be of the appropriate type, no coercions are\n"

13
libguile/vectors.c
View file

@ -83,8 +83,8 @@ SCM_REGISTER_PROC (s_list_to_vector, "list->vector", 1, 0, 0, scm_vector);
*/
SCM_DEFINE (scm_vector, "vector", 0, 0, 1,
(SCM l),
"@deffnx primitive list->vector l\n"
"Return a newly allocated vector whose elements contain the\n"
"@deffnx {Scheme Procedure} list->vector l\n"
"Return a newly allocated vector composed of the\n"
"given arguments. Analogous to @code{list}.\n"
"\n"
"@lisp\n"
@ -173,8 +173,8 @@ scm_vector_set_x (SCM v, SCM k, SCM obj)
SCM_DEFINE (scm_make_vector, "make-vector", 1, 1, 0,
(SCM k, SCM fill),
"Return a newly allocated vector of @var{k} elements. If a\n"
"second argument is given, then each element is initialized to\n"
"@var{fill}. Otherwise the initial contents of each element is\n"
"second argument is given, then each position is initialized to\n"
"@var{fill}. Otherwise the initial contents of each position is\n"
"unspecified.")
#define FUNC_NAME s_scm_make_vector
{
@ -226,8 +226,7 @@ scm_c_make_vector (unsigned long int k, SCM fill)
SCM_DEFINE (scm_vector_to_list, "vector->list", 1, 0, 0,
(SCM v),
"Return a newly allocated list of the objects contained in the\n"
"elements of @var{vector}.\n"
"Return a newly allocated list composed of the elements of @var{v}.\n"
"\n"
"@lisp\n"
"(vector->list '#(dah dah didah)) @result{} (dah dah didah)\n"
@ -248,7 +247,7 @@ SCM_DEFINE (scm_vector_to_list, "vector->list", 1, 0, 0,
SCM_DEFINE (scm_vector_fill_x, "vector-fill!", 2, 0, 0,
(SCM v, SCM fill),
"Store @var{fill} in every element of @var{vector}. The value\n"
"Store @var{fill} in every position of @var{vector}. The value\n"
"returned by @code{vector-fill!} is unspecified.")
#define FUNC_NAME s_scm_vector_fill_x
{

6
libguile/version.c
View file

@ -94,9 +94,9 @@ SCM_DEFINE (scm_micro_version, "micro-version", 0, 0, 0,
SCM_DEFINE (scm_version, "version", 0, 0, 0,
(),
"@deffnx primitive major-version\n"
"@deffnx primitive minor-version\n"
"@deffnx primitive micro-version\n"
"@deffnx {Scheme Procedure} major-version\n"
"@deffnx {Scheme Procedure} minor-version\n"
"@deffnx {Scheme Procedure} micro-version\n"
"Return a string describing Guile's version number, or its major, minor\n"
"or micro version number, respectively.\n\n"
"@lisp\n"

10
libguile/weaks.c
View file

@ -124,7 +124,7 @@ SCM_REGISTER_PROC(s_list_to_weak_vector, "list->weak-vector", 1, 0, 0, scm_weak_
SCM_DEFINE (scm_weak_vector, "weak-vector", 0, 0, 1,
(SCM l),
"@deffnx primitive list->weak-vector l\n"
"@deffnx {Scheme Procedure} list->weak-vector l\n"
"Construct a weak vector from a list: @code{weak-vector} uses\n"
"the list of its arguments while @code{list->weak-vector} uses\n"
"its only argument @var{l} (a list) to construct a weak vector\n"
@ -167,8 +167,8 @@ SCM_DEFINE (scm_weak_vector_p, "weak-vector?", 1, 0, 0,
SCM_DEFINE (scm_make_weak_key_hash_table, "make-weak-key-hash-table", 1, 0, 0,
(SCM size),
"@deffnx primitive make-weak-value-hash-table size\n"
"@deffnx primitive make-doubly-weak-hash-table size\n"
"@deffnx {Scheme Procedure} make-weak-value-hash-table size\n"
"@deffnx {Scheme Procedure} make-doubly-weak-hash-table size\n"
"Return a weak hash table with @var{size} buckets. As with any\n"
"hash table, choosing a good size for the table requires some\n"
"caution.\n"
@ -206,8 +206,8 @@ SCM_DEFINE (scm_make_doubly_weak_hash_table, "make-doubly-weak-hash-table", 1, 0
SCM_DEFINE (scm_weak_key_hash_table_p, "weak-key-hash-table?", 1, 0, 0,
(SCM obj),
"@deffnx primitive weak-value-hash-table? obj\n"
"@deffnx primitive doubly-weak-hash-table? obj\n"
"@deffnx {Scheme Procedure} weak-value-hash-table? obj\n"
"@deffnx {Scheme Procedure} doubly-weak-hash-table? obj\n"
"Return @code{#t} if @var{obj} is the specified weak hash\n"
"table. Note that a doubly weak hash table is neither a weak key\n"
"nor a weak value hash table.")

6
scripts/ChangeLog
View file

@ -1,5 +1,11 @@
2001-11-16 Neil Jerram <neil@ossau.uklinux.net>
* snarf-check-and-output-texi: Change generated @deffn categories
from "function" and "primitive" to "C Function" and "Scheme
Procedure".
(end-multiline): Take out @findex generation again; not needed
since index entries are implicit in @deffn forms.
These changes add a @deffnx C function declaration and function
index entries for each Guile primitive to the copy of the doc
snarf output that is used for reference manual synchronization.

13
scripts/snarf-check-and-output-texi
View file

@ -143,7 +143,7 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
(set! *sig* #f)
(set! *docstring* #f))
(define *primitive-deffnx-signature* "@deffnx primitive ")
(define *primitive-deffnx-signature* "@deffnx {Scheme Procedure} ")
(define *primitive-deffnx-sig-length* (string-length *primitive-deffnx-signature*))
(define (end-multiline)
@ -184,18 +184,18 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
(if (and *manual-flag* (eq? *snarf-type* 'primitive))
(with-output-to-string
(lambda ()
(format #t "@deffnx function SCM ~A (" *c-function-name*)
(format #t "@deffnx {C Function} ~A (" *c-function-name*)
(unless (null? *args*)
(format #t "SCM ~A" (car *args*))
(format #t "~A" (car *args*))
(let loop ((args (cdr *args*)))
(unless (null? args)
(format #t ", SCM ~A" (car args))
(format #t ", ~A" (car args))
(loop (cdr args)))))
(format #t ")\n")))
#f)))
(format #t "\n ~A\n" *function-name*)
(format #t "@c snarfed from ~A:~A\n" *file* *line*)
(format #t "@deffn primitive ~A\n" nice-sig)
(format #t "@deffn {Scheme Procedure} ~A\n" nice-sig)
(let loop ((strings *docstring*) (scm-deffnx scm-deffnx))
(cond ((null? strings))
((or (not scm-deffnx)
@ -209,9 +209,6 @@ exec ${GUILE-guile} -l $0 -c "(apply $main (cdr (command-line)))" "$@"
(else (display scm-deffnx)
(loop strings #f))))
(display "\n")
(when *manual-flag*
(format #t "@findex ~A\n" *function-name*)
(format #t "@findex ~A\n" *c-function-name*))
(display "@end deffn\n"))))
(define (texi-quote s)