mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-06-16 16:50:21 +02:00
Code Activity

Correct, update, improve and clean up a lot of docstrings in order to make

Browse source 
the documentation much more consistent.
This commit is contained in:
Martin Grabmüller 2001-04-03 13:19:05 +00:00
parent ae9f3a1582
commit 1e6808ea20
41 changed files with 1133 additions and 949 deletions
Download patch file Download diff file Expand all files Collapse all files

106
libguile/ChangeLog
View file

@ -1,3 +1,109 @@
2001-04-03 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
The following changes make the documentation more consistent.
* rdelim.c (scm_write_line), posix.c (scm_utime), ports.c
(scm_seek), net_db.c (scm_inet_aton, scm_inet_ntoa),
(scm_inet_netof, scm_lnaof, scm_inet_makeaddr), ioext.c
(scm_ftell): Changed @smalllisp ... @end smalllisp to @lisp
... @end lisp.
* vports.c (scm_make_soft_port), version.c (scm_version), unif.c
(scm_array_dimensions, scm_make_shared_array),
(scm_transpose_array, scm_enclose_array, scm_bit_count_star),
throw.c (scm_catch), struct.c (scm_make_vtable_vtable), strop.c
(scm_string_rindex, scm_string_index, scm_substring_fill_x),
(scm_string_null_p), strings.c (scm_read_only_string_p), root.c
(scm_call_with_dynamic_root), ramap.c (scm_array_index_map_x),
posix.c (scm_mknod), numbers.c (scm_logtest, scm_logbit_p),
macros.c (scm_makmmacro), list.c (scm_append), environments.c
(scm_environment_fold), dynwind.c (s_scm_dynamic_wind): Changed
@example ... @end example to @lisp ... @end lisp.
* weaks.c (scm_weak_vector): Corrected docstring.
* hashtab.c (scm_hashq_ref, scm_hashq_set_x, scm_hashq_remove_x),
(scm_hashv_ref, scm_hashv_set_x, scm_hashv_remove_x),
(scm_hash_ref, scm_hash_set_x, scm_hash_remove_x, scm_hashx_ref),
(scm_hashx_set_x, scm_hashx_get_handle),
(scm_hashx_create_handle_x), regex-posix.c (scm_make_regexp),
(scm_regexp_exec, scm_regexp_p), numbers.c (scm_logtest),
vectors.c (scm_vector_fill_x), strings.c
(scm_make_shared_substring), symbols.c (scm_string_to_symbol),
objprop.c (scm_set_object_properties_x):
(scm_set_object_property_x), throw.c (scm_catch, scm_lazy_catch),
strports.c (scm_call_with_input_string), ports.c
(scm_truncate_file), ioext.c (scm_ftell), ports.c (scm_seek),
list.c (scm_append_x), dynwind.c (scm_dynamic_wind), error.c
(scm_error_scm), vports.c (scm_make_soft_port), weaks.c
(scm_make_weak_vector,scm_weak_vector_p),
(scm_make_weak_key_hash_table, scm_make_weak_value_hash_table),
(scm_make_doubly_weak_hash_table, scm_weak_key_hash_table_p),
(scm_weak_value_hash_table_p, scm_doubly_weak_hash_table_p),
macros.c (scm_macro_type), dynl.c (scm_dynamic_link),
(scm_dynamic_unlink, scm_dynamic_call, scm_dynamic_args_call):
Made parameter names match documentation by renaming parameters
and/or fixing docstrings.
* numbers.c (scm_ash): Corrected Texinfo markup.
* strop.c (scm_string_index, scm_string_rindex),
(scm_substring_fill_x, scm_string_null_p): Removed `qdocs'.
* vports.c (scm_make_soft_port), unif.c
(scm_uniform_vector_length, scm_array_p, scm_array_rank),
(scm_dimensions_to_uniform_array, scm_transpose_array),
(scm_array_in_bounds_p, scm_uniform_vector_ref),
(scm_bit_count, scm_bit_position, scm_bit_count_star),
(scm_array_to_list, scm_list_to_uniform_array),
(scm_array_prototype, symbols.c (scm_string_to_symbol), strports.c
(scm_open_input_string, scm_open_output_string),
(scm_get_output_string), strop.c (scm_string_copy),
(scm_string_fill_x), strings.c (scm_string_p, scm_string), stime.c
(scm_get_internal_real_time, scm_times),
(scm_get_internal_run_time, scm_current_time, scm_gettimeofday),
(scm_localtime, scm_gmtime), socket.c (scm_htons, scm_ntohs),
(scm_htonl, scm_ntohl, scm_socket, scm_socketpair),
(scm_getsockopt, scm_getsockname, scm_getpeername, scm_recvfrom),
simpos.c (scm_system), random.c (scm_random_uniform),
(scm_random_normal, scm_random_exp), ramap.c
(scm_array_equal_p), posix.c (scm_pipe, scm_getgroups),
(scm_status_exit_val, scm_status_term_sig, scm_status_stop_sig),
(scm_getppid, scm_getuid, scm_getgid, scm_geteuid, scm_getegid),
(scm_getpgrp, scm_ttyname, scm_ctermid, scm_tcgetpgrp, scm_uname),
(scm_environ, scm_tmpnam, scm_mkstemp, scm_access, scm_getpid),
(scm_setlocale), ports.c (scm_char_ready_p, scm_drain_input),
(scm_pt_size, scm_pt_member, scm_port_revealed, scm_port_mode),
(scm_close_port, scm_input_port_p, scm_output_port_p, scm_port_p),
(scm_port_closed_p, scm_eof_object_p, scm_read_char),
(scm_peek_char), pairs.c (scm_pair_p, scm_cons), numbers.c
(scm_logand, scm_logior, scm_logxor, scm_lognot),
(scm_integer_expt, scm_bit_extract, scm_logcount),
(scm_integer_length, scm_string_to_number, scm_inexact_to_exact),
net_db.c (scm_inet_netof, scm_lnaof), modules.c
(scm_interaction_environment), macros.c (scm_makacro),
(scm_makmacro, scm_makmmacro), keywords.c (scm_keyword_p), ioext.c
(scm_ftell, scm_dup_to_fdes, scm_fileno, scm_isatty_p),
(scm_fdopen, scm_fdes_to_ports), gc.c (scm_gc_stats), fluids.c
(scm_fluid_ref), filesys.c (scm_open_fdes),
(scm_stat, scm_directory_stream_p, scm_getcwd, scm_readlink):
Docstring correction: `Returns' -> `Return'
* gc.c (scm_set_debug_cell_accesses_x):
(s_scm_gc_set_debug_check_freelist_x):
* fluids.c (scm_fluid_p): Added texinfo markup.
* error.c (scm_strerror): Made docstring more precise.
* vectors.c (scm_vector_p, scm_vector, scm_make_vector),
(scm_vector_to_list, _scm_vector_fill_x), symbols.c
(scm_symbol_p, scm_symbol_to_string), strorder.c
(scm_string_equal_p, scm_string_ci_equal_p, scm_string_less_p),
(scm_string_leq_p, scm_string_gr_p, scm_string_geq_p),
(scm_string_ci_less_p, scm_string_ci_leq_p, scm_string_ci_gr_p):
(scm_string_ci_geq_p), strop.c (scm_string_copy),
(scm_string_fill_x): Removed `(r5rs)' from docstrings.
2001-04-01 Dirk Herrmann <D.Herrmann@tu-bs.de>
* gc.c (MARK): Re-introduce a cheap sanity test for non debug

67
libguile/dynl.c
View file

@ -350,18 +350,19 @@ dynl_obj_print (SCM exp, SCM port, scm_print_state *pstate)
SCM_DEFINE (scm_dynamic_link, "dynamic-link", 1, 0, 0,
(SCM fname),
"Open the dynamic library @var{library-file}. A library handle\n"
"representing the opened library is returned; this handle should be used\n"
"as the @var{lib} argument to the following functions.")
(SCM filename),
"Open the dynamic library called @var{filename}. A library\n"
"handle representing the opened library is returned; this handle\n"
"should be used as the @var{dobj} argument to the following\n"
"functions.")
#define FUNC_NAME s_scm_dynamic_link
{
void *handle;
SCM_VALIDATE_STRING (1, fname);
SCM_STRING_COERCE_0TERMINATION_X (fname);
handle = sysdep_dynl_link (SCM_STRING_CHARS (fname), FUNC_NAME);
SCM_RETURN_NEWSMOB2 (scm_tc16_dynamic_obj, SCM_UNPACK (fname), handle);
SCM_VALIDATE_STRING (1, filename);
SCM_STRING_COERCE_0TERMINATION_X (filename);
handle = sysdep_dynl_link (SCM_STRING_CHARS (filename), FUNC_NAME);
SCM_RETURN_NEWSMOB2 (scm_tc16_dynamic_obj, SCM_UNPACK (filename), handle);
}
#undef FUNC_NAME
@ -379,13 +380,10 @@ SCM_DEFINE (scm_dynamic_object_p, "dynamic-object?", 1, 0, 0,
SCM_DEFINE (scm_dynamic_unlink, "dynamic-unlink", 1, 0, 0,
(SCM dobj),
"Unlink the library represented by @var{library-handle},\n"
"and remove any imported symbols from the address space.\n"
"GJB:FIXME:DOC: 2nd version below:\n"
"Unlink the indicated object file from the application. The\n"
"argument @var{dynobj} must have been obtained by a call to\n"
"argument @var{dobj} must have been obtained by a call to\n"
"@code{dynamic-link}. After @code{dynamic-unlink} has been\n"
"called on @var{dynobj}, its content is no longer accessible.")
"called on @var{dobj}, its content is no longer accessible.")
#define FUNC_NAME s_scm_dynamic_unlink
{
/*fixme* GC-problem */
@ -442,19 +440,14 @@ SCM_DEFINE (scm_dynamic_func, "dynamic-func", 2, 0, 0,
SCM_DEFINE (scm_dynamic_call, "dynamic-call", 2, 0, 0,
(SCM func, SCM dobj),
"Call @var{lib-thunk}, a procedure of no arguments. If @var{lib-thunk}\n"
"is a string, it is assumed to be a symbol found in the dynamic library\n"
"@var{lib} and is fetched with @code{dynamic-func}. Otherwise, it should\n"
"be a function handle returned by a previous call to @code{dynamic-func}.\n"
"The return value is unspecified.\n"
"GJB:FIXME:DOC 2nd version below\n"
"Call the C function indicated by @var{function} and @var{dynobj}. The\n"
"function is passed no arguments and its return value is ignored. When\n"
"@var{function} is something returned by @code{dynamic-func}, call that\n"
"function and ignore @var{dynobj}. When @var{function} is a string (or\n"
"symbol, etc.), look it up in @var{dynobj}; this is equivalent to\n\n"
"Call the C function indicated by @var{func} and @var{dobj}.\n"
"The function is passed no arguments and its return value is\n"
"ignored. When @var{function} is something returned by\n"
"@code{dynamic-func}, call that function and ignore @var{dobj}.\n"
"When @var{func} is a string , look it up in @var{dynobj}; this\n"
"is equivalent to\n"
"@smallexample\n"
"(dynamic-call (dynamic-func @var{function} @var{dynobj} #f))\n"
"(dynamic-call (dynamic-func @var{func} @var{dobj} #f))\n"
"@end smallexample\n\n"
"Interrupts are deferred while the C function is executing (with\n"
"@code{SCM_DEFER_INTS}/@code{SCM_ALLOW_INTS}).")
@ -474,24 +467,18 @@ SCM_DEFINE (scm_dynamic_call, "dynamic-call", 2, 0, 0,
SCM_DEFINE (scm_dynamic_args_call, "dynamic-args-call", 3, 0, 0,
(SCM func, SCM dobj, SCM args),
"Call @var{proc}, a dynamically loaded function, passing it the argument\n"
"list @var{args} (a list of strings). As with @code{dynamic-call},\n"
"@var{proc} should be either a function handle or a string, in which case\n"
"it is first fetched from @var{lib} with @code{dynamic-func}.\n\n"
"@var{proc} is assumed to return an integer, which is used as the return\n"
"value from @code{dynamic-args-call}.\n\n"
"GJB:FIXME:DOC 2nd version below\n"
"Call the C function indicated by @var{function} and @var{dynobj}, just\n"
"like @code{dynamic-call}, but pass it some arguments and return its\n"
"return value. The C function is expected to take two arguments and\n"
"return an @code{int}, just like @code{main}:\n\n"
"Call the C function indicated by @var{func} and @var{dobj},\n"
"just like @code{dynamic-call}, but pass it some arguments and\n"
"return its return value. The C function is expected to take\n"
"two arguments and return an @code{int}, just like @code{main}:\n"
"@smallexample\n"
"int c_func (int argc, char **argv);\n"
"@end smallexample\n\n"
"The parameter @var{args} must be a list of strings and is converted into\n"
"an array of @code{char *}. The array is passed in @var{argv} and its\n"
"size in @var{argc}. The return value is converted to a Scheme number\n"
"and returned from the call to @code{dynamic-args-call}.")
"The parameter @var{args} must be a list of strings and is\n"
"converted into an array of @code{char *}. The array is passed\n"
"in @var{argv} and its size in @var{argc}. The return value is\n"
"converted to a Scheme number and returned from the call to\n"
"@code{dynamic-args-call}.")
#define FUNC_NAME s_scm_dynamic_args_call
{
int (*fptr) (int argc, char **argv);

54
libguile/dynwind.c
View file

@ -70,60 +70,66 @@
SCM_DEFINE (scm_dynamic_wind, "dynamic-wind", 3, 0, 0,
(SCM thunk1, SCM thunk2, SCM thunk3),
"All three arguments must be 0-argument procedures.\n\n"
"@var{in-guard} is called, then @var{thunk}, then @var{out-guard}.\n\n"
"If, any time during the execution of @var{thunk}, the continuation\n"
"of the @code{dynamic-wind} expression is escaped non-locally, @var{out-guard}\n"
"is called. If the continuation of the dynamic-wind is re-entered,\n"
"@var{in-guard} is called. Thus @var{in-guard} and @var{out-guard} may\n"
"be called any number of times.\n\n"
"@example\n"
(SCM in_guard, SCM thunk, SCM out_guard),
"All three arguments must be 0-argument procedures.\n"
"@var{in_guard} is called, then @var{thunk}, then\n"
"@var{out_guard}.\n"
"\n"
"If, any time during the execution of @var{thunk}, the\n"
"continuation of the @code{dynamic_wind} expression is escaped\n"
"non-locally, @var{out_guard} is called. If the continuation of\n"
"the dynamic-wind is re-entered, @var{in_guard} is called. Thus\n"
"@var{in_guard} and @var{out_guard} may be called any number of\n"
"times.\n"
"@lisp\n"
"(define x 'normal-binding)\n"
"@result{} x\n\n"
"@result{} x\n"
"(define a-cont (call-with-current-continuation \n"
" (lambda (escape)\n"
" (let ((old-x x))\n"
" (dynamic-wind\n"
" ;; in-guard:\n"
" ;;\n"
" (lambda () (set! x 'special-binding))\n\n"
" (lambda () (set! x 'special-binding))\n"
"\n"
" ;; thunk\n"
" ;;\n"
" (lambda () (display x) (newline)\n"
" (call-with-current-continuation escape)\n"
" (display x) (newline)\n"
" x)\n\n"
" x)\n"
"\n"
" ;; out-guard:\n"
" ;;\n"
" (lambda () (set! x old-x)))))))\n\n"
" (lambda () (set! x old-x)))))))\n"
"\n"
";; Prints: \n"
"special-binding\n"
";; Evaluates to:\n"
"@result{} a-cont\n\n"
"@result{} a-cont\n"
"x\n"
"@result{} normal-binding\n\n"
"@result{} normal-binding\n"
"(a-cont #f)\n"
";; Prints:\n"
"special-binding\n"
";; Evaluates to:\n"
"@result{} a-cont ;; the value of the (define a-cont...)\n\n"
"@result{} a-cont ;; the value of the (define a-cont...)\n"
"x\n"
"@result{} normal-binding\n\n"
"@result{} normal-binding\n"
"a-cont\n"
"@result{} special-binding\n"
"@end example\n")
"@end lisp")
#define FUNC_NAME s_scm_dynamic_wind
{
SCM ans;
SCM_ASSERT (SCM_NFALSEP (scm_thunk_p (thunk3)),
thunk3,
SCM_ASSERT (SCM_NFALSEP (scm_thunk_p (out_guard)),
out_guard,
SCM_ARG3, FUNC_NAME);
scm_apply (thunk1, SCM_EOL, SCM_EOL);
scm_dynwinds = scm_acons (thunk1, thunk3, scm_dynwinds);
ans = scm_apply (thunk2, SCM_EOL, SCM_EOL);
scm_apply (in_guard, SCM_EOL, SCM_EOL);
scm_dynwinds = scm_acons (in_guard, out_guard, scm_dynwinds);
ans = scm_apply (thunk, SCM_EOL, SCM_EOL);
scm_dynwinds = SCM_CDR (scm_dynwinds);
scm_apply (thunk3, SCM_EOL, SCM_EOL);
scm_apply (out_guard, SCM_EOL, SCM_EOL);
return ans;
}
#undef FUNC_NAME

8
libguile/environments.c
View file

@ -209,26 +209,26 @@ SCM_DEFINE (scm_environment_fold, "environment-fold", 3, 0, 0,
"@var{init}.\n"
"If @var{env} binds the symbol sym1 to the value val1, sym2 to\n"
"val2, and so on, then this procedure computes:\n"
"@example\n"
"@lisp\n"
" (proc sym1 val1\n"
" (proc sym2 val2\n"
" ...\n"
" (proc symn valn\n"
" init)))\n"
"@end example\n"
"@end lisp\n"
"Each binding in @var{env} will be processed exactly once.\n"
"@code{environment-fold} makes no guarantees about the order in\n"
"which the bindings are processed.\n"
"Here is a function which, given an environment, constructs an\n"
"association list representing that environment's bindings,\n"
"using environment-fold:\n"
"@example\n"
"@lisp\n"
" (define (environment->alist env)\n"
" (environment-fold env\n"
" (lambda (sym val tail)\n"
" (cons (cons sym val) tail))\n"
" '()))\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_environment_fold
{
SCM_ASSERT (SCM_ENVIRONMENT_P (env), env, SCM_ARG1, FUNC_NAME);

31
libguile/error.c
View file

@ -98,18 +98,20 @@ scm_error (SCM key, const char *subr, const char *message, SCM args, SCM rest)
/* Scheme interface to scm_error. */
SCM_DEFINE (scm_error_scm, "scm-error", 5, 0, 0,
(SCM key, SCM subr, SCM message, SCM args, SCM rest),
"Raise an error with key @var{key}. @var{subr} can be a string naming\n"
"the procedure associated with the error, or @code{#f}. @var{message}\n"
"is the error message string, possibly containing @code{~S} and @code{~A}\n"
"escapes. When an error is reported, these are replaced by formating the\n"
"corresponding members of @var{args}: @code{~A} (was @code{%s}) formats using @code{display}\n"
"and @code{~S} (was @code{%S}) formats using @code{write}. @var{data} is a\n"
"list or @code{#f} depending on @var{key}: if @var{key} is\n"
"@code{system-error} then it should be a list\n"
"containing the Unix @code{errno} value; If @var{key} is @code{signal} then\n"
"it should be a list containing the Unix signal number; otherwise it\n"
"will usually be @code{#f}.")
(SCM key, SCM subr, SCM message, SCM args, SCM data),
"Raise an error with key @var{key}. @var{subr} can be a string\n"
"naming the procedure associated with the error, or @code{#f}.\n"
"@var{message} is the error message string, possibly containing\n"
"@code{~S} and @code{~A} escapes. When an error is reported,\n"
"these are replaced by formatting the corresponding members of\n"
"@var{args}: @code{~A} (was @code{%s} in older versions of\n"
"Guile) formats using @code{display} and @code{~S} (was\n"
"@code{%S}) formats using @code{write}. @var{data} is a list or\n"
"@code{#f} depending on @var{key}: if @var{key} is\n"
"@code{system-error} then it should be a list containing the\n"
"Unix @code{errno} value; If @var{key} is @code{signal} then it\n"
"should be a list containing the Unix signal number; otherwise\n"
"it will usually be @code{#f}.")
#define FUNC_NAME s_scm_error_scm
{
char *szSubr;
@ -143,14 +145,15 @@ SCM_DEFINE (scm_error_scm, "scm-error", 5, 0, 0,
szMessage = SCM_STRING_CHARS (message);
}
scm_error (key, szSubr, szMessage, args, rest);
scm_error (key, szSubr, szMessage, args, data);
/* not reached. */
}
#undef FUNC_NAME
SCM_DEFINE (scm_strerror, "strerror", 1, 0, 0,
(SCM err),
"Returns the Unix error message corresponding to @var{err}, an integer.")
"Return the Unix error message corresponding to @var{err}, which\n"
"must be an integer value.")
#define FUNC_NAME s_scm_strerror
{
SCM_VALIDATE_INUM (1,err);

59
libguile/filesys.c
View file

@ -233,8 +233,8 @@ SCM_DEFINE (scm_umask, "umask", 0, 1, 0,
SCM_DEFINE (scm_open_fdes, "open-fdes", 2, 1, 0,
(SCM path, SCM flags, SCM mode),
"Similar to @code{open} but returns a file descriptor instead of a\n"
"port.")
"Similar to @code{open} but return a file descriptor instead of\n"
"a port.")
#define FUNC_NAME s_scm_open_fdes
{
int fd;
@ -466,23 +466,26 @@ scm_stat2scm (struct stat *stat_temp)
SCM_DEFINE (scm_stat, "stat", 1, 0, 0,
(SCM object),
"Returns an object containing various information\n"
"about the file determined by @var{obj}.\n"
"@var{obj} can be a string containing a file name or a port or integer file\n"
"descriptor which is open on a file (in which case @code{fstat} is used\n"
"as the underlying system call).\n\n"
"The object returned by @code{stat} can be passed as a single parameter\n"
"to the following procedures, all of which return integers:\n\n"
"Return an object containing various information about the file\n"
"determined by @var{obj}. @var{obj} can be a string containing\n"
"a file name or a port or integer file descriptor which is open\n"
"on a file (in which case @code{fstat} is used as the underlying\n"
"system call).\n"
"\n"
"The object returned by @code{stat} can be passed as a single\n"
"parameter to the following procedures, all of which return\n"
"integers:\n"
"\n"
"@table @code\n"
"@item stat:dev\n"
"The device containing the file.\n"
"@item stat:ino\n"
"The file serial number, which distinguishes this file from all other\n"
"files on the same device.\n"
"The file serial number, which distinguishes this file from all\n"
"other files on the same device.\n"
"@item stat:mode\n"
"The mode of the file. This includes file type information\n"
"and the file permission bits. See @code{stat:type} and @code{stat:perms}\n"
"below.\n"
"The mode of the file. This includes file type information and\n"
"the file permission bits. See @code{stat:type} and\n"
"@code{stat:perms} below.\n"
"@item stat:nlink\n"
"The number of hard links to the file.\n"
"@item stat:uid\n"
@ -501,18 +504,21 @@ SCM_DEFINE (scm_stat, "stat", 1, 0, 0,
"@item stat:ctime\n"
"The last modification time for the attributes of the file.\n"
"@item stat:blksize\n"
"The optimal block size for reading or writing the file, in bytes.\n"
"The optimal block size for reading or writing the file, in\n"
"bytes.\n"
"@item stat:blocks\n"
"The amount of disk space that the file occupies measured in units of\n"
"512 byte blocks.\n"
"@end table\n\n"
"The amount of disk space that the file occupies measured in\n"
"units of 512 byte blocks.\n"
"@end table\n"
"\n"
"In addition, the following procedures return the information\n"
"from stat:mode in a more convenient form:\n\n"
"from stat:mode in a more convenient form:\n"
"\n"
"@table @code\n"
"@item stat:type\n"
"A symbol representing the type of file. Possible values are\n"
"regular, directory, symlink, block-special, char-special,\n"
"fifo, socket and unknown\n"
"regular, directory, symlink, block-special, char-special, fifo,\n"
"socket and unknown\n"
"@item stat:perms\n"
"An integer representing the access permission bits.\n"
"@end table")
@ -685,8 +691,8 @@ scm_bits_t scm_tc16_dir;
SCM_DEFINE (scm_directory_stream_p, "directory-stream?", 1, 0, 0,
(SCM obj),
"Returns a boolean indicating whether @var{object} is a directory stream\n"
"as returned by @code{opendir}.")
"Return a boolean indicating whether @var{object} is a directory\n"
"stream as returned by @code{opendir}.")
#define FUNC_NAME s_scm_directory_stream_p
{
return SCM_BOOL (SCM_DIRP (obj));
@ -822,7 +828,7 @@ SCM_DEFINE (scm_chdir, "chdir", 1, 0, 0,
#ifdef HAVE_GETCWD
SCM_DEFINE (scm_getcwd, "getcwd", 0, 0, 0,
(),
"Returns the name of the current working directory.")
"Return the name of the current working directory.")
#define FUNC_NAME s_scm_getcwd
{
char *rv;
@ -1247,9 +1253,8 @@ SCM_DEFINE (scm_symlink, "symlink", 2, 0, 0,
#ifdef HAVE_READLINK
SCM_DEFINE (scm_readlink, "readlink", 1, 0, 0,
(SCM path),
"Returns the value of the symbolic link named by\n"
"@var{path} (a string), i.e., the\n"
"file that the link points to.")
"Return the value of the symbolic link named by @var{path} (a\n"
"string), i.e., the file that the link points to.")
#define FUNC_NAME s_scm_readlink
{
int rv;

8
libguile/fluids.c
View file

@ -138,7 +138,8 @@ SCM_DEFINE (scm_make_fluid, "make-fluid", 0, 0, 0,
SCM_DEFINE (scm_fluid_p, "fluid?", 1, 0, 0,
(SCM obj),
"Return #t iff @var{obj} is a fluid; otherwise, return #f.")
"Return @code{#t} iff @var{obj} is a fluid; otherwise, return\n"
"@code{#f}.")
#define FUNC_NAME s_scm_fluid_p
{
return SCM_BOOL(SCM_FLUIDP (obj));
@ -147,8 +148,9 @@ SCM_DEFINE (scm_fluid_p, "fluid?", 1, 0, 0,
SCM_DEFINE (scm_fluid_ref, "fluid-ref", 1, 0, 0,
(SCM fluid),
"Return the value associated with @var{fluid} in the current dynamic root.\n"
"If @var{fluid} has not been set, then this returns #f.")
"Return the value associated with @var{fluid} in the current\n"
"dynamic root. If @var{fluid} has not been set, then return\n"
"@code{#f}.")
#define FUNC_NAME s_scm_fluid_ref
{
int n;

57
libguile/fports.c
View file

@ -243,12 +243,12 @@ SCM_DEFINE (scm_file_port_p, "file-port?", 1, 0, 0,
* Return the new port.
*/
SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0,
(SCM filename, SCM modes),
"Open the file whose name is @var{string}, and return a port\n"
(SCM filename, SCM mode),
"Open the file whose name is @var{filename}, and return a port\n"
"representing that file. The attributes of the port are\n"
"determined by the @var{mode} string. The way in \n"
"which this is interpreted is similar to C stdio:\n\n"
"The first character must be one of the following:\n\n"
"determined by the @var{mode} string. The way in which this is\n"
"interpreted is similar to C stdio. The first character must be\n"
"one of the following:\n"
"@table @samp\n"
"@item r\n"
"Open an existing file for input.\n"
@ -256,48 +256,49 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0,
"Open a file for output, creating it if it doesn't already exist\n"
"or removing its contents if it does.\n"
"@item a\n"
"Open a file for output, creating it if it doesn't already exist.\n"
"All writes to the port will go to the end of the file.\n"
"Open a file for output, creating it if it doesn't already\n"
"exist. All writes to the port will go to the end of the file.\n"
"The \"append mode\" can be turned off while the port is in use\n"
"@pxref{Ports and File Descriptors, fcntl}\n"
"@end table\n\n"
"The following additional characters can be appended:\n\n"
"@end table\n"
"The following additional characters can be appended:\n"
"@table @samp\n"
"@item +\n"
"Open the port for both input and output. E.g., @code{r+}: open\n"
"an existing file for both input and output.\n"
"@item 0\n"
"Create an \"unbuffered\" port. In this case input and output operations\n"
"are passed directly to the underlying port implementation without\n"
"additional buffering. This is likely to slow down I/O operations.\n"
"The buffering mode can be changed while a port is in use\n"
"@pxref{Ports and File Descriptors, setvbuf}\n"
"Create an \"unbuffered\" port. In this case input and output\n"
"operations are passed directly to the underlying port\n"
"implementation without additional buffering. This is likely to\n"
"slow down I/O operations. The buffering mode can be changed\n"
"while a port is in use @pxref{Ports and File Descriptors,\n"
"setvbuf}\n"
"@item l\n"
"Add line-buffering to the port. The port output buffer will be\n"
"automatically flushed whenever a newline character is written.\n"
"@end table\n\n"
"In theory we could create read/write ports which were buffered in one\n"
"direction only. However this isn't included in the current interfaces.\n\n"
"If a file cannot be opened with the access requested,\n"
"@code{open-file} throws an exception.")
"@end table\n"
"In theory we could create read/write ports which were buffered\n"
"in one direction only. However this isn't included in the\n"
"current interfaces. If a file cannot be opened with the access\n"
"requested, @code{open-file} throws an exception.")
#define FUNC_NAME s_scm_open_file
{
SCM port;
int fdes;
int flags = 0;
char *file;
char *mode;
char *md;
char *ptr;
SCM_VALIDATE_STRING (1, filename);
SCM_VALIDATE_STRING (2, modes);
SCM_VALIDATE_STRING (2, mode);
SCM_STRING_COERCE_0TERMINATION_X (filename);
SCM_STRING_COERCE_0TERMINATION_X (modes);
SCM_STRING_COERCE_0TERMINATION_X (mode);
file = SCM_STRING_CHARS (filename);
mode = SCM_STRING_CHARS (modes);
md = SCM_STRING_CHARS (mode);
switch (*mode)
switch (*md)
{
case 'r':
flags |= O_RDONLY;
@ -309,9 +310,9 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0,
flags |= O_WRONLY | O_CREAT | O_APPEND;
break;
default:
scm_out_of_range (FUNC_NAME, modes);
scm_out_of_range (FUNC_NAME, mode);
}
ptr = mode + 1;
ptr = md + 1;
while (*ptr != '\0')
{
switch (*ptr)
@ -328,7 +329,7 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0,
case 'l': /* line buffered: handled during output. */
break;
default:
scm_out_of_range (FUNC_NAME, modes);
scm_out_of_range (FUNC_NAME, mode);
}
ptr++;
}
@ -341,7 +342,7 @@ SCM_DEFINE (scm_open_file, "open-file", 2, 0, 0,
scm_cons (scm_makfrom0str (strerror (en)),
scm_cons (filename, SCM_EOL)), en);
}
port = scm_fdes_to_port (fdes, mode, filename);
port = scm_fdes_to_port (fdes, md, filename);
return port;
}
#undef FUNC_NAME

17
libguile/gc.c
View file

@ -151,10 +151,10 @@ scm_assert_cell_valid (SCM cell)
SCM_DEFINE (scm_set_debug_cell_accesses_x, "set-debug-cell-accesses!", 1, 0, 0,
(SCM flag),
"If FLAG is #f, cell access checking is disabled.\n"
"If FLAG is #t, cell access checking is enabled.\n"
"This procedure only exists because the compile-time flag\n"
"SCM_DEBUG_CELL_ACCESSES was set to 1.\n")
"If @var{flag} is @code{#f}, cell access checking is disabled.\n"
"If @var{flag} is @code{#t}, cell access checking is enabled.\n"
"This procedure only exists when the compile-time flag\n"
"@code{SCM_DEBUG_CELL_ACCESSES} was set to 1.")
#define FUNC_NAME s_scm_set_debug_cell_accesses_x
{
if (SCM_FALSEP (flag)) {
@ -644,9 +644,9 @@ scm_check_freelist (SCM freelist)
SCM_DEFINE (scm_gc_set_debug_check_freelist_x, "gc-set-debug-check-freelist!", 1, 0, 0,
(SCM flag),
"If FLAG is #t, check the freelist for consistency on each cell allocation.\n"
"This procedure only exists because the GUILE_DEBUG_FREELIST \n"
"compile-time flag was selected.\n")
"If @var{flag} is @code{#t}, check the freelist for consistency\n"
"on each cell allocation. This procedure only exists when the\n"
"@code{GUILE_DEBUG_FREELIST} compile-time flag was selected.")
#define FUNC_NAME s_scm_gc_set_debug_check_freelist_x
{
/* [cmm] I did a double-take when I read this code the first time.
@ -745,7 +745,8 @@ compute_cells_allocated ()
SCM_DEFINE (scm_gc_stats, "gc-stats", 0, 0, 0,
(),
"Returns an association list of statistics about Guile's current use of storage. ")
"Return an association list of statistics about Guile's current\n"
"use of storage.")
#define FUNC_NAME s_scm_gc_stats
{
int i;

108
libguile/hashtab.c
View file

@ -191,7 +191,7 @@ SCM_DEFINE (scm_hashq_create_handle_x, "hashq-create-handle!", 3, 0, 0,
SCM_DEFINE (scm_hashq_ref, "hashq-ref", 2, 1, 0,
(SCM table, SCM obj, SCM dflt),
(SCM table, SCM key, SCM dflt),
"Look up @var{key} in the hash table @var{table}, and return the\n"
"value (if any) associated with it. If @var{key} is not found,\n"
"return @var{default} (or @code{#f} if no @var{default} argument\n"
@ -200,31 +200,32 @@ SCM_DEFINE (scm_hashq_ref, "hashq-ref", 2, 1, 0,
{
if (SCM_UNBNDP (dflt))
dflt = SCM_BOOL_F;
return scm_hash_fn_ref (table, obj, dflt, scm_ihashq, scm_sloppy_assq, 0);
return scm_hash_fn_ref (table, key, dflt, scm_ihashq, scm_sloppy_assq, 0);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hashq_set_x, "hashq-set!", 3, 0, 0,
(SCM table, SCM obj, SCM val),
(SCM table, SCM key, SCM val),
"Find the entry in @var{table} associated with @var{key}, and\n"
"store @var{value} there. Uses @code{eq?} for equality testing.")
#define FUNC_NAME s_scm_hashq_set_x
{
return scm_hash_fn_set_x (table, obj, val, scm_ihashq, scm_sloppy_assq, 0);
return scm_hash_fn_set_x (table, key, val, scm_ihashq, scm_sloppy_assq, 0);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hashq_remove_x, "hashq-remove!", 2, 0, 0,
(SCM table, SCM obj),
(SCM table, SCM key),
"Remove @var{key} (and any value associated with it) from\n"
"@var{table}. Uses @code{eq?} for equality tests.")
#define FUNC_NAME s_scm_hashq_remove_x
{
return scm_hash_fn_remove_x (table, obj, scm_ihashq, scm_sloppy_assq, scm_delq_x, 0);
return scm_hash_fn_remove_x (table, key, scm_ihashq, scm_sloppy_assq,
scm_delq_x, 0);
}
#undef FUNC_NAME
@ -251,13 +252,14 @@ SCM_DEFINE (scm_hashv_create_handle_x, "hashv-create-handle!", 3, 0, 0,
"associates @var{key} with @var{init}.")
#define FUNC_NAME s_scm_hashv_create_handle_x
{
return scm_hash_fn_create_handle_x (table, key, init, scm_ihashv, scm_sloppy_assv, 0);
return scm_hash_fn_create_handle_x (table, key, init, scm_ihashv,
scm_sloppy_assv, 0);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hashv_ref, "hashv-ref", 2, 1, 0,
(SCM table, SCM obj, SCM dflt),
(SCM table, SCM key, SCM dflt),
"Look up @var{key} in the hash table @var{table}, and return the\n"
"value (if any) associated with it. If @var{key} is not found,\n"
"return @var{default} (or @code{#f} if no @var{default} argument\n"
@ -266,30 +268,31 @@ SCM_DEFINE (scm_hashv_ref, "hashv-ref", 2, 1, 0,
{
if (SCM_UNBNDP (dflt))
dflt = SCM_BOOL_F;
return scm_hash_fn_ref (table, obj, dflt, scm_ihashv, scm_sloppy_assv, 0);
return scm_hash_fn_ref (table, key, dflt, scm_ihashv, scm_sloppy_assv, 0);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hashv_set_x, "hashv-set!", 3, 0, 0,
(SCM table, SCM obj, SCM val),
(SCM table, SCM key, SCM val),
"Find the entry in @var{table} associated with @var{key}, and\n"
"store @var{value} there. Uses @code{eqv?} for equality testing.")
#define FUNC_NAME s_scm_hashv_set_x
{
return scm_hash_fn_set_x (table, obj, val, scm_ihashv, scm_sloppy_assv, 0);
return scm_hash_fn_set_x (table, key, val, scm_ihashv, scm_sloppy_assv, 0);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hashv_remove_x, "hashv-remove!", 2, 0, 0,
(SCM table, SCM obj),
(SCM table, SCM key),
"Remove @var{key} (and any value associated with it) from\n"
"@var{table}. Uses @code{eqv?} for equality tests.")
#define FUNC_NAME s_scm_hashv_remove_x
{
return scm_hash_fn_remove_x (table, obj, scm_ihashv, scm_sloppy_assv, scm_delv_x, 0);
return scm_hash_fn_remove_x (table, key, scm_ihashv, scm_sloppy_assv,
scm_delv_x, 0);
}
#undef FUNC_NAME
@ -321,7 +324,7 @@ SCM_DEFINE (scm_hash_create_handle_x, "hash-create-handle!", 3, 0, 0,
SCM_DEFINE (scm_hash_ref, "hash-ref", 2, 1, 0,
(SCM table, SCM obj, SCM dflt),
(SCM table, SCM key, SCM dflt),
"Look up @var{key} in the hash table @var{table}, and return the\n"
"value (if any) associated with it. If @var{key} is not found,\n"
"return @var{default} (or @code{#f} if no @var{default} argument\n"
@ -330,32 +333,33 @@ SCM_DEFINE (scm_hash_ref, "hash-ref", 2, 1, 0,
{
if (SCM_UNBNDP (dflt))
dflt = SCM_BOOL_F;
return scm_hash_fn_ref (table, obj, dflt, scm_ihash, scm_sloppy_assoc, 0);
return scm_hash_fn_ref (table, key, dflt, scm_ihash, scm_sloppy_assoc, 0);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hash_set_x, "hash-set!", 3, 0, 0,
(SCM table, SCM obj, SCM val),
(SCM table, SCM key, SCM val),
"Find the entry in @var{table} associated with @var{key}, and\n"
"store @var{value} there. Uses @code{equal?} for equality\n"
"testing.")
#define FUNC_NAME s_scm_hash_set_x
{
return scm_hash_fn_set_x (table, obj, val, scm_ihash, scm_sloppy_assoc, 0);
return scm_hash_fn_set_x (table, key, val, scm_ihash, scm_sloppy_assoc, 0);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hash_remove_x, "hash-remove!", 2, 0, 0,
(SCM table, SCM obj),
(SCM table, SCM key),
"Remove @var{key} (and any value associated with it) from\n"
"@var{table}. Uses @code{equal?} for equality tests.")
#define FUNC_NAME s_scm_hash_remove_x
{
return scm_hash_fn_remove_x (table, obj, scm_ihash, scm_sloppy_assoc, scm_delete_x, 0);
return scm_hash_fn_remove_x (table, key, scm_ihash, scm_sloppy_assoc,
scm_delete_x, 0);
}
#undef FUNC_NAME
@ -415,11 +419,11 @@ scm_delx_x (SCM obj,SCM alist,struct scm_ihashx_closure * closure)
SCM_DEFINE (scm_hashx_get_handle, "hashx-get-handle", 4, 0, 0,
(SCM hash, SCM assoc, SCM table, SCM obj),
"This behaves the same way as the corresponding @code{-get-handle}\n"
"function, but uses @var{hasher} as a\n"
"hash function and @var{assoc} to compare keys. @code{hasher} must\n"
"be a function that takes two arguments, a key to be hashed and a\n"
(SCM hash, SCM assoc, SCM table, SCM key),
"This behaves the same way as the corresponding\n"
"@code{-get-handle} function, but uses @var{hash} as a hash\n"
"function and @var{assoc} to compare keys. @code{hash} must be\n"
"a function that takes two arguments, a key to be hashed and a\n"
"table size. @code{assoc} must be an associator function, like\n"
"@code{assoc}, @code{assq} or @code{assv}.")
#define FUNC_NAME s_scm_hashx_get_handle
@ -427,17 +431,18 @@ SCM_DEFINE (scm_hashx_get_handle, "hashx-get-handle", 4, 0, 0,
struct scm_ihashx_closure closure;
closure.hash = hash;
closure.assoc = assoc;
return scm_hash_fn_get_handle (table, obj, scm_ihashx, scm_sloppy_assx, (void *)&closure);
return scm_hash_fn_get_handle (table, key, scm_ihashx, scm_sloppy_assx,
(void *)&closure);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hashx_create_handle_x, "hashx-create-handle!", 5, 0, 0,
(SCM hash, SCM assoc, SCM table, SCM obj, SCM init),
"This behaves the same way as the corresponding @code{-create-handle}\n"
"function, but uses @var{hasher} as a\n"
"hash function and @var{assoc} to compare keys. @code{hasher} must\n"
"be a function that takes two arguments, a key to be hashed and a\n"
(SCM hash, SCM assoc, SCM table, SCM key, SCM init),
"This behaves the same way as the corresponding\n"
"@code{-create-handle} function, but uses @var{hash} as a hash\n"
"function and @var{assoc} to compare keys. @code{hash} must be\n"
"a function that takes two arguments, a key to be hashed and a\n"
"table size. @code{assoc} must be an associator function, like\n"
"@code{assoc}, @code{assq} or @code{assv}.")
#define FUNC_NAME s_scm_hashx_create_handle_x
@ -445,22 +450,24 @@ SCM_DEFINE (scm_hashx_create_handle_x, "hashx-create-handle!", 5, 0, 0,
struct scm_ihashx_closure closure;
closure.hash = hash;
closure.assoc = assoc;
return scm_hash_fn_create_handle_x (table, obj, init, scm_ihashx, scm_sloppy_assx, (void *)&closure);
return scm_hash_fn_create_handle_x (table, key, init, scm_ihashx,
scm_sloppy_assx, (void *)&closure);
}
#undef FUNC_NAME
SCM_DEFINE (scm_hashx_ref, "hashx-ref", 4, 1, 0,
(SCM hash, SCM assoc, SCM table, SCM obj, SCM dflt),
(SCM hash, SCM assoc, SCM table, SCM key, SCM dflt),
"This behaves the same way as the corresponding @code{ref}\n"
"function, but uses @var{hasher} as a\n"
"hash function and @var{assoc} to compare keys. @code{hasher} must\n"
"be a function that takes two arguments, a key to be hashed and a\n"
"table size. @code{assoc} must be an associator function, like\n"
"@code{assoc}, @code{assq} or @code{assv}.\n\n"
"By way of illustration, @code{hashq-ref table key} is equivalent\n"
"to @code{hashx-ref hashq assq table key}.")
"function, but uses @var{hash} as a hash function and\n"
"@var{assoc} to compare keys. @code{hash} must be a function\n"
"that takes two arguments, a key to be hashed and a table size.\n"
"@code{assoc} must be an associator function, like @code{assoc},\n"
"@code{assq} or @code{assv}.\n"
"\n"
"By way of illustration, @code{hashq-ref table key} is\n"
"equivalent to @code{hashx-ref hashq assq table key}.")
#define FUNC_NAME s_scm_hashx_ref
{
struct scm_ihashx_closure closure;
@ -468,7 +475,8 @@ SCM_DEFINE (scm_hashx_ref, "hashx-ref", 4, 1, 0,
dflt = SCM_BOOL_F;
closure.hash = hash;
closure.assoc = assoc;
return scm_hash_fn_ref (table, obj, dflt, scm_ihashx, scm_sloppy_assx, (void *)&closure);
return scm_hash_fn_ref (table, key, dflt, scm_ihashx, scm_sloppy_assx,
(void *)&closure);
}
#undef FUNC_NAME
@ -476,21 +484,23 @@ SCM_DEFINE (scm_hashx_ref, "hashx-ref", 4, 1, 0,
SCM_DEFINE (scm_hashx_set_x, "hashx-set!", 5, 0, 0,
(SCM hash, SCM assoc, SCM table, SCM obj, SCM val),
(SCM hash, SCM assoc, SCM table, SCM key, SCM val),
"This behaves the same way as the corresponding @code{set!}\n"
"function, but uses @var{hasher} as a\n"
"hash function and @var{assoc} to compare keys. @code{hasher} must\n"
"be a function that takes two arguments, a key to be hashed and a\n"
"table size. @code{assoc} must be an associator function, like\n"
"@code{assoc}, @code{assq} or @code{assv}.\n\n"
"By way of illustration, @code{hashq-set! table key} is equivalent\n"
"to @code{hashx-set! hashq assq table key}.")
"function, but uses @var{hash} as a hash function and\n"
"@var{assoc} to compare keys. @code{hash} must be a function\n"
"that takes two arguments, a key to be hashed and a table size.\n"
"@code{assoc} must be an associator function, like @code{assoc},\n"
"@code{assq} or @code{assv}.\n"
"\n"
" By way of illustration, @code{hashq-set! table key} is\n"
"equivalent to @code{hashx-set! hashq assq table key}.")
#define FUNC_NAME s_scm_hashx_set_x
{
struct scm_ihashx_closure closure;
closure.hash = hash;
closure.assoc = assoc;
return scm_hash_fn_set_x (table, obj, val, scm_ihashx, scm_sloppy_assx, (void *)&closure);
return scm_hash_fn_set_x (table, key, val, scm_ihashx, scm_sloppy_assx,
(void *)&closure);
}
#undef FUNC_NAME

46
libguile/ioext.c
View file

@ -165,15 +165,16 @@ SCM_DEFINE (scm_read_string_x_partial, "read-string!/partial", 1, 3, 0,
#undef FUNC_NAME
SCM_DEFINE (scm_ftell, "ftell", 1, 0, 0,
(SCM object),
"Returns an integer representing the current position of @var{fd/port},\n"
"measured from the beginning. Equivalent to:\n"
"@smalllisp\n"
(SCM fd_port),
"Return an integer representing the current position of\n"
"@var{fd/port}, measured from the beginning. Equivalent to:\n"
"\n"
"@lisp\n"
"(seek port 0 SEEK_CUR)\n"
"@end smalllisp")
"@end lisp")
#define FUNC_NAME s_scm_ftell
{
return scm_seek (object, SCM_INUM0, SCM_MAKINUM (SEEK_CUR));
return scm_seek (fd_port, SCM_INUM0, SCM_MAKINUM (SEEK_CUR));
}
#undef FUNC_NAME
@ -181,12 +182,12 @@ SCM_DEFINE (scm_ftell, "ftell", 1, 0, 0,
#if (SCM_DEBUG_DEPRECATED == 0)
SCM_DEFINE (scm_fseek, "fseek", 3, 0, 0,
(SCM object, SCM offset, SCM whence),
"Obsolete. Almost the same as seek, above, but the return value is\n"
"unspecified.")
(SCM fd_port, SCM offset, SCM whence),
"Obsolete. Almost the same as @code{seek}, but the return value\n"
"is unspecified.")
#define FUNC_NAME s_scm_fseek
{
scm_seek (object, offset, whence);
scm_seek (fd_port, offset, whence);
return SCM_UNSPECIFIED;
}
#undef FUNC_NAME
@ -242,7 +243,9 @@ SCM_DEFINE (scm_redirect_port, "redirect-port", 2, 0, 0,
SCM_DEFINE (scm_dup_to_fdes, "dup->fdes", 1, 1, 0,
(SCM fd_or_port, SCM fd),
"Returns an integer file descriptor.")
"Return a new integer file descriptor referring to the open file\n"
"designated by @var{fd_or_port}, which must be either an open\n"
"file port or a file descriptor.")
#define FUNC_NAME s_scm_dup_to_fdes
{
int oldfd, newfd, rv;
@ -307,8 +310,8 @@ SCM_DEFINE (scm_dup2, "dup2", 2, 0, 0,
SCM_DEFINE (scm_fileno, "fileno", 1, 0, 0,
(SCM port),
"Returns the integer file descriptor underlying @var{port}.\n"
"Does not change its revealed count.")
"Return the integer file descriptor underlying @var{port}. Does\n"
"not change its revealed count.")
#define FUNC_NAME s_scm_fileno
{
port = SCM_COERCE_OUTPORT (port);
@ -323,8 +326,8 @@ SCM_DEFINE (scm_fileno, "fileno", 1, 0, 0,
if it is not going to assume that the arg is a port */
SCM_DEFINE (scm_isatty_p, "isatty?", 1, 0, 0,
(SCM port),
"Returns @code{#t} if @var{port} is using a serial\n"
"non-file device, otherwise @code{#f}.")
"Return @code{#t} if @var{port} is using a serial non--file\n"
"device, otherwise @code{#f}.")
#define FUNC_NAME s_scm_isatty_p
{
int rv;
@ -343,10 +346,10 @@ SCM_DEFINE (scm_isatty_p, "isatty?", 1, 0, 0,
SCM_DEFINE (scm_fdopen, "fdopen", 2, 0, 0,
(SCM fdes, SCM modes),
"Returns a new port based on the file descriptor @var{fdes}.\n"
"Modes are given by the string @var{modes}. The revealed count of the port\n"
"is initialized to zero. The modes string is the same as that accepted\n"
"by @ref{File Ports, open-file}.")
"Return a new port based on the file descriptor @var{fdes}.\n"
"Modes are given by the string @var{modes}. The revealed count\n"
"of the port is initialized to zero. The modes string is the\n"
"same as that accepted by @ref{File Ports, open-file}.")
#define FUNC_NAME s_scm_fdopen
{
SCM_VALIDATE_INUM (1,fdes);
@ -403,8 +406,9 @@ SCM_DEFINE (scm_primitive_move_to_fdes, "primitive-move->fdes", 2, 0, 0,
/* Return a list of ports using a given file descriptor. */
SCM_DEFINE (scm_fdes_to_ports, "fdes->ports", 1, 0, 0,
(SCM fd),
"Returns a list of existing ports which have @var{fdes} as an\n"
"underlying file descriptor, without changing their revealed counts.")
"Return a list of existing ports which have @var{fdes} as an\n"
"underlying file descriptor, without changing their revealed\n"
"counts.")
#define FUNC_NAME s_scm_fdes_to_ports
{
SCM result = SCM_EOL;

3
libguile/keywords.c
View file

@ -109,7 +109,8 @@ scm_c_make_keyword (char *s)
SCM_DEFINE (scm_keyword_p, "keyword?", 1, 0, 0,
(SCM obj),
"Returns @code{#t} if the argument @var{obj} is a keyword, else @code{#f}.")
"Return @code{#t} if the argument @var{obj} is a keyword, else\n"
"@code{#f}.")
#define FUNC_NAME s_scm_keyword_p
{
return SCM_BOOL (SCM_KEYWORDP (obj));

33
libguile/list.c
View file

@ -194,19 +194,19 @@ SCM_DEFINE (scm_append, "append", 0, 0, 1,
(SCM args),
"Return a list consisting of the elements the lists passed as\n"
"arguments.\n"
"@example\n"
"@lisp\n"
"(append '(x) '(y)) @result{} (x y)\n"
"(append '(a) '(b c d)) @result{} (a b c d)\n"
"(append '(a (b)) '((c))) @result{} (a (b) (c))\n"
"@end example\n"
"@end lisp\n"
"The resulting list is always newly allocated, except that it\n"
"shares structure with the last list argument. The last\n"
"argument may actually be any object; an improper list results\n"
"if the last argument is not a proper list.\n"
"@example\n"
"@lisp\n"
"(append '(a b) '(c . d)) @result{} (a b c . d)\n"
"(append '() 'a) @result{} a\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_append
{
SCM_VALIDATE_REST_ARGUMENT (args);
@ -235,25 +235,26 @@ SCM_DEFINE (scm_append, "append", 0, 0, 1,
SCM_DEFINE (scm_append_x, "append!", 0, 0, 1,
(SCM args),
"A destructive version of @code{append} (@pxref{Pairs and Lists,,,r4rs,\n"
"The Revised^4 Report on Scheme}). The cdr field of each list's final\n"
"pair is changed to point to the head of the next list, so no consing is\n"
"performed. Return a pointer to the mutated list.")
(SCM lists),
"A destructive version of @code{append} (@pxref{Pairs and\n"
"Lists,,,r4rs, The Revised^4 Report on Scheme}). The cdr field\n"
"of each list's final pair is changed to point to the head of\n"
"the next list, so no consing is performed. Return a pointer to\n"
"the mutated list.")
#define FUNC_NAME s_scm_append_x
{
SCM_VALIDATE_REST_ARGUMENT (args);
SCM_VALIDATE_REST_ARGUMENT (lists);
while (1) {
if (SCM_NULLP (args)) {
if (SCM_NULLP (lists)) {
return SCM_EOL;
} else {
SCM arg = SCM_CAR (args);
args = SCM_CDR (args);
if (SCM_NULLP (args)) {
SCM arg = SCM_CAR (lists);
lists = SCM_CDR (lists);
if (SCM_NULLP (lists)) {
return arg;
} else if (!SCM_NULLP (arg)) {
SCM_VALIDATE_CONS (SCM_ARG1, arg);
SCM_SETCDR (scm_last_pair (arg), scm_append_x (args));
SCM_SETCDR (scm_last_pair (arg), scm_append_x (lists));
return arg;
}
}
@ -565,7 +566,7 @@ SCM_DEFINE (scm_sloppy_member, "sloppy-member", 2, 0, 0,
/* The function scm_c_memq returns the first sublist of list whose car is
* 'eq?' obj, where the sublists of list are the non-empty lists returned by
* (list-tail list k) for k less than the length of list. If obj does not
* occur in list, then #f (not the empty list) is returned. (r5rs)
* occur in list, then #f (not the empty list) is returned.
* List must be a proper list, otherwise scm_c_memq may crash or loop
* endlessly.
*/

58
libguile/macros.c
View file

@ -55,9 +55,10 @@ scm_bits_t scm_tc16_macro;
SCM_DEFINE (scm_makacro, "procedure->syntax", 1, 0, 0,
(SCM code),
"Returns a @dfn{macro} which, when a symbol defined to this value\n"
"appears as the first symbol in an expression, returns the result\n"
"of applying @var{code} to the expression and the environment.")
"Return a @dfn{macro} which, when a symbol defined to this value\n"
"appears as the first symbol in an expression, returns the\n"
"result of applying @var{code} to the expression and the\n"
"environment.")
#define FUNC_NAME s_scm_makacro
{
SCM_VALIDATE_PROC (1,code);
@ -68,18 +69,19 @@ SCM_DEFINE (scm_makacro, "procedure->syntax", 1, 0, 0,
SCM_DEFINE (scm_makmacro, "procedure->macro", 1, 0, 0,
(SCM code),
"Returns a @dfn{macro} which, when a symbol defined to this value\n"
"appears as the first symbol in an expression, evaluates the result\n"
"of applying @var{code} to the expression and the environment.\n"
"The value returned from @var{code} which has been passed to\n"
"@code{procedure->memoizing-macro} replaces the form passed to\n"
"@var{code}. For example:\n\n"
"@example\n"
"Return a @dfn{macro} which, when a symbol defined to this value\n"
"appears as the first symbol in an expression, evaluates the\n"
"result of applying @var{code} to the expression and the\n"
"environment. The value returned from @var{code} which has been\n"
"passed to @code{procedure->memoizing-macro} replaces the form\n"
"passed to @var{code}. For example:\n"
"\n"
"@lisp\n"
"(define trace\n"
" (procedure->macro\n"
" (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))\n\n"
"(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_makmacro
{
SCM_VALIDATE_PROC (1,code);
@ -90,18 +92,19 @@ SCM_DEFINE (scm_makmacro, "procedure->macro", 1, 0, 0,
SCM_DEFINE (scm_makmmacro, "procedure->memoizing-macro", 1, 0, 0,
(SCM code),
"Returns a @dfn{macro} which, when a symbol defined to this value\n"
"appears as the first symbol in an expression, evaluates the result\n"
"of applying @var{proc} to the expression and the environment.\n"
"The value returned from @var{proc} which has been passed to\n"
"@code{procedure->memoizing-macro} replaces the form passed to\n"
"@var{proc}. For example:\n\n"
"@example\n"
"(define trace\n"
" (procedure->macro\n"
" (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))\n\n"
"(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).\n"
"@end example")
"Return a @dfn{macro} which, when a symbol defined to this value\n"
"appears as the first symbol in an expression, evaluates the\n"
"result of applying @var{proc} to the expression and the\n"
"environment. The value returned from @var{proc} which has been\n"
"passed to @code{procedure->memoizing-macro} replaces the form\n"
"passed to @var{proc}. For example:\n"
"\n"
"@lisp\n"
"(define trace\n"
" (procedure->macro\n"
" (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))\n\n"
"(trace @i{foo}) @equiv{} (set! @i{foo} (tracef @i{foo} '@i{foo})).\n"
"@end lisp")
#define FUNC_NAME s_scm_makmmacro
{
SCM_VALIDATE_PROC (1,code);
@ -127,10 +130,11 @@ SCM_SYMBOL (scm_sym_mmacro, "macro!");
SCM_DEFINE (scm_macro_type, "macro-type", 1, 0, 0,
(SCM m),
"Return one of the symbols @code{syntax}, @code{macro} or @code{macro!},\n"
"depending on whether @var{obj} is a syntax tranformer, a regular macro,\n"
"or a memoizing macro, respectively. If @var{obj} is not a macro,\n"
"@code{#f} is returned.")
"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"
"respectively. If @var{m} is not a macro, @code{#f} is\n"
"returned.")
#define FUNC_NAME s_scm_macro_type
{
if (!SCM_TYP16_PREDICATE (scm_tc16_macro, m))

10
libguile/modules.c
View file

@ -95,11 +95,11 @@ scm_set_current_module (SCM module)
SCM_DEFINE (scm_interaction_environment, "interaction-environment", 0, 0, 0,
(),
"This procedure returns a specifier for the environment that contains\n"
"implementation-defined bindings, typically a superset of those listed in\n"
"the report. The intent is that this procedure will return the\n"
"environment in which the implementation would evaluate expressions\n"
"dynamically typed by the user.")
"Return a specifier for the environment that contains\n"
"implementation--defined bindings, typically a superset of those\n"
"listed in the report. The intent is that this procedure will\n"
"return the environment in which the implementation would\n"
"evaluate expressions dynamically typed by the user.")
#define FUNC_NAME s_scm_interaction_environment
{
return scm_current_module ();

42
libguile/net_db.c
View file

@ -89,11 +89,11 @@ extern int h_errno;
SCM_DEFINE (scm_inet_aton, "inet-aton", 1, 0, 0,
(SCM address),
"Converts a string containing an Internet host address in the traditional\n"
"dotted decimal notation into an integer.\n\n"
"@smalllisp\n"
"(inet-aton \"127.0.0.1\") @result{} 2130706433\n\n"
"@end smalllisp")
"Converts a string containing an Internet host address in the\n"
"traditional dotted decimal notation into an integer.\n"
"@lisp\n"
"(inet-aton \"127.0.0.1\") @result{} 2130706433\n"
"@end lisp")
#define FUNC_NAME s_scm_inet_aton
{
struct in_addr soka;
@ -109,11 +109,11 @@ SCM_DEFINE (scm_inet_aton, "inet-aton", 1, 0, 0,
SCM_DEFINE (scm_inet_ntoa, "inet-ntoa", 1, 0, 0,
(SCM inetid),
"Converts an integer Internet host address into a string with the\n"
"traditional dotted decimal representation.\n\n"
"@smalllisp\n"
"Converts an integer Internet host address into a string with\n"
"the traditional dotted decimal representation.\n"
"@lisp\n"
"(inet-ntoa 2130706433) @result{} \"127.0.0.1\"\n"
"@end smalllisp")
"@end lisp")
#define FUNC_NAME s_scm_inet_ntoa
{
struct in_addr addr;
@ -129,10 +129,11 @@ SCM_DEFINE (scm_inet_ntoa, "inet-ntoa", 1, 0, 0,
#ifdef HAVE_INET_NETOF
SCM_DEFINE (scm_inet_netof, "inet-netof", 1, 0, 0,
(SCM address),
"Returns the network number part of the given integer Internet address.\n\n"
"@smalllisp\n"
"Return the network number part of the given integer Internet\n"
"address.\n"
"@lisp\n"
"(inet-netof 2130706433) @result{} 127\n"
"@end smalllisp")
"@end lisp")
#define FUNC_NAME s_scm_inet_netof
{
struct in_addr addr;
@ -145,11 +146,11 @@ SCM_DEFINE (scm_inet_netof, "inet-netof", 1, 0, 0,
#ifdef HAVE_INET_LNAOF
SCM_DEFINE (scm_lnaof, "inet-lnaof", 1, 0, 0,
(SCM address),
"Returns the local-address-with-network part of the given Internet\n"
"address.\n\n"
"@smalllisp\n"
"Return the local-address-with-network part of the given\n"
"Internet address.\n"
"@lisp\n"
"(inet-lnaof 2130706433) @result{} 1\n"
"@end smalllisp")
"@end lisp")
#define FUNC_NAME s_scm_lnaof
{
struct in_addr addr;
@ -162,11 +163,12 @@ SCM_DEFINE (scm_lnaof, "inet-lnaof", 1, 0, 0,
#ifdef HAVE_INET_MAKEADDR
SCM_DEFINE (scm_inet_makeaddr, "inet-makeaddr", 2, 0, 0,
(SCM net, SCM lna),
"Makes an Internet host address by combining the network number @var{net}\n"
"with the local-address-within-network number @var{lna}.\n\n"
"@smalllisp\n"
"Makes an Internet host address by combining the network number\n"
"@var{net} with the local-address-within-network number\n"
"@var{lna}.\n"
"@lisp\n"
"(inet-makeaddr 127 1) @result{} 2130706433\n"
"@end smalllisp")
"@end lisp")
#define FUNC_NAME s_scm_inet_makeaddr
{
struct in_addr addr;

161
libguile/numbers.c
View file

@ -746,13 +746,13 @@ SCM scm_big_test(SCM_BIGDIG *x, scm_sizet nx, int xsgn, SCM bigy)
SCM_DEFINE1 (scm_logand, "logand", scm_tc7_asubr,
(SCM n1, SCM n2),
"Returns the integer which is the bit-wise AND of the two integer\n"
"arguments.\n\n"
"Example:\n"
"@lisp\n"
"(number->string (logand #b1100 #b1010) 2)\n"
" @result{} \"1000\"\n"
"@end lisp")
"Return the integer which is the bit-wise AND of the two integer\n"
"arguments.\n"
"\n"
"@lisp\n"
"(number->string (logand #b1100 #b1010) 2)\n"
" @result{} \"1000\"\n"
"@end lisp")
#define FUNC_NAME s_scm_logand
{
long int nn1;
@ -833,13 +833,13 @@ SCM_DEFINE1 (scm_logand, "logand", scm_tc7_asubr,
SCM_DEFINE1 (scm_logior, "logior", scm_tc7_asubr,
(SCM n1, SCM n2),
"Returns the integer which is the bit-wise OR of the two integer\n"
"arguments.\n\n"
"Example:\n"
"@lisp\n"
"(number->string (logior #b1100 #b1010) 2)\n"
" @result{} \"1110\"\n"
"@end lisp")
"Return the integer which is the bit-wise OR of the two integer\n"
"arguments.\n"
"\n"
"@lisp\n"
"(number->string (logior #b1100 #b1010) 2)\n"
" @result{} \"1110\"\n"
"@end lisp")
#define FUNC_NAME s_scm_logior
{
long int nn1;
@ -919,13 +919,13 @@ SCM_DEFINE1 (scm_logior, "logior", scm_tc7_asubr,
SCM_DEFINE1 (scm_logxor, "logxor", scm_tc7_asubr,
(SCM n1, SCM n2),
"Returns the integer which is the bit-wise XOR of the two integer\n"
"arguments.\n\n"
"Example:\n"
"@lisp\n"
"(number->string (logxor #b1100 #b1010) 2)\n"
" @result{} \"110\"\n"
"@end lisp")
"Return the integer which is the bit-wise XOR of the two integer\n"
"arguments.\n"
"\n"
"@lisp\n"
"(number->string (logxor #b1100 #b1010) 2)\n"
" @result{} \"110\"\n"
"@end lisp")
#define FUNC_NAME s_scm_logxor
{
long int nn1;
@ -989,54 +989,54 @@ SCM_DEFINE1 (scm_logxor, "logxor", scm_tc7_asubr,
SCM_DEFINE (scm_logtest, "logtest", 2, 0, 0,
(SCM n1, SCM n2),
"@example\n"
(SCM j, SCM k),
"@lisp\n"
"(logtest j k) @equiv{} (not (zero? (logand j k)))\n\n"
"(logtest #b0100 #b1011) @result{} #f\n"
"(logtest #b0100 #b0111) @result{} #t\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_logtest
{
long int nn1;
long int nj;
if (SCM_INUMP (n1)) {
nn1 = SCM_INUM (n1);
if (SCM_INUMP (n2)) {
long nn2 = SCM_INUM (n2);
return SCM_BOOL (nn1 & nn2);
} else if (SCM_BIGP (n2)) {
if (SCM_INUMP (j)) {
nj = SCM_INUM (j);
if (SCM_INUMP (k)) {
long nk = SCM_INUM (k);
return SCM_BOOL (nj & nk);
} else if (SCM_BIGP (k)) {
intbig:
{
# ifndef SCM_DIGSTOOBIG
long z = scm_pseudolong (nn1);
long z = scm_pseudolong (nj);
return scm_big_test ((SCM_BIGDIG *)&z, SCM_DIGSPERLONG,
(nn1 < 0) ? SCM_BIGSIGNFLAG : 0, n2);
(nj < 0) ? SCM_BIGSIGNFLAG : 0, k);
# else
SCM_BIGDIG zdigs [SCM_DIGSPERLONG];
scm_longdigs (nn1, zdigs);
scm_longdigs (nj, zdigs);
return scm_big_test (zdigs, SCM_DIGSPERLONG,
(nn1 < 0) ? SCM_BIGSIGNFLAG : 0, n2);
(nj < 0) ? SCM_BIGSIGNFLAG : 0, k);
# endif
}
} else {
SCM_WRONG_TYPE_ARG (SCM_ARG2, n2);
SCM_WRONG_TYPE_ARG (SCM_ARG2, k);
}
} else if (SCM_BIGP (n1)) {
if (SCM_INUMP (n2)) {
SCM_SWAP (n1, n2);
nn1 = SCM_INUM (n1);
} else if (SCM_BIGP (j)) {
if (SCM_INUMP (k)) {
SCM_SWAP (j, k);
nj = SCM_INUM (j);
goto intbig;
} else if (SCM_BIGP (n2)) {
if (SCM_NUMDIGS (n1) > SCM_NUMDIGS (n2)) {
SCM_SWAP (n1, n2);
} else if (SCM_BIGP (k)) {
if (SCM_NUMDIGS (j) > SCM_NUMDIGS (k)) {
SCM_SWAP (j, k);
}
return scm_big_test (SCM_BDIGITS (n1), SCM_NUMDIGS (n1),
SCM_BIGSIGN (n1), n2);
return scm_big_test (SCM_BDIGITS (j), SCM_NUMDIGS (j),
SCM_BIGSIGN (j), k);
} else {
SCM_WRONG_TYPE_ARG (SCM_ARG2, n2);
SCM_WRONG_TYPE_ARG (SCM_ARG2, k);
}
} else {
SCM_WRONG_TYPE_ARG (SCM_ARG1, n1);
SCM_WRONG_TYPE_ARG (SCM_ARG1, j);
}
}
#undef FUNC_NAME
@ -1044,14 +1044,14 @@ SCM_DEFINE (scm_logtest, "logtest", 2, 0, 0,
SCM_DEFINE (scm_logbit_p, "logbit?", 2, 0, 0,
(SCM index, SCM j),
"@example\n"
"@lisp\n"
"(logbit? index j) @equiv{} (logtest (integer-expt 2 index) j)\n\n"
"(logbit? 0 #b1101) @result{} #t\n"
"(logbit? 1 #b1101) @result{} #f\n"
"(logbit? 2 #b1101) @result{} #t\n"
"(logbit? 3 #b1101) @result{} #t\n"
"(logbit? 4 #b1101) @result{} #f\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_logbit_p
{
unsigned long int iindex;
@ -1092,14 +1092,15 @@ SCM_DEFINE (scm_logbit_p, "logbit?", 2, 0, 0,
SCM_DEFINE (scm_lognot, "lognot", 1, 0, 0,
(SCM n),
"Returns the integer which is the 2s-complement of the integer argument.\n\n"
"Example:\n"
"Return the integer which is the 2s-complement of the integer\n"
"argument.\n"
"\n"
"@lisp\n"
"(number->string (lognot #b10000000) 2)\n"
" @result{} \"-10000001\"\n"
"(number->string (lognot #b0) 2)\n"
" @result{} \"-1\"\n"
"@end lisp\n")
"@end lisp")
#define FUNC_NAME s_scm_lognot
{
return scm_difference (SCM_MAKINUM (-1L), n);
@ -1108,8 +1109,9 @@ SCM_DEFINE (scm_lognot, "lognot", 1, 0, 0,
SCM_DEFINE (scm_integer_expt, "integer-expt", 2, 0, 0,
(SCM n, SCM k),
"Returns @var{n} raised to the non-negative integer exponent @var{k}.\n\n"
"Example:\n"
"Return @var{n} raised to the non-negative integer exponent\n"
"@var{k}.\n"
"\n"
"@lisp\n"
"(integer-expt 2 5)\n"
" @result{} 32\n"
@ -1148,21 +1150,20 @@ SCM_DEFINE (scm_integer_expt, "integer-expt", 2, 0, 0,
SCM_DEFINE (scm_ash, "ash", 2, 0, 0,
(SCM n, SCM cnt),
"The function ash performs an arithmetic shift left by @var{CNT}\n"
"bits (or shift right, if @var{cnt} is negative).\n"
"'Arithmetic' means, that the function does not guarantee to\n"
"keep the bit structure of @var{n}, but rather guarantees that\n"
"the result will always be rounded towards minus infinity.\n"
"Therefore, the results of ash and a corresponding bitwise\n"
"shift will differ if N is negative.\n\n"
"The function ash performs an arithmetic shift left by @var{cnt}\n"
"bits (or shift right, if @var{cnt} is negative). 'Arithmetic'\n"
"means, that the function does not guarantee to keep the bit\n"
"structure of @var{n}, but rather guarantees that the result\n"
"will always be rounded towards minus infinity. Therefore, the\n"
"results of ash and a corresponding bitwise shift will differ if\n"
"@var{n} is negative.\n"
"\n"
"Formally, the function returns an integer equivalent to\n"
"@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.\n\n"
"Example:\n"
"@code{(inexact->exact (floor (* @var{n} (expt 2 @var{cnt}))))}.\n"
"\n"
"@lisp\n"
"(number->string (ash #b1 3) 2)\n"
" @result{} \"1000\"\n"
"(number->string (ash #b1010 -1) 2)\n"
" @result{} \"101\"\n"
"(number->string (ash #b1 3) 2) @result{} \"1000\"\n"
"(number->string (ash #b1010 -1) 2) @result{} \"101\"\n"
"@end lisp")
#define FUNC_NAME s_scm_ash
{
@ -1207,10 +1208,10 @@ SCM_DEFINE (scm_ash, "ash", 2, 0, 0,
SCM_DEFINE (scm_bit_extract, "bit-extract", 3, 0, 0,
(SCM n, SCM start, SCM end),
"Returns the integer composed of the @var{start} (inclusive) through\n"
"@var{end} (exclusive) bits of @var{n}. The @var{start}th bit becomes\n"
"the 0-th bit in the result.@refill\n\n"
"Example:\n"
"Return the integer composed of the @var{start} (inclusive)\n"
"through @var{end} (exclusive) bits of @var{n}. The\n"
"@var{start}th bit becomes the 0-th bit in the result.\n"
"\n"
"@lisp\n"
"(number->string (bit-extract #b1101101010 0 4) 2)\n"
" @result{} \"1010\"\n"
@ -1276,11 +1277,11 @@ static const char scm_logtab[] = {
SCM_DEFINE (scm_logcount, "logcount", 1, 0, 0,
(SCM n),
"Returns the number of bits in integer @var{n}. If integer is positive,\n"
"the 1-bits in its binary representation are counted. If negative, the\n"
"0-bits in its two's-complement binary representation are counted. If 0,\n"
"0 is returned.\n\n"
"Example:\n"
"Return the number of bits in integer @var{n}. If integer is\n"
"positive, the 1-bits in its binary representation are counted.\n"
"If negative, the 0-bits in its two's-complement binary\n"
"representation are counted. If 0, 0 is returned.\n"
"\n"
"@lisp\n"
"(logcount #b10101010)\n"
" @result{} 4\n"
@ -1330,8 +1331,8 @@ static const char scm_ilentab[] = {
SCM_DEFINE (scm_integer_length, "integer-length", 1, 0, 0,
(SCM n),
"Returns the number of bits neccessary to represent @var{n}.\n\n"
"Example:\n"
"Return the number of bits neccessary to represent @var{n}.\n"
"\n"
"@lisp\n"
"(integer-length #b10101010)\n"
" @result{} 8\n"
@ -2863,7 +2864,7 @@ scm_istring2number (char *str, long len, long radix)
SCM_DEFINE (scm_string_to_number, "string->number", 1, 1, 0,
(SCM string, SCM radix),
"Returns a number of the maximally precise representation\n"
"Return a number of the maximally precise representation\n"
"expressed by the given @var{string}. @var{radix} must be an\n"
"exact integer, either 2, 8, 10, or 16. If supplied, @var{radix}\n"
"is a default radix that may be overridden by an explicit radix\n"
@ -4228,7 +4229,7 @@ scm_angle (SCM z)
SCM_DEFINE (scm_inexact_to_exact, "inexact->exact", 1, 0, 0,
(SCM z),
"Returns an exact number that is numerically closest to @var{z}.")
"Return an exact number that is numerically closest to @var{z}.")
#define FUNC_NAME s_scm_inexact_to_exact
{
if (SCM_INUMP (z)) {

20
libguile/objprop.c
View file

@ -68,14 +68,14 @@ 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 plist),
(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
{
SCM handle = scm_hashq_create_handle_x (scm_object_whash, obj, plist);
SCM_SETCDR (handle, plist);
return plist;
SCM handle = scm_hashq_create_handle_x (scm_object_whash, obj, alist);
SCM_SETCDR (handle, alist);
return alist;
}
#undef FUNC_NAME
@ -92,10 +92,10 @@ SCM_DEFINE (scm_object_property, "object-property", 2, 0, 0,
#undef FUNC_NAME
SCM_DEFINE (scm_set_object_property_x, "set-object-property!", 3, 0, 0,
(SCM obj, SCM key, SCM val),
(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} to\n"
"@var{value}.")
"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
{
SCM h;
@ -104,14 +104,14 @@ SCM_DEFINE (scm_set_object_property_x, "set-object-property!", 3, 0, 0,
SCM_DEFER_INTS;
assoc = scm_assq (key, SCM_CDR (h));
if (SCM_NIMP (assoc))
SCM_SETCDR (assoc, val);
SCM_SETCDR (assoc, value);
else
{
assoc = scm_acons (key, val, SCM_CDR (h));
assoc = scm_acons (key, value, SCM_CDR (h));
SCM_SETCDR (h, assoc);
}
SCM_ALLOW_INTS;
return val;
return value;
}
#undef FUNC_NAME

9
libguile/pairs.c
View file

@ -56,9 +56,9 @@
SCM_DEFINE (scm_cons, "cons", 2, 0, 0,
(SCM x, SCM y),
"Returns a newly allocated pair whose car is @var{x} and whose cdr is\n"
"@var{y}. The pair is guaranteed to be different (in the sense of\n"
"@code{eqv?}) from every previously existing object.")
"Return a newly allocated pair whose car is @var{x} and whose\n"
"cdr is @var{y}. The pair is guaranteed to be different (in the\n"
"sense of @code{eq?}) from every previously existing object.")
#define FUNC_NAME s_scm_cons
{
SCM z;
@ -90,7 +90,8 @@ scm_cons2 (SCM w, SCM x, SCM y)
SCM_DEFINE (scm_pair_p, "pair?", 1, 0, 0,
(SCM x),
"Returns @code{#t} if @var{x} is a pair; otherwise returns @code{#f}.")
"Return @code{#t} if @var{x} is a pair; otherwise return\n"
"@code{#f}.")
#define FUNC_NAME s_scm_pair_p
{
return SCM_BOOL (SCM_CONSP (x));

159
libguile/ports.c
View file

@ -230,20 +230,20 @@ scm_set_port_input_waiting (long tc, int (*input_waiting) (SCM))
SCM_DEFINE (scm_char_ready_p, "char-ready?", 0, 1, 0,
(SCM port),
"Returns @code{#t} if a character is ready on input @var{port} and\n"
"returns @code{#f} otherwise. If @code{char-ready?} returns @code{#t}\n"
"then the next @code{read-char} operation on @var{port} is\n"
"guaranteed not to hang. If @var{port} is a file port at end of\n"
"file then @code{char-ready?} returns @code{#t}.\n"
"@footnote{@code{char-ready?} exists to make it possible for a\n"
"program to accept characters from interactive ports without getting\n"
"stuck waiting for input. Any input editors associated with such ports\n"
"must make sure that characters whose existence has been asserted by\n"
"@code{char-ready?} cannot be rubbed out. If @code{char-ready?} were to\n"
"return @code{#f} at end of file, a port at end of file would be\n"
"indistinguishable from an interactive port that has no ready\n"
"characters.}")
(SCM port),
"Return @code{#t} if a character is ready on input @var{port}\n"
"and return @code{#f} otherwise. If @code{char-ready?} returns\n"
"@code{#t} then the next @code{read-char} operation on\n"
"@var{port} is guaranteed not to hang. If @var{port} is a file\n"
"port at end of file then @code{char-ready?} returns @code{#t}.\n"
"@footnote{@code{char-ready?} exists to make it possible for a\n"
"program to accept characters from interactive ports without\n"
"getting stuck waiting for input. Any input editors associated\n"
"with such ports must make sure that characters whose existence\n"
"has been asserted by @code{char-ready?} cannot be rubbed out.\n"
"If @code{char-ready?} were to return @code{#f} at end of file,\n"
"a port at end of file would be indistinguishable from an\n"
"interactive port that has no ready characters.}")
#define FUNC_NAME s_scm_char_ready_p
{
scm_port *pt;
@ -309,7 +309,7 @@ size_t scm_take_from_input_buffers (SCM port, char *dest, size_t read_len)
SCM_DEFINE (scm_drain_input, "drain-input", 1, 0, 0,
(SCM port),
"Drain @var{port}'s read buffers (including any pushed-back\n"
"characters) and returns the content as a single string.")
"characters) and return the content as a single string.")
#define FUNC_NAME s_scm_drain_input
{
SCM result;
@ -500,7 +500,7 @@ scm_remove_from_port_table (SCM port)
SCM_DEFINE (scm_pt_size, "pt-size", 0, 0, 0,
(),
"Returns the number of ports in the port table. @code{pt-size}\n"
"Return the number of ports in the port table. @code{pt-size}\n"
"is only included in @code{--enable-guile-debug} builds.")
#define FUNC_NAME s_scm_pt_size
{
@ -510,7 +510,7 @@ SCM_DEFINE (scm_pt_size, "pt-size", 0, 0, 0,
SCM_DEFINE (scm_pt_member, "pt-member", 1, 0, 0,
(SCM index),
"Returns the port at @var{index} in the port table.\n"
"Return the port at @var{index} in the port table.\n"
"@code{pt-member} is only included in\n"
"@code{--enable-guile-debug} builds.")
#define FUNC_NAME s_scm_pt_member
@ -553,7 +553,7 @@ scm_revealed_count (SCM port)
SCM_DEFINE (scm_port_revealed, "port-revealed", 1, 0, 0,
(SCM port),
"Returns the revealed count for @var{port}.")
"Return the revealed count for @var{port}.")
#define FUNC_NAME s_scm_port_revealed
{
port = SCM_COERCE_OUTPORT (port);
@ -606,10 +606,10 @@ scm_mode_bits (char *modes)
SCM_DEFINE (scm_port_mode, "port-mode", 1, 0, 0,
(SCM port),
"Returns the port modes associated with the open port @var{port}. These\n"
"will not necessarily be identical to the modes used when the port was\n"
"opened, since modes such as \"append\" which are used only during\n"
"port creation are not retained.")
"Return the port modes associated with the open port @var{port}.\n"
"These will not necessarily be identical to the modes used when\n"
"the port was opened, since modes such as \"append\" which are\n"
"used only during port creation are not retained.")
#define FUNC_NAME s_scm_port_mode
{
char modes[4];
@ -641,12 +641,12 @@ SCM_DEFINE (scm_port_mode, "port-mode", 1, 0, 0,
*/
SCM_DEFINE (scm_close_port, "close-port", 1, 0, 0,
(SCM port),
"Close the specified port object. Returns @code{#t} if it successfully\n"
"closes a port or @code{#f} if it was already\n"
"closed. An exception may be raised if an error occurs, for example\n"
"when flushing buffered output.\n"
"See also @ref{Ports and File Descriptors, close}, for a procedure\n"
"which can close file descriptors.")
"Close the specified port object. Return @code{#t} if it\n"
"successfully closes a port or @code{#f} if it was already\n"
"closed. An exception may be raised if an error occurs, for\n"
"example when flushing buffered output. See also @ref{Ports and\n"
"File Descriptors, close}, for a procedure which can close file\n"
"descriptors.")
#define FUNC_NAME s_scm_close_port
{
scm_sizet i;
@ -786,9 +786,9 @@ SCM_DEFINE (scm_close_all_ports_except, "close-all-ports-except", 0, 0, 1,
SCM_DEFINE (scm_input_port_p, "input-port?", 1, 0, 0,
(SCM x),
"Returns @code{#t} if @var{x} is an input port, otherwise returns\n"
"@code{#f}. Any object satisfying this predicate also satisfies\n"
"@code{port?}.")
"Return @code{#t} if @var{x} is an input port, otherwise return\n"
"@code{#f}. Any object satisfying this predicate also satisfies\n"
"@code{port?}.")
#define FUNC_NAME s_scm_input_port_p
{
if (SCM_IMP (x))
@ -799,9 +799,9 @@ SCM_DEFINE (scm_input_port_p, "input-port?", 1, 0, 0,
SCM_DEFINE (scm_output_port_p, "output-port?", 1, 0, 0,
(SCM x),
"Returns @code{#t} if @var{x} is an output port, otherwise returns\n"
"@code{#f}. Any object satisfying this predicate also satisfies\n"
"@code{port?}.")
"Return @code{#t} if @var{x} is an output port, otherwise return\n"
"@code{#f}. Any object satisfying this predicate also satisfies\n"
"@code{port?}.")
#define FUNC_NAME s_scm_output_port_p
{
if (SCM_IMP (x))
@ -814,7 +814,7 @@ SCM_DEFINE (scm_output_port_p, "output-port?", 1, 0, 0,
SCM_DEFINE (scm_port_p, "port?", 1, 0, 0,
(SCM x),
"Returns a boolean indicating whether @var{x} is a port.\n"
"Return a boolean indicating whether @var{x} is a port.\n"
"Equivalent to @code{(or (input-port? @var{x}) (output-port?\n"
"@var{x}))}.")
#define FUNC_NAME s_scm_port_p
@ -825,7 +825,8 @@ SCM_DEFINE (scm_port_p, "port?", 1, 0, 0,
SCM_DEFINE (scm_port_closed_p, "port-closed?", 1, 0, 0,
(SCM port),
"Returns @code{#t} if @var{port} is closed or @code{#f} if it is open.")
"Return @code{#t} if @var{port} is closed or @code{#f} if it is\n"
"open.")
#define FUNC_NAME s_scm_port_closed_p
{
SCM_VALIDATE_PORT (1,port);
@ -835,8 +836,8 @@ SCM_DEFINE (scm_port_closed_p, "port-closed?", 1, 0, 0,
SCM_DEFINE (scm_eof_object_p, "eof-object?", 1, 0, 0,
(SCM x),
"Returns @code{#t} if @var{x} is an end-of-file object; otherwise\n"
"returns @code{#f}.")
"Return @code{#t} if @var{x} is an end-of-file object; otherwise\n"
"return @code{#f}.")
#define FUNC_NAME s_scm_eof_object_p
{
return SCM_BOOL(SCM_EOF_OBJECT_P (x));
@ -884,9 +885,9 @@ SCM_DEFINE (scm_flush_all_ports, "flush-all-ports", 0, 0, 0,
SCM_DEFINE (scm_read_char, "read-char", 0, 1, 0,
(SCM port),
"Returns the next character available from @var{port}, updating\n"
"@var{port} to point to the following character. If no more\n"
"characters are available, an end-of-file object is returned.")
"Return the next character available from @var{port}, updating\n"
"@var{port} to point to the following character. If no more\n"
"characters are available, the end-of-file object is returned.")
#define FUNC_NAME s_scm_read_char
{
int c;
@ -1192,17 +1193,18 @@ scm_ungets (const char *s, int n, SCM port)
SCM_DEFINE (scm_peek_char, "peek-char", 0, 1, 0,
(SCM port),
"Returns the next character available from @var{port},\n"
"@emph{without} updating @var{port} to point to the following\n"
"character. If no more characters are available, an end-of-file object\n"
"is returned.@footnote{The value returned by a call to @code{peek-char}\n"
"is the same as the value that would have been returned by a call to\n"
"@code{read-char} on the same port. The only difference is that the very\n"
"next call to @code{read-char} or @code{peek-char} on that\n"
"@var{port} will return the value returned by the preceding call to\n"
"@code{peek-char}. In particular, a call to @code{peek-char} on an\n"
"interactive port will hang waiting for input whenever a call to\n"
"@code{read-char} would have hung.}")
"Return the next character available from @var{port},\n"
"@emph{without} updating @var{port} to point to the following\n"
"character. If no more characters are available, the\n"
"end-of-file object is returned.@footnote{The value returned by\n"
"a call to @code{peek-char} is the same as the value that would\n"
"have been returned by a call to @code{read-char} on the same\n"
"port. The only difference is that the very next call to\n"
"@code{read-char} or @code{peek-char} on that @var{port} will\n"
"return the value returned by the preceding call to\n"
"@code{peek-char}. In particular, a call to @code{peek-char} on\n"
"an interactive port will hang waiting for input whenever a call\n"
"to @code{read-char} would have hung.}")
#define FUNC_NAME s_scm_peek_char
{
int c;
@ -1262,11 +1264,13 @@ SCM_DEFINE (scm_unread_string, "unread-string", 2, 0, 0,
#undef FUNC_NAME
SCM_DEFINE (scm_seek, "seek", 3, 0, 0,
(SCM object, SCM offset, SCM whence),
"Sets the current position of @var{fd/port} to the integer @var{offset},\n"
"which is interpreted according to the value of @var{whence}.\n\n"
"One of the following variables should be supplied\n"
"for @var{whence}:\n"
(SCM fd_port, SCM offset, SCM whence),
"Sets the current position of @var{fd/port} to the integer\n"
"@var{offset}, which is interpreted according to the value of\n"
"@var{whence}.\n"
"\n"
"One of the following variables should be supplied for\n"
"@var{whence}:\n"
"@defvar SEEK_SET\n"
"Seek from the beginning of the file.\n"
"@end defvar\n"
@ -1275,40 +1279,41 @@ SCM_DEFINE (scm_seek, "seek", 3, 0, 0,
"@end defvar\n"
"@defvar SEEK_END\n"
"Seek from the end of the file.\n"
"@end defvar\n\n"
"If @var{fd/port} is a file descriptor, the underlying system call is\n"
"@code{lseek}. @var{port} may be a string port.\n\n"
"The value returned is the new position in the file. This means that\n"
"the current position of a port can be obtained using:\n"
"@smalllisp\n"
"@end defvar\n"
"If @var{fd/port} is a file descriptor, the underlying system\n"
"call is @code{lseek}. @var{port} may be a string port.\n"
"\n"
"The value returned is the new position in the file. This means\n"
"that the current position of a port can be obtained using:\n"
"@lisp\n"
"(seek port 0 SEEK_CUR)\n"
"@end smalllisp")
"@end lisp")
#define FUNC_NAME s_scm_seek
{
off_t off;
off_t rv;
int how;
object = SCM_COERCE_OUTPORT (object);
fd_port = SCM_COERCE_OUTPORT (fd_port);
off = SCM_NUM2LONG (2, offset);
SCM_VALIDATE_INUM_COPY (3, whence, how);
if (how != SEEK_SET && how != SEEK_CUR && how != SEEK_END)
SCM_OUT_OF_RANGE (3, whence);
if (SCM_OPPORTP (object))
if (SCM_OPPORTP (fd_port))
{
scm_ptob_descriptor *ptob = scm_ptobs + SCM_PTOBNUM (object);
scm_ptob_descriptor *ptob = scm_ptobs + SCM_PTOBNUM (fd_port);
if (!ptob->seek)
SCM_MISC_ERROR ("port is not seekable",
scm_cons (object, SCM_EOL));
scm_cons (fd_port, SCM_EOL));
else
rv = ptob->seek (object, off, how);
rv = ptob->seek (fd_port, off, how);
}
else /* file descriptor?. */
{
SCM_VALIDATE_INUM (1,object);
rv = lseek (SCM_INUM (object), off, how);
SCM_VALIDATE_INUM (1,fd_port);
rv = lseek (SCM_INUM (fd_port), off, how);
if (rv == -1)
SCM_SYSERROR;
}
@ -1318,12 +1323,12 @@ SCM_DEFINE (scm_seek, "seek", 3, 0, 0,
SCM_DEFINE (scm_truncate_file, "truncate-file", 1, 1, 0,
(SCM object, SCM length),
"Truncates the object referred to by @var{obj} to at most @var{size} bytes.\n"
"@var{obj} can be a string containing a file name or an integer file\n"
"descriptor or a port. @var{size} may be omitted if @var{obj} is not\n"
"a file name, in which case the truncation occurs at the current port.\n"
"position.\n\n"
"The return value is unspecified.")
"Truncates the object referred to by @var{object} to at most\n"
"@var{length} bytes. @var{object} can be a string containing a\n"
"file name or an integer file descriptor or a port.\n"
"@var{length} may be omitted if @var{object} is not a file name,\n"
"in which case the truncation occurs at the current port.\n"
"position. The return value is unspecified.")
#define FUNC_NAME s_scm_truncate_file
{
int rv;

183
libguile/posix.c
View file

@ -186,19 +186,19 @@ SCM_SYMBOL (sym_write_pipe, "write pipe");
SCM_DEFINE (scm_pipe, "pipe", 0, 0, 0,
(),
"Returns a newly created pipe: a pair of ports which are linked\n"
"together on the local machine. The CAR is the input port and\n"
"the CDR is the output port. Data written (and flushed) to the\n"
"output port can be read from the input port.\n"
"Pipes are commonly used for communication with a newly\n"
"forked child process. The need to flush the output port\n"
"can be avoided by making it unbuffered using @code{setvbuf}.\n\n"
"Writes occur atomically provided the size of the data in\n"
"bytes is not greater than the value of @code{PIPE_BUF}\n"
"Note that the output port is likely to block if too much data\n"
"(typically equal to @code{PIPE_BUF}) has been written but not\n"
"yet read from the input port\n"
)
"Return a newly created pipe: a pair of ports which are linked\n"
"together on the local machine. The @emph{car} is the input\n"
"port and the @emph{cdr} is the output port. Data written (and\n"
"flushed) to the output port can be read from the input port.\n"
"Pipes are commonly used for communication with a newly forked\n"
"child process. The need to flush the output port can be\n"
"avoided by making it unbuffered using @code{setvbuf}.\n"
"\n"
"Writes occur atomically provided the size of the data in bytes\n"
"is not greater than the value of @code{PIPE_BUF}. Note that\n"
"the output port is likely to block if too much data (typically\n"
"equal to @code{PIPE_BUF}) has been written but not yet read\n"
"from the input port.")
#define FUNC_NAME s_scm_pipe
{
int fd[2], rv;
@ -218,7 +218,8 @@ SCM_DEFINE (scm_pipe, "pipe", 0, 0, 0,
#ifdef HAVE_GETGROUPS
SCM_DEFINE (scm_getgroups, "getgroups", 0, 0, 0,
(),
"Returns a vector of integers representing the current supplimentary group IDs.")
"Return a vector of integers representing the current\n"
"supplimentary group IDs.")
#define FUNC_NAME s_scm_getgroups
{
SCM ans;
@ -473,9 +474,9 @@ SCM_DEFINE (scm_waitpid, "waitpid", 1, 1, 0,
SCM_DEFINE (scm_status_exit_val, "status:exit-val", 1, 0, 0,
(SCM status),
"Returns the exit status value, as would be\n"
"set if a process ended normally through a\n"
"call to @code{exit} or @code{_exit}, if any, otherwise @code{#f}.")
"Return the exit status value, as would be set if a process\n"
"ended normally through a call to @code{exit} or @code{_exit},\n"
"if any, otherwise @code{#f}.")
#define FUNC_NAME s_scm_status_exit_val
{
int lstatus;
@ -494,8 +495,8 @@ SCM_DEFINE (scm_status_exit_val, "status:exit-val", 1, 0, 0,
SCM_DEFINE (scm_status_term_sig, "status:term-sig", 1, 0, 0,
(SCM status),
"Returns the signal number which terminated the\n"
"process, if any, otherwise @code{#f}.")
"Return the signal number which terminated the process, if any,\n"
"otherwise @code{#f}.")
#define FUNC_NAME s_scm_status_term_sig
{
int lstatus;
@ -512,8 +513,8 @@ SCM_DEFINE (scm_status_term_sig, "status:term-sig", 1, 0, 0,
SCM_DEFINE (scm_status_stop_sig, "status:stop-sig", 1, 0, 0,
(SCM status),
"Returns the signal number which stopped the\n"
"process, if any, otherwise @code{#f}.")
"Return the signal number which stopped the process, if any,\n"
"otherwise @code{#f}.")
#define FUNC_NAME s_scm_status_stop_sig
{
int lstatus;
@ -530,7 +531,8 @@ SCM_DEFINE (scm_status_stop_sig, "status:stop-sig", 1, 0, 0,
SCM_DEFINE (scm_getppid, "getppid", 0, 0, 0,
(),
"Returns an integer representing the process ID of the parent process.")
"Return an integer representing the process ID of the parent\n"
"process.")
#define FUNC_NAME s_scm_getppid
{
return SCM_MAKINUM (0L + getppid ());
@ -541,7 +543,7 @@ SCM_DEFINE (scm_getppid, "getppid", 0, 0, 0,
SCM_DEFINE (scm_getuid, "getuid", 0, 0, 0,
(),
"Returns an integer representing the current real user ID.")
"Return an integer representing the current real user ID.")
#define FUNC_NAME s_scm_getuid
{
return SCM_MAKINUM (0L + getuid ());
@ -552,7 +554,7 @@ SCM_DEFINE (scm_getuid, "getuid", 0, 0, 0,
SCM_DEFINE (scm_getgid, "getgid", 0, 0, 0,
(),
"Returns an integer representing the current real group ID.")
"Return an integer representing the current real group ID.")
#define FUNC_NAME s_scm_getgid
{
return SCM_MAKINUM (0L + getgid ());
@ -563,10 +565,10 @@ SCM_DEFINE (scm_getgid, "getgid", 0, 0, 0,
SCM_DEFINE (scm_geteuid, "geteuid", 0, 0, 0,
(),
"Returns an integer representing the current effective user ID.\n"
"Return an integer representing the current effective user ID.\n"
"If the system does not support effective IDs, then the real ID\n"
"is returned. @code{(feature? 'EIDs)} reports whether the system\n"
"supports effective IDs.")
"is returned. @code{(feature? 'EIDs)} reports whether the\n"
"system supports effective IDs.")
#define FUNC_NAME s_scm_geteuid
{
#ifdef HAVE_GETEUID
@ -581,10 +583,10 @@ SCM_DEFINE (scm_geteuid, "geteuid", 0, 0, 0,
SCM_DEFINE (scm_getegid, "getegid", 0, 0, 0,
(),
"Returns an integer representing the current effective group ID.\n"
"Return an integer representing the current effective group ID.\n"
"If the system does not support effective IDs, then the real ID\n"
"is returned. @code{(feature? 'EIDs)} reports whether the system\n"
"supports effective IDs.")
"is returned. @code{(feature? 'EIDs)} reports whether the\n"
"system supports effective IDs.")
#define FUNC_NAME s_scm_getegid
{
#ifdef HAVE_GETEUID
@ -675,7 +677,7 @@ SCM_DEFINE (scm_setegid, "setegid", 1, 0, 0,
SCM_DEFINE (scm_getpgrp, "getpgrp", 0, 0, 0,
(),
"Returns an integer representing the current process group ID.\n"
"Return an integer representing the current process group ID.\n"
"This is the POSIX definition, not BSD.")
#define FUNC_NAME s_scm_getpgrp
{
@ -724,8 +726,8 @@ SCM_DEFINE (scm_setsid, "setsid", 0, 0, 0,
SCM_DEFINE (scm_ttyname, "ttyname", 1, 0, 0,
(SCM port),
"Returns a string with the name of the serial terminal device underlying\n"
"@var{port}.")
"Return a string with the name of the serial terminal device\n"
"underlying @var{port}.")
#define FUNC_NAME s_scm_ttyname
{
char *ans;
@ -747,8 +749,8 @@ SCM_DEFINE (scm_ttyname, "ttyname", 1, 0, 0,
#ifdef HAVE_CTERMID
SCM_DEFINE (scm_ctermid, "ctermid", 0, 0, 0,
(),
"Returns a string containing the file name of the controlling terminal\n"
"for the current process.")
"Return a string containing the file name of the controlling\n"
"terminal for the current process.")
#define FUNC_NAME s_scm_ctermid
{
char *result = ctermid (NULL);
@ -762,9 +764,10 @@ SCM_DEFINE (scm_ctermid, "ctermid", 0, 0, 0,
#ifdef HAVE_TCGETPGRP
SCM_DEFINE (scm_tcgetpgrp, "tcgetpgrp", 1, 0, 0,
(SCM port),
"Returns the process group ID of the foreground\n"
"process group associated with the terminal open on the file descriptor\n"
"underlying @var{port}.\n\n"
"Return the process group ID of the foreground process group\n"
"associated with the terminal open on the file descriptor\n"
"underlying @var{port}.\n"
"\n"
"If there is no foreground process group, the return value is a\n"
"number greater than 1 that does not match the process group ID\n"
"of any existing process group. This can happen if all of the\n"
@ -964,8 +967,8 @@ SCM_DEFINE (scm_fork, "primitive-fork", 0, 0, 0,
#ifdef HAVE_UNAME
SCM_DEFINE (scm_uname, "uname", 0, 0, 0,
(),
"Returns an object with some information about the computer system the\n"
"program is running on.")
"Return an object with some information about the computer\n"
"system the program is running on.")
#define FUNC_NAME s_scm_uname
{
struct utsname buf;
@ -989,12 +992,13 @@ SCM_DEFINE (scm_uname, "uname", 0, 0, 0,
SCM_DEFINE (scm_environ, "environ", 0, 1, 0,
(SCM env),
"If @var{env} is omitted, returns the current environment as a list of strings.\n"
"Otherwise it sets the current environment, which is also the\n"
"default environment for child processes, to the supplied list of strings.\n"
"Each member of @var{env} should be of the form\n"
"@code{NAME=VALUE} and values of @code{NAME} should not be duplicated.\n"
"If @var{env} is supplied then the return value is unspecified.")
"If @var{env} is omitted, return the current environment (in the\n"
"Unix sense) as a list of strings. Otherwise set the current\n"
"environment, which is also the default environment for child\n"
"processes, to the supplied list of strings. Each member of\n"
"@var{env} should be of the form @code{NAME=VALUE} and values of\n"
"@code{NAME} should not be duplicated. If @var{env} is supplied\n"
"then the return value is unspecified.")
#define FUNC_NAME s_scm_environ
{
if (SCM_UNBNDP (env))
@ -1028,11 +1032,11 @@ SCM_DEFINE (scm_environ, "environ", 0, 1, 0,
SCM_DEFINE (scm_tmpnam, "tmpnam", 0, 0, 0,
(),
"tmpnam returns a name in the file system that does not match\n"
"any existing file. However there is no guarantee that\n"
"another process will not create the file after tmpnam\n"
"is called. Care should be taken if opening the file,\n"
"e.g., use the O_EXCL open flag or use @code{mkstemp!} instead.")
"Return a name in the file system that does not match any\n"
"existing file. However there is no guarantee that another\n"
"process will not create the file after @code{tmpnam} is called.\n"
"Care should be taken if opening the file, e.g., use the\n"
"@code{O_EXCL} open flag or use @code{mkstemp!} instead.")
#define FUNC_NAME s_scm_tmpnam
{
char name[L_tmpnam];
@ -1050,12 +1054,11 @@ SCM_DEFINE (scm_tmpnam, "tmpnam", 0, 0, 0,
SCM_DEFINE (scm_mkstemp, "mkstemp!", 1, 0, 0,
(SCM tmpl),
"mkstemp creates a new unique file in the file system and\n"
"returns a new buffered port open for reading and writing to\n"
"the file. @var{tmpl} is a string specifying where the\n"
"file should be created: it must end with @code{XXXXXX}\n"
"and will be changed in place to return the name of the\n"
"temporary file.\n")
"Create a new unique file in the file system and returns a new\n"
"buffered port open for reading and writing to the file.\n"
"@var{tmpl} is a string specifying where the file should be\n"
"created: it must end with @code{XXXXXX} and will be changed in\n"
"place to return the name of the temporary file.")
#define FUNC_NAME s_scm_mkstemp
{
char *c_tmpl;
@ -1072,18 +1075,16 @@ SCM_DEFINE (scm_mkstemp, "mkstemp!", 1, 0, 0,
SCM_DEFINE (scm_utime, "utime", 1, 2, 0,
(SCM pathname, SCM actime, SCM modtime),
"@code{utime} sets the access and modification times for\n"
"the file named by @var{path}. If @var{actime} or @var{modtime}\n"
"is not supplied, then the current time is used.\n"
"@var{actime} and @var{modtime}\n"
"must be integer time values as returned by the @code{current-time}\n"
"procedure.\n\n"
"E.g.,\n\n"
"@smalllisp\n"
"@code{utime} sets the access and modification times for the\n"
"file named by @var{path}. If @var{actime} or @var{modtime} is\n"
"not supplied, then the current time is used. @var{actime} and\n"
"@var{modtime} must be integer time values as returned by the\n"
"@code{current-time} procedure.\n"
"@lisp\n"
"(utime \"foo\" (- (current-time) 3600))\n"
"@end smalllisp\n\n"
"will set the access time to one hour in the past and the modification\n"
"time to the current time.")
"@end lisp\n"
"will set the access time to one hour in the past and the\n"
"modification time to the current time.")
#define FUNC_NAME s_scm_utime
{
int rv;
@ -1110,17 +1111,17 @@ SCM_DEFINE (scm_utime, "utime", 1, 2, 0,
SCM_DEFINE (scm_access, "access?", 2, 0, 0,
(SCM path, SCM how),
"Returns @code{#t} if @var{path} corresponds to an existing\n"
"file and the current process\n"
"has the type of access specified by @var{how}, otherwise \n"
"@code{#f}.\n"
"@var{how} should be specified\n"
"using the values of the variables listed below. Multiple values can\n"
"be combined using a bitwise or, in which case @code{#t} will only\n"
"be returned if all accesses are granted.\n\n"
"Permissions are checked using the real id of the current process,\n"
"not the effective id, although it's the effective id which determines\n"
"whether the access would actually be granted.\n\n"
"Return @code{#t} if @var{path} corresponds to an existing file\n"
"and the current process has the type of access specified by\n"
"@var{how}, otherwise @code{#f}. @var{how} should be specified\n"
"using the values of the variables listed below. Multiple\n"
"values can be combined using a bitwise or, in which case\n"
"@code{#t} will only be returned if all accesses are granted.\n"
"\n"
"Permissions are checked using the real id of the current\n"
"process, not the effective id, although it's the effective id\n"
"which determines whether the access would actually be granted.\n"
"\n"
"@defvar R_OK\n"
"test for read permission.\n"
"@end defvar\n"
@ -1147,7 +1148,7 @@ SCM_DEFINE (scm_access, "access?", 2, 0, 0,
SCM_DEFINE (scm_getpid, "getpid", 0, 0, 0,
(),
"Returns an integer representing the current process ID.")
"Return an integer representing the current process ID.")
#define FUNC_NAME s_scm_getpid
{
return SCM_MAKINUM ((unsigned long) getpid ());
@ -1187,15 +1188,15 @@ SCM_DEFINE (scm_putenv, "putenv", 1, 0, 0,
#ifdef HAVE_SETLOCALE
SCM_DEFINE (scm_setlocale, "setlocale", 1, 1, 0,
(SCM category, SCM locale),
"If @var{locale} is omitted, returns the current value of the specified\n"
"locale category \n"
"as a system-dependent string.\n"
"@var{category} should be specified using the values @code{LC_COLLATE},\n"
"@code{LC_ALL} etc.\n\n"
"Otherwise the specified locale category is set to\n"
"the string @var{locale}\n"
"and the new value is returned as a system-dependent string. If @var{locale}\n"
"is an empty string, the locale will be set using envirionment variables.")
"If @var{locale} is omitted, return the current value of the\n"
"specified locale category as a system-dependent string.\n"
"@var{category} should be specified using the values\n"
"@code{LC_COLLATE}, @code{LC_ALL} etc.\n"
"\n"
"Otherwise the specified locale category is set to the string\n"
"@var{locale} and the new value is returned as a\n"
"system-dependent string. If @var{locale} is an empty string,\n"
"the locale will be set using envirionment variables.")
#define FUNC_NAME s_scm_setlocale
{
char *clocale;
@ -1233,9 +1234,9 @@ SCM_DEFINE (scm_mknod, "mknod", 4, 0, 0,
"to. Its exact interpretation depends on the kind of special file\n"
"being created.\n\n"
"E.g.,\n"
"@example\n"
"@lisp\n"
"(mknod \"/dev/fd0\" 'block-special #o660 (+ (* 2 256) 2))\n"
"@end example\n\n"
"@end lisp\n\n"
"The return value is unspecified.")
#define FUNC_NAME s_scm_mknod
{

19
libguile/ramap.c
View file

@ -1686,19 +1686,19 @@ SCM_DEFINE (scm_array_index_map_x, "array-index-map!", 2, 0, 0,
"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"
"@example\n"
"@lisp\n"
"(define (array-indexes array)\n"
" (let ((ra (apply make-array #f (array-shape array))))\n"
" (array-index-map! ra (lambda x x))\n"
" ra))\n"
"@end example\n"
"@end lisp\n"
"Another example:\n"
"@example\n"
"@lisp\n"
"(define (apl:index-generator n)\n"
" (let ((v (make-uniform-vector n 1)))\n"
" (array-index-map! v (lambda (i) i))\n"
" v))\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_array_index_map_x
{
scm_sizet i;
@ -1979,11 +1979,12 @@ scm_raequal (SCM ra0, SCM ra1)
/* GJB:FIXME:: Why not use SCM_DEFINE1 for array-equal? */
SCM_DEFINE1 (scm_array_equal_p, "array-equal?", scm_tc7_rpsubr,
(SCM ra0, SCM ra1),
"Returns @code{#t} iff all arguments are arrays with the same shape, the\n"
"same type, and have corresponding elements which are either\n"
"@code{equal?} or @code{array-equal?}. This function differs from\n"
"@code{equal?} in that a one dimensional shared array may be\n"
"@var{array-equal?} but not @var{equal?} to a vector or uniform vector.")
"Return @code{#t} iff all arguments are arrays with the same\n"
"shape, the same type, and have corresponding elements which are\n"
"either @code{equal?} or @code{array-equal?}. This function\n"
"differs from @code{equal?} in that a one dimensional shared\n"
"array may be @var{array-equal?} but not @var{equal?} to a\n"
"vector or uniform vector.")
#define FUNC_NAME s_scm_array_equal_p
{
}

16
libguile/random.c
View file

@ -415,7 +415,8 @@ SCM_DEFINE (scm_seed_to_random_state, "seed->random-state", 1, 0, 0,
SCM_DEFINE (scm_random_uniform, "random:uniform", 0, 1, 0,
(SCM state),
"Returns a uniformly distributed inexact real random number in [0,1).")
"Return a uniformly distributed inexact real random number in\n"
"[0,1).")
#define FUNC_NAME s_scm_random_uniform
{
if (SCM_UNBNDP (state))
@ -427,10 +428,10 @@ SCM_DEFINE (scm_random_uniform, "random:uniform", 0, 1, 0,
SCM_DEFINE (scm_random_normal, "random:normal", 0, 1, 0,
(SCM state),
"Returns an inexact real in a normal distribution.\n"
"The distribution used has mean 0 and standard deviation 1.\n"
"For a normal distribution with mean m and standard deviation\n"
"d use @code{(+ m (* d (random:normal)))}.")
"Return an inexact real in a normal distribution. The\n"
"distribution used has mean 0 and standard deviation 1. For a\n"
"normal distribution with mean m and standard deviation d use\n"
"@code{(+ m (* d (random:normal)))}.")
#define FUNC_NAME s_scm_random_normal
{
if (SCM_UNBNDP (state))
@ -550,8 +551,9 @@ SCM_DEFINE (scm_random_normal_vector_x, "random:normal-vector!", 1, 1, 0,
SCM_DEFINE (scm_random_exp, "random:exp", 0, 1, 0,
(SCM state),
"Returns an inexact real in an exponential distribution with mean 1.\n"
"For an exponential distribution with mean u use (* u (random:exp)).")
"Return an inexact real in an exponential distribution with mean\n"
"1. For an exponential distribution with mean u use (* u\n"
"(random:exp)).")
#define FUNC_NAME s_scm_random_exp
{
if (SCM_UNBNDP (state))

10
libguile/rdelim.c
View file

@ -268,13 +268,13 @@ SCM_DEFINE (scm_read_line, "%read-line", 0, 1, 0,
SCM_DEFINE (scm_write_line, "write-line", 1, 1, 0,
(SCM obj, SCM port),
"Display @var{obj} and a newline character to @var{port}. If @var{port}\n"
"is not specified, @code{(current-output-port)} is used. This function\n"
"is equivalent to:\n\n"
"@smalllisp\n"
"Display @var{obj} and a newline character to @var{port}. If\n"
"@var{port} is not specified, @code{(current-output-port)} is\n"
"used. This function is equivalent to:\n"
"@lisp\n"
"(display obj [port])\n"
"(newline [port])\n"
"@end smalllisp")
"@end lisp")
#define FUNC_NAME s_scm_write_line
{
scm_display (obj, port);

74
libguile/regex-posix.c
View file

@ -134,49 +134,54 @@ scm_regexp_error_msg (int regerrno, regex_t *rx)
}
SCM_DEFINE (scm_regexp_p, "regexp?", 1, 0, 0,
(SCM x),
"Return @code{#t} if @var{obj} is a compiled regular expression, or\n"
"@code{#f} otherwise.")
(SCM obj),
"Return @code{#t} if @var{obj} is a compiled regular expression,\n"
"or @code{#f} otherwise.")
#define FUNC_NAME s_scm_regexp_p
{
return SCM_BOOL(SCM_RGXP (x));
return SCM_BOOL(SCM_RGXP (obj));
}
#undef FUNC_NAME
SCM_DEFINE (scm_make_regexp, "make-regexp", 1, 0, 1,
(SCM pat, SCM flags),
"Compile the regular expression described by @var{str}, and return the\n"
"compiled regexp structure. If @var{str} does not describe a legal\n"
"regular expression, @code{make-regexp} throws a\n"
"@code{regular-expression-syntax} error.\n\n"
"The @var{flag} arguments change the behavior of the compiled regexp.\n"
"The following flags may be supplied:\n\n"
"Compile the regular expression described by @var{pat}, and\n"
"return the compiled regexp structure. If @var{pat} does not\n"
"describe a legal regular expression, @code{make-regexp} throws\n"
"a @code{regular-expression-syntax} error.\n"
"\n"
"The @var{flags} arguments change the behavior of the compiled\n"
"regular expression. The following flags may be supplied:\n"
"\n"
"@table @code\n"
"@item regexp/icase\n"
"Consider uppercase and lowercase letters to be the same when matching.\n\n"
"Consider uppercase and lowercase letters to be the same when\n"
"matching.\n"
"@item regexp/newline\n"
"If a newline appears in the target string, then permit the @samp{^} and\n"
"@samp{$} operators to match immediately after or immediately before the\n"
"newline, respectively. Also, the @samp{.} and @samp{[^...]} operators\n"
"will never match a newline character. The intent of this flag is to\n"
"treat the target string as a buffer containing many lines of text, and\n"
"the regular expression as a pattern that may match a single one of those\n"
"lines.\n\n"
"If a newline appears in the target string, then permit the\n"
"@samp{^} and @samp{$} operators to match immediately after or\n"
"immediately before the newline, respectively. Also, the\n"
"@samp{.} and @samp{[^...]} operators will never match a newline\n"
"character. The intent of this flag is to treat the target\n"
"string as a buffer containing many lines of text, and the\n"
"regular expression as a pattern that may match a single one of\n"
"those lines.\n"
"@item regexp/basic\n"
"Compile a basic (``obsolete'') regexp instead of the extended\n"
"(``modern'') regexps that are the default. Basic regexps do not\n"
"consider @samp{|}, @samp{+} or @samp{?} to be special characters, and\n"
"require the @samp{@{...@}} and @samp{(...)} metacharacters to be\n"
"backslash-escaped (@pxref{Backslash Escapes}). There are several other\n"
"differences between basic and extended regular expressions, but these\n"
"are the most significant.\n\n"
"(``modern'') regexps that are the default. Basic regexps do\n"
"not consider @samp{|}, @samp{+} or @samp{?} to be special\n"
"characters, and require the @samp{@{...@}} and @samp{(...)}\n"
"metacharacters to be backslash-escaped (@pxref{Backslash\n"
"Escapes}). There are several other differences between basic\n"
"and extended regular expressions, but these are the most\n"
"significant.\n"
"@item regexp/extended\n"
"Compile an extended regular expression rather than a basic regexp. This\n"
"is the default behavior; this flag will not usually be needed. If a\n"
"call to @code{make-regexp} includes both @code{regexp/basic} and\n"
"@code{regexp/extended} flags, the one which comes last will override\n"
"the earlier one.\n"
"@end table\n")
"Compile an extended regular expression rather than a basic\n"
"regexp. This is the default behavior; this flag will not\n"
"usually be needed. If a call to @code{make-regexp} includes\n"
"both @code{regexp/basic} and @code{regexp/extended} flags, the\n"
"one which comes last will override the earlier one.\n"
"@end table")
#define FUNC_NAME s_scm_make_regexp
{
SCM flag;
@ -220,10 +225,11 @@ SCM_DEFINE (scm_make_regexp, "make-regexp", 1, 0, 1,
SCM_DEFINE (scm_regexp_exec, "regexp-exec", 2, 2, 0,
(SCM rx, SCM str, SCM start, SCM flags),
"Match the compiled regular expression @var{regexp} against @code{str}.\n"
"If the optional integer @var{start} argument is provided, begin matching\n"
"from that position in the string. Return a match structure describing\n"
"the results of the match, or @code{#f} if no match could be found.")
"Match the compiled regular expression @var{rx} against\n"
"@code{str}. If the optional integer @var{start} argument is\n"
"provided, begin matching from that position in the string.\n"
"Return a match structure describing the results of the match,\n"
"or @code{#f} if no match could be found.")
#define FUNC_NAME s_scm_regexp_exec
{
int status, nmatches, offset;

4
libguile/root.c
View file

@ -334,7 +334,7 @@ SCM_DEFINE (scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
"Before calling @var{thunk}, the dynamic-wind chain is un-wound back to\n"
"the root and a new chain started for @var{thunk}. Therefore, this call\n"
"may not do what you expect:\n\n"
"@example\n"
"@lisp\n"
";; Almost certainly a bug:\n"
"(with-output-to-port\n"
" some-port\n\n"
@ -344,7 +344,7 @@ SCM_DEFINE (scm_call_with_dynamic_root, "call-with-dynamic-root", 2, 0, 0,
" (display 'fnord)\n"
" (newline))\n"
" (lambda (errcode) errcode))))\n"
"@end example\n\n"
"@end lisp\n\n"
"The problem is, on what port will @samp{fnord} be displayed? You\n"
"might expect that because of the @code{with-output-to-port} that\n"
"it will be displayed on the port bound to @code{some-port}. But it\n"

12
libguile/simpos.c
View file

@ -68,11 +68,13 @@ extern int system();
#ifdef HAVE_SYSTEM
SCM_DEFINE (scm_system, "system", 0, 1, 0,
(SCM cmd),
"Executes @var{cmd} using the operating system's \"command processor\".\n"
"Under Unix this is usually the default shell @code{sh}. The value\n"
"returned is @var{cmd}'s exit status as returned by @code{waitpid}, which\n"
"can be interpreted using the functions above.\n\n"
"If @code{system} is called without arguments, it returns a boolean\n"
"Execute @var{cmd} using the operating system's \"command\n"
"processor\". Under Unix this is usually the default shell\n"
"@code{sh}. The value returned is @var{cmd}'s exit status as\n"
"returned by @code{waitpid}, which can be interpreted using the\n"
"functions above.\n"
"\n"
"If @code{system} is called without arguments, return a boolean\n"
"indicating whether the command processor is available.")
#define FUNC_NAME s_scm_system
{

124
libguile/socket.c
View file

@ -84,9 +84,9 @@
SCM_DEFINE (scm_htons, "htons", 1, 0, 0,
(SCM in),
"Returns a new integer from @var{value} by converting from host to\n"
"network order. @var{value} must be within the range of a C unsigned\n"
"short integer.")
"Return a new integer from @var{value} by converting from host\n"
"to network order. @var{value} must be within the range of a C\n"
"unsigned short integer.")
#define FUNC_NAME s_scm_htons
{
unsigned short c_in;
@ -101,9 +101,9 @@ SCM_DEFINE (scm_htons, "htons", 1, 0, 0,
SCM_DEFINE (scm_ntohs, "ntohs", 1, 0, 0,
(SCM in),
"Returns a new integer from @var{value} by converting from network to\n"
"host order. @var{value} must be within the range of a C unsigned short\n"
"integer.")
"Return a new integer from @var{value} by converting from\n"
"network to host order. @var{value} must be within the range of\n"
"a C unsigned short integer.")
#define FUNC_NAME s_scm_ntohs
{
unsigned short c_in;
@ -118,9 +118,9 @@ SCM_DEFINE (scm_ntohs, "ntohs", 1, 0, 0,
SCM_DEFINE (scm_htonl, "htonl", 1, 0, 0,
(SCM in),
"Returns a new integer from @var{value} by converting from host to\n"
"network order. @var{value} must be within the range of a C unsigned\n"
"long integer.")
"Return a new integer from @var{value} by converting from host\n"
"to network order. @var{value} must be within the range of a C\n"
"unsigned long integer.")
#define FUNC_NAME s_scm_htonl
{
unsigned long c_in = SCM_NUM2ULONG (1,in);
@ -130,9 +130,9 @@ SCM_DEFINE (scm_htonl, "htonl", 1, 0, 0,
SCM_DEFINE (scm_ntohl, "ntohl", 1, 0, 0,
(SCM in),
"Returns a new integer from @var{value} by converting from network to\n"
"host order. @var{value} must be within the range of a C unsigned\n"
"long integer.")
"Return a new integer from @var{value} by converting from\n"
"network to host order. @var{value} must be within the range of\n"
"a C unsigned long integer.")
#define FUNC_NAME s_scm_ntohl
{
unsigned long c_in = SCM_NUM2ULONG (1,in);
@ -146,16 +146,19 @@ SCM_SYMBOL (sym_socket, "socket");
SCM_DEFINE (scm_socket, "socket", 3, 0, 0,
(SCM family, SCM style, SCM proto),
"Returns a new socket port of the type specified by @var{family}, @var{style}\n"
"and @var{protocol}. All three parameters are integers. Typical values\n"
"for @var{family} are the values of @code{AF_UNIX}\n"
"and @code{AF_INET}. Typical values for @var{style} are\n"
"the values of @code{SOCK_STREAM}, @code{SOCK_DGRAM} and @code{SOCK_RAW}.\n\n"
"Return a new socket port of the type specified by @var{family},\n"
"@var{style} and @var{protocol}. All three parameters are\n"
"integers. Typical values for @var{family} are the values of\n"
"@code{AF_UNIX} and @code{AF_INET}. Typical values for\n"
"@var{style} are the values of @code{SOCK_STREAM},\n"
"@code{SOCK_DGRAM} and @code{SOCK_RAW}.\n"
"\n"
"@var{protocol} can be obtained from a protocol name using\n"
"@code{getprotobyname}. A value of\n"
"zero specifies the default protocol, which is usually right.\n\n"
"A single socket port cannot by used for communication until\n"
"it has been connected to another socket.")
"@code{getprotobyname}. A value of zero specifies the default\n"
"protocol, which is usually right.\n"
"\n"
"A single socket port cannot by used for communication until it\n"
"has been connected to another socket.")
#define FUNC_NAME s_scm_socket
{
int fd;
@ -173,11 +176,11 @@ SCM_DEFINE (scm_socket, "socket", 3, 0, 0,
#ifdef HAVE_SOCKETPAIR
SCM_DEFINE (scm_socketpair, "socketpair", 3, 0, 0,
(SCM family, SCM style, SCM proto),
"Returns a pair of connected (but unnamed) socket ports of the type specified\n"
"by @var{family}, @var{style} and @var{protocol}.\n"
"Many systems support only\n"
"socket pairs of the @code{AF_UNIX} family. Zero is likely to be\n"
"the only meaningful value for @var{protocol}.")
"Return a pair of connected (but unnamed) socket ports of the\n"
"type specified by @var{family}, @var{style} and @var{protocol}.\n"
"Many systems support only socket pairs of the @code{AF_UNIX}\n"
"family. Zero is likely to be the only meaningful value for\n"
"@var{protocol}.")
#define FUNC_NAME s_scm_socketpair
{
int fam;
@ -199,14 +202,15 @@ SCM_DEFINE (scm_socketpair, "socketpair", 3, 0, 0,
SCM_DEFINE (scm_getsockopt, "getsockopt", 3, 0, 0,
(SCM sock, SCM level, SCM optname),
"Returns the value of a particular socket option for the socket\n"
"port @var{socket}. @var{level} is an integer code for type of option\n"
"being requested, e.g., @code{SOL_SOCKET} for socket-level options.\n"
"@var{optname} is an\n"
"integer code for the option required and should be specified using one of\n"
"the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.\n\n"
"The returned value is typically an integer but @code{SO_LINGER} returns a\n"
"pair of integers.")
"Return the value of a particular socket option for the socket\n"
"port @var{socket}. @var{level} is an integer code for type of\n"
"option being requested, e.g., @code{SOL_SOCKET} for\n"
"socket-level options. @var{optname} is an integer code for the\n"
"option required and should be specified using one of the\n"
"symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.\n"
"\n"
"The returned value is typically an integer but @code{SO_LINGER}\n"
"returns a pair of integers.")
#define FUNC_NAME s_scm_getsockopt
{
int fd;
@ -663,9 +667,9 @@ SCM_DEFINE (scm_accept, "accept", 1, 0, 0,
SCM_DEFINE (scm_getsockname, "getsockname", 1, 0, 0,
(SCM sock),
"Returns the address of @var{socket}, in the same form as the object\n"
"returned by @code{accept}. On many systems the address of a socket\n"
"in the @code{AF_FILE} namespace cannot be read.")
"Return the address of @var{socket}, in the same form as the\n"
"object returned by @code{accept}. On many systems the address\n"
"of a socket in the @code{AF_FILE} namespace cannot be read.")
#define FUNC_NAME s_scm_getsockname
{
int fd;
@ -689,10 +693,10 @@ SCM_DEFINE (scm_getsockname, "getsockname", 1, 0, 0,
SCM_DEFINE (scm_getpeername, "getpeername", 1, 0, 0,
(SCM sock),
"Returns the address of the socket that the socket @var{socket} is connected to,\n"
"in the same form as the object\n"
"returned by @code{accept}. On many systems the address of a socket\n"
"in the @code{AF_FILE} namespace cannot be read.")
"Return the address of the socket that the socket @var{socket}\n"
"is connected to, in the same form as the object returned by\n"
"@code{accept}. On many systems the address of a socket in the\n"
"@code{AF_FILE} namespace cannot be read.")
#define FUNC_NAME s_scm_getpeername
{
int fd;
@ -778,23 +782,27 @@ SCM_DEFINE (scm_send, "send", 2, 1, 0,
SCM_DEFINE (scm_recvfrom, "recvfrom!", 2, 3, 0,
(SCM sock, SCM str, SCM flags, SCM start, SCM end),
"Returns data from the socket port @var{socket} and also information about\n"
"where the data was received from. @var{socket} must already\n"
"be bound to the address from which data is to be received.\n"
"@code{str}, is a string into which\n"
"the data will be written. The size of @var{str} limits the amount of\n"
"data which can be received: in the case of packet\n"
"protocols, if a packet larger than this limit is encountered then some data\n"
"will be irrevocably lost.\n\n"
"The optional @var{flags} argument is a value or\n"
"bitwise OR of MSG_OOB, MSG_PEEK, MSG_DONTROUTE etc.\n\n"
"The value returned is a pair: the CAR is the number of bytes read from\n"
"the socket and the CDR an address object in the same form as returned by\n"
"@code{accept}.\n\n"
"The @var{start} and @var{end} arguments specify a substring of @var{str}\n"
"to which the data should be written.\n\n"
"Note that the data is read directly from the socket file descriptor:\n"
"any unread buffered port data is ignored.")
"Return data from the socket port @var{socket} and also\n"
"information about where the data was received from.\n"
"@var{socket} must already be bound to the address from which\n"
"data is to be received. @code{str}, is a string into which the\n"
"data will be written. The size of @var{str} limits the amount\n"
"of data which can be received: in the case of packet protocols,\n"
"if a packet larger than this limit is encountered then some\n"
"data will be irrevocably lost.\n"
"\n"
"The optional @var{flags} argument is a value or bitwise OR of\n"
"@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.\n"
"\n"
"The value returned is a pair: the @emph{car} is the number of\n"
"bytes read from the socket and the @emph{cdr} an address object\n"
"in the same form as returned by @code{accept}.\n"
"\n"
"The @var{start} and @var{end} arguments specify a substring of\n"
"@var{str} to which the data should be written.\n"
"\n"
"Note that the data is read directly from the socket file\n"
"descriptor: any unread buffered port data is ignored.")
#define FUNC_NAME s_scm_recvfrom
{
int rv;

52
libguile/stime.c
View file

@ -138,7 +138,8 @@ timet scm_your_base = 0;
SCM_DEFINE (scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0,
(),
"Returns the number of time units since the interpreter was started.")
"Return the number of time units since the interpreter was\n"
"started.")
#define FUNC_NAME s_scm_get_internal_real_time
{
#ifdef HAVE_FTIME
@ -163,9 +164,10 @@ SCM_DEFINE (scm_get_internal_real_time, "get-internal-real-time", 0, 0, 0,
#ifdef HAVE_TIMES
SCM_DEFINE (scm_times, "times", 0, 0, 0,
(void),
"Returns an object with information about real and processor time.\n"
"The following procedures accept such an object as an argument and\n"
"return a selected component:\n\n"
"Return an object with information about real and processor\n"
"time. The following procedures accept such an object as an\n"
"argument and return a selected component:\n"
"\n"
"@table @code\n"
"@item tms:clock\n"
"The current real time, expressed as time units relative to an\n"
@ -173,12 +175,14 @@ SCM_DEFINE (scm_times, "times", 0, 0, 0,
"@item tms:utime\n"
"The CPU time units used by the calling process.\n"
"@item tms:stime\n"
"The CPU time units used by the system on behalf of the calling process.\n"
"The CPU time units used by the system on behalf of the calling\n"
"process.\n"
"@item tms:cutime\n"
"The CPU time units used by terminated child processes of the calling\n"
"process, whose status has been collected (e.g., using @code{waitpid}).\n"
"The CPU time units used by terminated child processes of the\n"
"calling process, whose status has been collected (e.g., using\n"
"@code{waitpid}).\n"
"@item tms:cstime\n"
"Similarly, the CPU times units used by the system on behalf of \n"
"Similarly, the CPU times units used by the system on behalf of\n"
"terminated child processes.\n"
"@end table")
#define FUNC_NAME s_scm_times
@ -210,8 +214,9 @@ scm_c_get_internal_run_time ()
SCM_DEFINE (scm_get_internal_run_time, "get-internal-run-time", 0, 0, 0,
(void),
"Returns the number of time units of processor time used by the interpreter.\n"
"Both \"system\" and \"user\" time are included but subprocesses are not.")
"Return the number of time units of processor time used by the\n"
"interpreter. Both @emph{system} and @emph{user} time are\n"
"included but subprocesses are not.")
#define FUNC_NAME s_scm_get_internal_run_time
{
return scm_long2num (scm_c_get_internal_run_time ());
@ -220,8 +225,8 @@ SCM_DEFINE (scm_get_internal_run_time, "get-internal-run-time", 0, 0, 0,
SCM_DEFINE (scm_current_time, "current-time", 0, 0, 0,
(void),
"Returns the number of seconds since 1970-01-01 00:00:00 UTC, excluding\n"
"leap seconds.")
"Return the number of seconds since 1970-01-01 00:00:00 UTC,\n"
"excluding leap seconds.")
#define FUNC_NAME s_scm_current_time
{
timet timv;
@ -236,9 +241,10 @@ SCM_DEFINE (scm_current_time, "current-time", 0, 0, 0,
SCM_DEFINE (scm_gettimeofday, "gettimeofday", 0, 0, 0,
(void),
"Returns a pair containing the number of seconds and microseconds since\n"
"1970-01-01 00:00:00 UTC, excluding leap seconds. Note: whether true\n"
"microsecond resolution is available depends on the operating system.")
"Return a pair containing the number of seconds and microseconds\n"
"since 1970-01-01 00:00:00 UTC, excluding leap seconds. Note:\n"
"whether true microsecond resolution is available depends on the\n"
"operating system.")
#define FUNC_NAME s_scm_gettimeofday
{
#ifdef HAVE_GETTIMEOFDAY
@ -334,11 +340,11 @@ restorezone (SCM zone, char **oldenv, const char *subr)
SCM_DEFINE (scm_localtime, "localtime", 1, 1, 0,
(SCM time, SCM zone),
"Returns an object representing the broken down components of @var{time},\n"
"an integer like the one returned by @code{current-time}. The time zone\n"
"for the calculation is optionally specified by @var{zone} (a string),\n"
"otherwise the @code{TZ} environment variable or the system default is\n"
"used.")
"Return an object representing the broken down components of\n"
"@var{time}, an integer like the one returned by\n"
"@code{current-time}. The time zone for the calculation is\n"
"optionally specified by @var{zone} (a string), otherwise the\n"
"@code{TZ} environment variable or the system default is used.")
#define FUNC_NAME s_scm_localtime
{
timet itime;
@ -408,9 +414,9 @@ SCM_DEFINE (scm_localtime, "localtime", 1, 1, 0,
SCM_DEFINE (scm_gmtime, "gmtime", 1, 0, 0,
(SCM time),
"Returns an object representing the broken down components of @var{time},\n"
"an integer like the one returned by @code{current-time}. The values\n"
"are calculated for UTC.")
"Return an object representing the broken down components of\n"
"@var{time}, an integer like the one returned by\n"
"@code{current-time}. The values are calculated for UTC.")
#define FUNC_NAME s_scm_gmtime
{
timet itime;

32
libguile/strings.c
View file

@ -58,7 +58,7 @@
SCM_DEFINE (scm_string_p, "string?", 1, 0, 0,
(SCM obj),
"Returns @code{#t} iff @var{obj} is a string, else returns\n"
"Return @code{#t} iff @var{obj} is a string, else returns\n"
"@code{#f}.")
#define FUNC_NAME s_scm_string_p
{
@ -77,12 +77,12 @@ SCM_DEFINE (scm_read_only_string_p, "read-only-string?", 1, 0, 0,
"Return true if @var{obj} can be read as a string,\n\n"
"This illustrates the difference between @code{string?} and\n"
"@code{read-only-string?}:\n\n"
"@example\n"
"@lisp\n"
"(string? \"a string\") @result{} #t\n"
"(string? 'a-symbol) @result{} #f\n\n"
"(read-only-string? \"a string\") @result{} #t\n"
"(read-only-string? 'a-symbol) @result{} #t\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_read_only_string_p
{
return SCM_BOOL(SCM_ROSTRINGP (obj));
@ -96,7 +96,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"
"Returns a newly allocated string composed of the arguments,\n"
"Return a newly allocated string composed of the arguments,\n"
"@var{chrs}.")
#define FUNC_NAME s_scm_string
{
@ -390,14 +390,14 @@ SCM_DEFINE (scm_string_append, "string-append", 0, 0, 1,
*/
SCM_DEFINE (scm_make_shared_substring, "make-shared-substring", 1, 2, 0,
(SCM str, SCM frm, SCM to),
"Return a shared substring of @var{str}. The semantics are the same as\n"
"for the @code{substring} function: the shared substring returned\n"
"includes all of the text from @var{str} between indexes @var{start}\n"
"(inclusive) and @var{end} (exclusive). If @var{end} is omitted, it\n"
"defaults to the end of @var{str}. The shared substring returned by\n"
"@code{make-shared-substring} occupies the same storage space as\n"
"@var{str}.")
(SCM str, SCM start, SCM end),
"Return a shared substring of @var{str}. The semantics are the\n"
"same as for the @code{substring} function: the shared substring\n"
"returned includes all of the text from @var{str} between\n"
"indexes @var{start} (inclusive) and @var{end} (exclusive). If\n"
"@var{end} is omitted, it defaults to the end of @var{str}. The\n"
"shared substring returned by @code{make-shared-substring}\n"
"occupies the same storage space as @var{str}.")
#define FUNC_NAME s_scm_make_shared_substring
{
long f;
@ -406,11 +406,11 @@ SCM_DEFINE (scm_make_shared_substring, "make-shared-substring", 1, 2, 0,
SCM len_str;
SCM_VALIDATE_ROSTRING (1,str);
SCM_VALIDATE_INUM_DEF_COPY (2,frm,0,f);
SCM_VALIDATE_INUM_DEF_COPY (3,to,SCM_ROLENGTH(str),t);
SCM_VALIDATE_INUM_DEF_COPY (2,start,0,f);
SCM_VALIDATE_INUM_DEF_COPY (3,end,SCM_ROLENGTH(str),t);
SCM_ASSERT_RANGE (2,frm,(f >= 0));
SCM_ASSERT_RANGE (3,to, (f <= t) && (t <= SCM_ROLENGTH (str)));
SCM_ASSERT_RANGE (2,start,(f >= 0));
SCM_ASSERT_RANGE (3,end, (f <= t) && (t <= SCM_ROLENGTH (str)));
SCM_NEWCELL (answer);
SCM_NEWCELL (len_str);

68
libguile/strop.c
View file

@ -104,21 +104,16 @@ SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0,
"@var{str}. The optional integer arguments @var{frm} and\n"
"@var{to} limit the search to a portion of the string. This\n"
"procedure essentially implements the @code{index} or\n"
"@code{strchr} functions from the C library.\n\n"
"(qdocs:) Returns\n"
"the index of @var{char} in @var{str}, or @code{#f} if the\n"
"@var{char} isn't in @var{str}. If @var{frm} is given and not\n"
"@code{#f}, it is used as the starting index; if @var{to} is\n"
"given and not @code{#f}, it is used as the ending index\n"
"(exclusive).\n\n"
"@example\n"
"@code{strchr} functions from the C library.\n"
"\n"
"@lisp\n"
"(string-index \"weiner\" #\\e)\n"
"@result{} 1\n\n"
"(string-index \"weiner\" #\\e 2)\n"
"@result{} 4\n\n"
"(string-index \"weiner\" #\\e 2 4)\n"
"@result{} #f\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_string_index
{
int pos;
@ -136,20 +131,19 @@ SCM_DEFINE (scm_string_index, "string-index", 2, 2, 0,
SCM_DEFINE (scm_string_rindex, "string-rindex", 2, 2, 0,
(SCM str, SCM chr, SCM frm, SCM to),
"Like @code{string-index}, but search from the right of the string rather\n"
"than from the left. This procedure essentially implements the\n"
"@code{rindex} or @code{strrchr} functions from the C library.\n\n"
"(qdocs:) The same as @code{string-index}, except it gives the rightmost occurance\n"
"of @var{char} in the range [@var{frm}, @var{to}-1], which defaults to\n"
"the entire string.\n\n"
"@example\n"
"Like @code{string-index}, but search from the right of the\n"
"string rather than from the left. This procedure essentially\n"
"implements the @code{rindex} or @code{strrchr} functions from\n"
"the C library.\n"
"\n"
"@lisp\n"
"(string-rindex \"weiner\" #\\e)\n"
"@result{} 4\n\n"
"(string-rindex \"weiner\" #\\e 2 4)\n"
"@result{} #f\n\n"
"(string-rindex \"weiner\" #\\e 2 5)\n"
"@result{} 4\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_string_rindex
{
int pos;
@ -179,7 +173,7 @@ Moves a substring of @var{str1}, from @var{start1} to @var{end1}
(@var{end1} is exclusive), into @var{str2}, starting at
@var{start2}. Allows overlapping strings.
@example
@lisp
(define x (make-string 10 #\a))
(define y "bcd")
(substring-move-left! x 2 5 y 0)
@ -198,7 +192,7 @@ y
(substring-move-left! y 2 5 y 3)
y
@result{} "abccccg"
@end example
@end lisp
*/
/*
@ -210,7 +204,7 @@ it hasn't made it into the guile tree].
Does much the same thing as @code{substring-move-left!}, except it
starts moving at the end of the sequence, rather than the beginning.
@example
@lisp
(define y "abcdefg")
(substring-move-right! y 2 5 y 0)
y
@ -220,7 +214,7 @@ y
(substring-move-right! y 2 5 y 3)
y
@result{} "abccdeg"
@end example
@end lisp
*/
SCM_DEFINE (scm_substring_move_x, "substring-move!", 5, 0, 0,
@ -269,15 +263,15 @@ SCM_DEFINE (scm_substring_move_x, "substring-move!", 5, 0, 0,
SCM_DEFINE (scm_substring_fill_x, "substring-fill!", 4, 0, 0,
(SCM str, SCM start, SCM end, SCM fill),
"Change every character in @var{str} between @var{start} and @var{end} to\n"
"@var{fill-char}.\n\n"
"(qdocs:) Destructively fills @var{str}, from @var{start} to @var{end}, with @var{fill}.\n\n"
"@example\n"
"Change every character in @var{str} between @var{start} and\n"
"@var{end} to @var{fill}.\n"
"\n"
"@lisp\n"
"(define y \"abcdefg\")\n"
"(substring-fill! y 1 3 #\\r)\n"
"y\n"
"@result{} \"arrdefg\"\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_substring_fill_x
{
long i, e;
@ -296,15 +290,13 @@ SCM_DEFINE (scm_substring_fill_x, "substring-fill!", 4, 0, 0,
SCM_DEFINE (scm_string_null_p, "string-null?", 1, 0, 0,
(SCM str),
"Return @code{#t} if @var{str}'s length is nonzero, and @code{#f}\n"
"otherwise.\n\n"
"(qdocs:) Returns @code{#t} if @var{str} is empty, else returns @code{#f}.\n\n"
"@example\n"
"(string-null? \"\")\n"
"@result{} #t\n\n"
"(string-null? y)\n"
"@result{} #f\n"
"@end example")
"Return @code{#t} if @var{str}'s length is nonzero, and\n"
"@code{#f} otherwise.\n"
"@lisp\n"
"(string-null? \"\") @result{} #t\n"
"y @result{} \"foo\"\n"
"(string-null? y) @result{} #f\n"
"@end lisp")
#define FUNC_NAME s_scm_string_null_p
{
SCM_VALIDATE_STRING (1,str);
@ -343,7 +335,7 @@ string_copy (SCM str)
SCM_DEFINE (scm_string_copy, "string-copy", 1, 0, 0,
(SCM str),
"Returns a newly allocated copy of the given @var{string}. (r5rs)")
"Return a newly allocated copy of the given @var{string}.")
#define FUNC_NAME s_scm_string_copy
{
SCM_VALIDATE_STRING (1, str);
@ -355,8 +347,8 @@ SCM_DEFINE (scm_string_copy, "string-copy", 1, 0, 0,
SCM_DEFINE (scm_string_fill_x, "string-fill!", 2, 0, 0,
(SCM str, SCM chr),
"Stores @var{char} in every element of the given @var{string} and returns an\n"
"unspecified value. (r5rs)")
"Store @var{char} in every element of the given @var{string} and\n"
"return an unspecified value.")
#define FUNC_NAME s_scm_string_fill_x
{
register char *dst, c;

66
libguile/strorder.c
View file

@ -54,14 +54,14 @@
SCM_DEFINE1 (scm_string_equal_p, "string=?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Lexicographic equality predicate; \n"
"Returns @code{#t} if the two strings are the same length and\n"
"contain the same characters in the same positions, otherwise\n"
"returns @code{#f}. (r5rs)\n\n"
"The procedure @code{string-ci=?} treats upper and lower case\n"
"letters as though they were the same character, but\n"
"@code{string=?} treats upper and lower case as distinct\n"
"characters.")
"Lexicographic equality predicate; return @code{#t} if the two\n"
"strings are the same length and contain the same characters in\n"
"the same positions, otherwise return @code{#f}.\n"
"\n"
"The procedure @code{string-ci=?} treats upper and lower case\n"
"letters as though they were the same character, but\n"
"@code{string=?} treats upper and lower case as distinct\n"
"characters.")
#define FUNC_NAME s_scm_string_equal_p
{
scm_sizet length;
@ -93,10 +93,10 @@ SCM_DEFINE1 (scm_string_equal_p, "string=?", scm_tc7_rpsubr,
SCM_DEFINE1 (scm_string_ci_equal_p, "string-ci=?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Case-insensitive string equality predicate; returns @code{#t}\n"
"if the two strings are the same length and their component\n"
"characters match (ignoring case) at each position; otherwise\n"
"returns @code{#f}. (r5rs)")
"Case-insensitive string equality predicate; return @code{#t} if\n"
"the two strings are the same length and their component\n"
"characters match (ignoring case) at each position; otherwise\n"
"return @code{#f}.")
#define FUNC_NAME s_scm_string_ci_equal_p
{
scm_sizet length;
@ -152,8 +152,8 @@ string_less_p (SCM s1, SCM s2)
SCM_DEFINE1 (scm_string_less_p, "string<?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Lexicographic ordering predicate; returns @code{#t} if\n"
"@var{s1} is lexicographically less than @var{s2}. (r5rs)")
"Lexicographic ordering predicate; return @code{#t} if @var{s1}\n"
"is lexicographically less than @var{s2}.")
#define FUNC_NAME s_scm_string_less_p
{
SCM_VALIDATE_STRING (1, s1);
@ -166,9 +166,8 @@ SCM_DEFINE1 (scm_string_less_p, "string<?", scm_tc7_rpsubr,
SCM_DEFINE1 (scm_string_leq_p, "string<=?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Lexicographic ordering predicate; returns @code{#t} if\n"
"@var{s1} is lexicographically less than or equal to @var{s2}.\n"
"(r5rs)")
"Lexicographic ordering predicate; return @code{#t} if @var{s1}\n"
"is lexicographically less than or equal to @var{s2}.")
#define FUNC_NAME s_scm_string_leq_p
{
SCM_VALIDATE_STRING (1, s1);
@ -181,8 +180,8 @@ SCM_DEFINE1 (scm_string_leq_p, "string<=?", scm_tc7_rpsubr,
SCM_DEFINE1 (scm_string_gr_p, "string>?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Lexicographic ordering predicate; returns @code{#t} if\n"
"@var{s1} is lexicographically greater than @var{s2}. (r5rs)")
"Lexicographic ordering predicate; return @code{#t} if @var{s1}\n"
"is lexicographically greater than @var{s2}.")
#define FUNC_NAME s_scm_string_gr_p
{
SCM_VALIDATE_STRING (1, s1);
@ -195,9 +194,8 @@ SCM_DEFINE1 (scm_string_gr_p, "string>?", scm_tc7_rpsubr,
SCM_DEFINE1 (scm_string_geq_p, "string>=?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Lexicographic ordering predicate; returns @code{#t} if\n"
"@var{s1} is lexicographically greater than or equal to\n"
"@var{s2}. (r5rs)")
"Lexicographic ordering predicate; return @code{#t} if @var{s1}\n"
"is lexicographically greater than or equal to @var{s2}.")
#define FUNC_NAME s_scm_string_geq_p
{
SCM_VALIDATE_STRING (1, s1);
@ -234,9 +232,9 @@ string_ci_less_p (SCM s1, SCM s2)
SCM_DEFINE1 (scm_string_ci_less_p, "string-ci<?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Case insensitive lexicographic ordering predicate;\n"
"returns @code{#t} if @var{s1} is lexicographically less than\n"
"@var{s2} regardless of case. (r5rs)")
"Case insensitive lexicographic ordering predicate; return\n"
"@code{#t} if @var{s1} is lexicographically less than @var{s2}\n"
"regardless of case.")
#define FUNC_NAME s_scm_string_ci_less_p
{
SCM_VALIDATE_STRING (1, s1);
@ -249,9 +247,9 @@ SCM_DEFINE1 (scm_string_ci_less_p, "string-ci<?", scm_tc7_rpsubr,
SCM_DEFINE1 (scm_string_ci_leq_p, "string-ci<=?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Case insensitive lexicographic ordering predicate;\n"
"returns @code{#t} if @var{s1} is lexicographically less than\n"
"or equal to @var{s2} regardless of case. (r5rs)")
"Case insensitive lexicographic ordering predicate; return\n"
"@code{#t} if @var{s1} is lexicographically less than or equal\n"
"to @var{s2} regardless of case.")
#define FUNC_NAME s_scm_string_ci_leq_p
{
SCM_VALIDATE_STRING (1, s1);
@ -264,9 +262,9 @@ SCM_DEFINE1 (scm_string_ci_leq_p, "string-ci<=?", scm_tc7_rpsubr,
SCM_DEFINE1 (scm_string_ci_gr_p, "string-ci>?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Case insensitive lexicographic ordering predicate;\n"
"returns @code{#t} if @var{s1} is lexicographically greater\n"
"than @var{s2} regardless of case. (r5rs)")
"Case insensitive lexicographic ordering predicate; return\n"
"@code{#t} if @var{s1} is lexicographically greater than\n"
"@var{s2} regardless of case.")
#define FUNC_NAME s_scm_string_ci_gr_p
{
SCM_VALIDATE_STRING (1, s1);
@ -279,9 +277,9 @@ SCM_DEFINE1 (scm_string_ci_gr_p, "string-ci>?", scm_tc7_rpsubr,
SCM_DEFINE1 (scm_string_ci_geq_p, "string-ci>=?", scm_tc7_rpsubr,
(SCM s1, SCM s2),
"Case insensitive lexicographic ordering predicate;\n"
"returns @code{#t} if @var{s1} is lexicographically greater\n"
"than or equal to @var{s2} regardless of case. (r5rs)")
"Case insensitive lexicographic ordering predicate; return\n"
"@code{#t} if @var{s1} is lexicographically greater than or\n"
"equal to @var{s2} regardless of case.")
#define FUNC_NAME s_scm_string_ci_geq_p
{
SCM_VALIDATE_STRING (1, s1);

18
libguile/strports.c
View file

@ -365,21 +365,21 @@ SCM_DEFINE (scm_call_with_output_string, "call-with-output-string", 1, 0, 0,
#undef FUNC_NAME
SCM_DEFINE (scm_call_with_input_string, "call-with-input-string", 2, 0, 0,
(SCM str, SCM proc),
"Calls the one-argument procedure @var{proc} with a newly created input\n"
"port from which @var{string}'s contents may be read. The value yielded\n"
"by the @var{proc} is returned.")
(SCM string, SCM proc),
"Calls the one-argument procedure @var{proc} with a newly\n"
"created input port from which @var{string}'s contents may be\n"
"read. The value yielded by the @var{proc} is returned.")
#define FUNC_NAME s_scm_call_with_input_string
{
SCM p = scm_mkstrport(SCM_INUM0, str, SCM_OPN | SCM_RDNG, FUNC_NAME);
SCM p = scm_mkstrport(SCM_INUM0, string, SCM_OPN | SCM_RDNG, FUNC_NAME);
return scm_apply (proc, p, scm_listofnull);
}
#undef FUNC_NAME
SCM_DEFINE (scm_open_input_string, "open-input-string", 1, 0, 0,
(SCM str),
"Takes a string and returns an input port that delivers\n"
"characters from the string. The port can be closed by\n"
"Take a string and return an input port that delivers characters\n"
"from the string. The port can be closed by\n"
"@code{close-input-port}, though its storage will be reclaimed\n"
"by the garbage collector if it becomes inaccessible.")
#define FUNC_NAME s_scm_open_input_string
@ -391,7 +391,7 @@ SCM_DEFINE (scm_open_input_string, "open-input-string", 1, 0, 0,
SCM_DEFINE (scm_open_output_string, "open-output-string", 0, 0, 0,
(void),
"Returns an output port that will accumulate characters for\n"
"Return an output port that will accumulate characters for\n"
"retrieval by @code{get-output-string}. The port can be closed\n"
"by the procedure @code{close-output-port}, though its storage\n"
"will be reclaimed by the garbage collector if it becomes\n"
@ -411,7 +411,7 @@ SCM_DEFINE (scm_open_output_string, "open-output-string", 0, 0, 0,
SCM_DEFINE (scm_get_output_string, "get-output-string", 1, 0, 0,
(SCM port),
"Given an output port created by @code{open-output-string},\n"
"returns a string consisting of the characters that have been\n"
"return a string consisting of the characters that have been\n"
"output to the port so far.")
#define FUNC_NAME s_scm_get_output_string
{

4
libguile/struct.c
View file

@ -503,7 +503,7 @@ SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
"sub-system: one vtable-vtable working as the root and one or several\n"
"\"types\", each with a set of \"instances\". (The vtable-vtable should be\n"
"compared to the class <class> which is the class of itself.)\n\n"
"@example\n"
"@lisp\n"
"(define ball-root (make-vtable-vtable \"pr\" 0))\n\n"
"(define (make-ball-type ball-color)\n"
" (make-struct ball-root 0\n"
@ -520,7 +520,7 @@ SCM_DEFINE (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
"(define (make-ball type owner) (make-struct type 0 owner))\n\n"
"(define ball (make-ball green 'Nisse))\n"
"ball @result{} #<a green ball owned by Nisse>\n"
"@end example\n")
"@end lisp\n")
#define FUNC_NAME s_scm_make_vtable_vtable
{
SCM fields;

56
libguile/symbols.c
View file

@ -418,8 +418,8 @@ scm_symbol_value0 (const char *name)
SCM_DEFINE (scm_symbol_p, "symbol?", 1, 0, 0,
(SCM obj),
"Returns @code{#t} if @var{obj} is a symbol, otherwise returns\n"
"@code{#f}. (r5rs)")
"Return @code{#t} if @var{obj} is a symbol, otherwise return\n"
"@code{#f}.")
#define FUNC_NAME s_scm_symbol_p
{
return SCM_BOOL (SCM_SYMBOLP (obj));
@ -428,24 +428,26 @@ SCM_DEFINE (scm_symbol_p, "symbol?", 1, 0, 0,
SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0,
(SCM s),
"Returns the name of @var{symbol} as a string. If the symbol\n"
"was part of an object returned as the value of a literal\n"
"expression (section @pxref{Literal expressions,,,r4rs, The\n"
"Revised^4 Report on Scheme}) or by a call to the @code{read}\n"
"procedure, and its name contains alphabetic characters, then\n"
"the string returned will contain characters in the\n"
"implementation's preferred standard case---some implementations\n"
"will prefer upper case, others lower case. If the symbol was\n"
"returned by @code{string->symbol}, the case of characters in\n"
"the string returned will be the same as the case in the string\n"
"that was passed to @code{string->symbol}. It is an error to\n"
"apply mutation procedures like @code{string-set!} to strings\n"
"returned by this procedure. (r5rs)\n\n"
"Return the name of @var{symbol} as a string. If the symbol was\n"
"part of an object returned as the value of a literal expression\n"
"(section @pxref{Literal expressions,,,r4rs, The Revised^4\n"
"Report on Scheme}) or by a call to the @code{read} procedure,\n"
"and its name contains alphabetic characters, then the string\n"
"returned will contain characters in the implementation's\n"
"preferred standard case---some implementations will prefer\n"
"upper case, others lower case. If the symbol was returned by\n"
"@code{string->symbol}, the case of characters in the string\n"
"returned will be the same as the case in the string that was\n"
"passed to @code{string->symbol}. It is an error to apply\n"
"mutation procedures like @code{string-set!} to strings returned\n"
"by this procedure.\n"
"\n"
"The following examples assume that the implementation's\n"
"standard case is lower case:\n\n"
"standard case is lower case:\n"
"\n"
"@lisp\n"
"(symbol->string 'flying-fish) @result{} \"flying-fish\"\n"
"(symbol->string 'Martin) @result{} \"martin\"\n"
"(symbol->string 'flying-fish) @result{} \"flying-fish\"\n"
"(symbol->string 'Martin) @result{} \"martin\"\n"
"(symbol->string\n"
" (string->symbol \"Malvina\")) @result{} \"Malvina\"\n"
"@end lisp")
@ -458,14 +460,17 @@ SCM_DEFINE (scm_symbol_to_string, "symbol->string", 1, 0, 0,
SCM_DEFINE (scm_string_to_symbol, "string->symbol", 1, 0, 0,
(SCM s),
"Returns the symbol whose name is @var{string}. This procedure\n"
(SCM string),
"Return the symbol whose name is @var{string}. This procedure\n"
"can create symbols with names containing special characters or\n"
"letters in the non-standard case, but it is usually a bad idea\n"
"to create such because in some implementations of Scheme they\n"
"cannot be read as themselves. See @code{symbol->string}.\n\n"
"to create such symbols because in some implementations of\n"
"Scheme they cannot be read as themselves. See\n"
"@code{symbol->string}.\n"
"\n"
"The following examples assume that the implementation's\n"
"standard case is lower case:\n\n"
"standard case is lower case:\n"
"\n"
"@lisp\n"
"(eq? 'mISSISSIppi 'mississippi) @result{} #t\n"
"(string->symbol \"mISSISSIppi\") @result{} @r{the symbol with name \"mISSISSIppi\"}\n"
@ -478,8 +483,9 @@ SCM_DEFINE (scm_string_to_symbol, "string->symbol", 1, 0, 0,
"@end lisp")
#define FUNC_NAME s_scm_string_to_symbol
{
SCM_VALIDATE_STRING (1, s);
return scm_mem2symbol (SCM_STRING_CHARS (s), SCM_STRING_LENGTH (s));
SCM_VALIDATE_STRING (1, string);
return scm_mem2symbol (SCM_STRING_CHARS (string),
SCM_STRING_LENGTH (string));
}
#undef FUNC_NAME

52
libguile/throw.c
View file

@ -514,37 +514,41 @@ scm_handle_by_throw (void *handler_data, SCM tag, SCM args)
/* the Scheme-visible CATCH and LAZY-CATCH functions */
SCM_DEFINE (scm_catch, "catch", 3, 0, 0,
(SCM tag, SCM thunk, SCM handler),
(SCM key, SCM thunk, SCM handler),
"Invoke @var{thunk} in the dynamic context of @var{handler} for\n"
"exceptions matching @var{key}. If thunk throws to the symbol @var{key},\n"
"then @var{handler} is invoked this way:\n\n"
"@example\n"
"exceptions matching @var{key}. If thunk throws to the symbol\n"
"@var{key}, then @var{handler} is invoked this way:\n"
"@lisp\n"
"(handler key args ...)\n"
"@end example\n\n"
"@var{key} is a symbol or #t.\n\n"
"@var{thunk} takes no arguments. If @var{thunk} returns normally, that\n"
"is the return value of @code{catch}.\n\n"
"Handler is invoked outside the scope of its own @code{catch}. If\n"
"@var{handler} again throws to the same key, a new handler from further\n"
"up the call chain is invoked.\n\n"
"If the key is @code{#t}, then a throw to @emph{any} symbol will match\n"
"this call to @code{catch}.")
"@end lisp\n"
"\n"
"@var{key} is a symbol or @code{#t}.\n"
"\n"
"@var{thunk} takes no arguments. If @var{thunk} returns\n"
"normally, that is the return value of @code{catch}.\n"
"\n"
"Handler is invoked outside the scope of its own @code{catch}.\n"
"If @var{handler} again throws to the same key, a new handler\n"
"from further up the call chain is invoked.\n"
"\n"
"If the key is @code{#t}, then a throw to @emph{any} symbol will\n"
"match this call to @code{catch}.")
#define FUNC_NAME s_scm_catch
{
struct scm_body_thunk_data c;
SCM_ASSERT (SCM_SYMBOLP (tag) || SCM_EQ_P (tag, SCM_BOOL_T),
tag, SCM_ARG1, FUNC_NAME);
SCM_ASSERT (SCM_SYMBOLP (key) || SCM_EQ_P (key, SCM_BOOL_T),
key, SCM_ARG1, FUNC_NAME);
c.tag = tag;
c.tag = key;
c.body_proc = thunk;
/* scm_internal_catch takes care of all the mechanics of setting up
a catch tag; we tell it to call scm_body_thunk to run the body,
a catch key; we tell it to call scm_body_thunk to run the body,
and scm_handle_by_proc to deal with any throws to this catch.
The former receives a pointer to c, telling it how to behave.
The latter receives a pointer to HANDLER, so it knows who to call. */
return scm_internal_catch (tag,
return scm_internal_catch (key,
scm_body_thunk, &c,
scm_handle_by_proc, &handler);
}
@ -552,7 +556,7 @@ SCM_DEFINE (scm_catch, "catch", 3, 0, 0,
SCM_DEFINE (scm_lazy_catch, "lazy-catch", 3, 0, 0,
(SCM tag, SCM thunk, SCM handler),
(SCM key, SCM thunk, SCM handler),
"This behaves exactly like @code{catch}, except that it does\n"
"not unwind the stack (this is the major difference), and if\n"
"handler returns, its value is returned from the throw.")
@ -560,19 +564,19 @@ SCM_DEFINE (scm_lazy_catch, "lazy-catch", 3, 0, 0,
{
struct scm_body_thunk_data c;
SCM_ASSERT (SCM_SYMBOLP (tag) || SCM_EQ_P (tag, SCM_BOOL_T),
tag, SCM_ARG1, FUNC_NAME);
SCM_ASSERT (SCM_SYMBOLP (key) || SCM_EQ_P (key, SCM_BOOL_T),
key, SCM_ARG1, FUNC_NAME);
c.tag = tag;
c.tag = key;
c.body_proc = thunk;
/* scm_internal_lazy_catch takes care of all the mechanics of
setting up a lazy catch tag; we tell it to call scm_body_thunk to
setting up a lazy catch key; we tell it to call scm_body_thunk to
run the body, and scm_handle_by_proc to deal with any throws to
this catch. The former receives a pointer to c, telling it how
to behave. The latter receives a pointer to HANDLER, so it knows
who to call. */
return scm_internal_lazy_catch (tag,
return scm_internal_lazy_catch (key,
scm_body_thunk, &c,
scm_handle_by_proc, &handler);
}

98
libguile/unif.c
View file

@ -251,8 +251,8 @@ scm_make_uve (long k, SCM prot)
SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
(SCM v),
"Returns the number of elements in @var{uve}.")
(SCM v),
"Return the number of elements in @var{uve}.")
#define FUNC_NAME s_scm_uniform_vector_length
{
SCM_ASRTGO (SCM_NIMP (v), badarg1);
@ -284,9 +284,9 @@ SCM_DEFINE (scm_uniform_vector_length, "uniform-vector-length", 1, 0, 0,
SCM_DEFINE (scm_array_p, "array?", 1, 1, 0,
(SCM v, SCM prot),
"Returns @code{#t} if the @var{obj} is an array, and @code{#f} if not.\n\n"
"The @var{prototype} argument is used with uniform arrays and is described\n"
"elsewhere.")
"Return @code{#t} if the @var{obj} is an array, and @code{#f} if\n"
"not. The @var{prototype} argument is used with uniform arrays\n"
"and is described elsewhere.")
#define FUNC_NAME s_scm_array_p
{
int nprot;
@ -356,8 +356,8 @@ SCM_DEFINE (scm_array_p, "array?", 1, 1, 0,
SCM_DEFINE (scm_array_rank, "array-rank", 1, 0, 0,
(SCM ra),
"Returns the number of dimensions of @var{obj}. If @var{obj} is not an\n"
"array, @code{0} is returned.")
"Return the number of dimensions of @var{obj}. If @var{obj} is\n"
"not an array, @code{0} is returned.")
#define FUNC_NAME s_scm_array_rank
{
if (SCM_IMP (ra))
@ -393,9 +393,9 @@ SCM_DEFINE (scm_array_dimensions, "array-dimensions", 1, 0, 0,
(SCM ra),
"@code{Array-dimensions} is similar to @code{array-shape} but replaces\n"
"elements with a @code{0} minimum with one greater than the maximum. So:\n"
"@example\n"
"@lisp\n"
"(array-dimensions (make-array 'foo '(-1 3) 5)) @result{} ((-1 3) 5)\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_array_dimensions
{
SCM res = SCM_EOL;
@ -578,12 +578,12 @@ 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),
(SCM dims, SCM prot, SCM fill),
"@deffnx primitive make-uniform-vector length prototype [fill]\n"
"Creates and returns a uniform array or vector of type corresponding to\n"
"@var{prototype} with dimensions @var{dims} or length @var{length}. If\n"
"@var{fill} is supplied, it's used to fill the array, otherwise \n"
"@var{prototype} is used.")
"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"
"fill the array, otherwise @var{prototype} is used.")
#define FUNC_NAME s_scm_dimensions_to_uniform_array
{
scm_sizet k;
@ -660,7 +660,7 @@ SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1,
"the new array into coordinates in the old array. A @var{mapper} must be\n"
"linear, and its range must stay within the bounds of the old array, but\n"
"it can be otherwise arbitrary. A simple example:\n"
"@example\n"
"@lisp\n"
"(define fred (make-array #f 8 8))\n"
"(define freds-diagonal\n"
" (make-shared-array fred (lambda (i) (list i i)) 8))\n"
@ -669,7 +669,7 @@ SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1,
"(define freds-center\n"
" (make-shared-array fred (lambda (i j) (list (+ 3 i) (+ 3 j))) 2 2))\n"
"(array-ref freds-center 0 0) @result{} foo\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_make_shared_array
{
SCM ra;
@ -783,23 +783,25 @@ SCM_DEFINE (scm_make_shared_array, "make-shared-array", 2, 0, 1,
/* args are RA . DIMS */
SCM_DEFINE (scm_transpose_array, "transpose-array", 1, 0, 1,
(SCM ra, SCM args),
"Returns an array sharing contents with @var{array}, but with dimensions\n"
"arranged in a different order. There must be one @var{dim} argument for\n"
"each dimension of @var{array}. @var{dim0}, @var{dim1}, @dots{} should\n"
"be integers between 0 and the rank of the array to be returned. Each\n"
"integer in that range must appear at least once in the argument list.\n\n"
"The values of @var{dim0}, @var{dim1}, @dots{} correspond to dimensions\n"
"in the array to be returned, their positions in the argument list to\n"
"dimensions of @var{array}. Several @var{dim}s may have the same value,\n"
"in which case the returned array will have smaller rank than\n"
"@var{array}.\n\n"
"examples:\n"
"@example\n"
"Return an array sharing contents with @var{array}, but with\n"
"dimensions arranged in a different order. There must be one\n"
"@var{dim} argument for each dimension of @var{array}.\n"
"@var{dim0}, @var{dim1}, @dots{} should be integers between 0\n"
"and the rank of the array to be returned. Each integer in that\n"
"range must appear at least once in the argument list.\n"
"\n"
"The values of @var{dim0}, @var{dim1}, @dots{} correspond to\n"
"dimensions in the array to be returned, their positions in the\n"
"argument list to dimensions of @var{array}. Several @var{dim}s\n"
"may have the same value, in which case the returned array will\n"
"have smaller rank than @var{array}.\n"
"\n"
"@lisp\n"
"(transpose-array '#2((a b) (c d)) 1 0) @result{} #2((a c) (b d))\n"
"(transpose-array '#2((a b) (c d)) 0 0) @result{} #1(a d)\n"
"(transpose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 1 0) @result{}\n"
" #2((a 4) (b 5) (c 6))\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_transpose_array
{
SCM res, vargs, *ve = &vargs;
@ -903,12 +905,12 @@ SCM_DEFINE (scm_enclose_array, "enclose-array", 1, 0, 1,
"@code{eq?}. The value returned by @var{array-prototype} when given an\n"
"enclosed array is unspecified.\n\n"
"examples:\n"
"@example\n"
"@lisp\n"
"(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1) @result{}\n"
" #<enclosed-array (#1(a d) #1(b e) #1(c f)) (#1(1 4) #1(2 5) #1(3 6))>\n\n"
"(enclose-array '#3(((a b c) (d e f)) ((1 2 3) (4 5 6))) 1 0) @result{}\n"
" #<enclosed-array #2((a 1) (d 4)) #2((b 2) (e 5)) #2((c 3) (f 6))>\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_enclose_array
{
SCM axv, res, ra_inr;
@ -991,7 +993,8 @@ SCM_DEFINE (scm_enclose_array, "enclose-array", 1, 0, 1,
SCM_DEFINE (scm_array_in_bounds_p, "array-in-bounds?", 1, 0, 1,
(SCM v, SCM args),
"Returns @code{#t} if its arguments would be acceptable to array-ref.")
"Return @code{#t} if its arguments would be acceptable to\n"
"@code{array-ref}.")
#define FUNC_NAME s_scm_array_in_bounds_p
{
SCM ind = SCM_EOL;
@ -1076,7 +1079,8 @@ 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"
"Returns the element at the @code{(index1, index2)} element in @var{array}.")
"Return the element at the @code{(index1, index2)} element in\n"
"@var{array}.")
#define FUNC_NAME s_scm_uniform_vector_ref
{
long pos;
@ -1770,7 +1774,7 @@ static char cnt_tab[16] =
SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0,
(SCM b, SCM bitvector),
"Returns the number of occurrences of the boolean @var{b} in\n"
"Return the number of occurrences of the boolean @var{b} in\n"
"@var{bitvector}.")
#define FUNC_NAME s_scm_bit_count
{
@ -1808,9 +1812,9 @@ SCM_DEFINE (scm_bit_count, "bit-count", 2, 0, 0,
SCM_DEFINE (scm_bit_position, "bit-position", 3, 0, 0,
(SCM item, SCM v, SCM k),
"Returns the minimum index of an occurrence of @var{bool} in @var{bv}\n"
"which is at least @var{k}. If no @var{bool} occurs within the specified\n"
"range @code{#f} is returned.")
"Return the minimum index of an occurrence of @var{bool} in\n"
"@var{bv} which is at least @var{k}. If no @var{bool} occurs\n"
"within the specified range @code{#f} is returned.")
#define FUNC_NAME s_scm_bit_position
{
long i, lenw, xbits, pos;
@ -1928,10 +1932,10 @@ SCM_DEFINE (scm_bit_set_star_x, "bit-set*!", 3, 0, 0,
SCM_DEFINE (scm_bit_count_star, "bit-count*", 3, 0, 0,
(SCM v, SCM kv, SCM obj),
"Returns\n"
"@example\n"
"Return\n"
"@lisp\n"
"(bit-count (bit-set*! (if bool bv (bit-invert! bv)) uve #t) #t).\n"
"@end example\n"
"@end lisp\n"
"@var{bv} is not modified.")
#define FUNC_NAME s_scm_bit_count_star
{
@ -2074,7 +2078,8 @@ ra2l (SCM ra,scm_sizet base,scm_sizet k)
SCM_DEFINE (scm_array_to_list, "array->list", 1, 0, 0,
(SCM v),
"Returns a list consisting of all the elements, in order, of @var{array}.")
"Return a list consisting of all the elements, in order, of\n"
"@var{array}.")
#define FUNC_NAME s_scm_array_to_list
{
SCM res = SCM_EOL;
@ -2164,9 +2169,10 @@ static int l2ra(SCM lst, SCM ra, scm_sizet base, scm_sizet 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"
"Returns a uniform array of the type indicated by prototype @var{prot}\n"
"with elements the same as those of @var{lst}. Elements must be of the\n"
"appropriate type, no coercions are done.")
"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"
"done.")
#define FUNC_NAME s_scm_list_to_uniform_array
{
SCM shp = SCM_EOL;
@ -2515,8 +2521,8 @@ tail:
SCM_DEFINE (scm_array_prototype, "array-prototype", 1, 0, 0,
(SCM ra),
"Returns an object that would produce an array of the same type as\n"
"@var{array}, if used as the @var{prototype} for\n"
"Return an object that would produce an array of the same type\n"
"as @var{array}, if used as the @var{prototype} for\n"
"@code{make-uniform-array}.")
#define FUNC_NAME s_scm_array_prototype
{

35
libguile/vectors.c
View file

@ -138,8 +138,8 @@ scm_vector_set_length_x (SCM vect, SCM len)
SCM_DEFINE (scm_vector_p, "vector?", 1, 0, 0,
(SCM obj),
"Returns @code{#t} if @var{obj} is a vector, otherwise returns\n"
"@code{#f}. (r5rs)")
"Return @code{#t} if @var{obj} is a vector, otherwise return\n"
"@code{#f}.")
#define FUNC_NAME s_scm_vector_p
{
if (SCM_IMP (obj))
@ -149,7 +149,7 @@ SCM_DEFINE (scm_vector_p, "vector?", 1, 0, 0,
#undef FUNC_NAME
SCM_GPROC (s_vector_length, "vector-length", 1, 0, 0, scm_vector_length, g_vector_length);
/* Returns the number of elements in @var{vector} as an exact integer. (r5rs) */
/* Returns the number of elements in @var{vector} as an exact integer. */
SCM
scm_vector_length (SCM v)
{
@ -170,10 +170,11 @@ 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"
"Returns a newly allocated vector whose elements contain the\n"
"given arguments. Analogous to @code{list}. (r5rs)\n\n"
"Return a newly allocated vector whose elements contain the\n"
"given arguments. Analogous to @code{list}.\n"
"\n"
"@lisp\n"
"(vector 'a 'b 'c) @result{} #(a b c)\n"
"(vector 'a 'b 'c) @result{} #(a b c)\n"
"@end lisp")
#define FUNC_NAME s_scm_vector
{
@ -257,9 +258,10 @@ scm_vector_set_x (SCM v, SCM k, SCM obj)
SCM_DEFINE (scm_make_vector, "make-vector", 1, 1, 0,
(SCM k, SCM fill),
"Returns a newly allocated vector of @var{k} elements. If a second\n"
"argument is given, then each element is initialized to @var{fill}.\n"
"Otherwise the initial contents of each element is unspecified. (r5rs)")
"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"
"unspecified.")
#define FUNC_NAME s_scm_make_vector
{
if (SCM_UNBNDP (fill))
@ -309,9 +311,10 @@ scm_c_make_vector (unsigned long int k, SCM fill)
SCM_DEFINE (scm_vector_to_list, "vector->list", 1, 0, 0,
(SCM v),
"@samp{Vector->list} returns a newly allocated list of the\n"
"objects contained in the elements of @var{vector}. (r5rs)\n\n"
(SCM v),
"Return a newly allocated list of the objects contained in the\n"
"elements of @var{vector}.\n"
"\n"
"@lisp\n"
"(vector->list '#(dah dah didah)) @result{} (dah dah didah)\n"
"(list->vector '(dididit dah)) @result{} #(dididit dah)\n"
@ -330,9 +333,9 @@ 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_x),
"Stores @var{fill} in every element of @var{vector}.\n"
"The value returned by @code{vector-fill!} is unspecified. (r5rs)")
(SCM v, SCM fill),
"Store @var{fill} in every element of @var{vector}. The value\n"
"returned by @code{vector-fill!} is unspecified.")
#define FUNC_NAME s_scm_vector_fill_x
{
register long i;
@ -340,7 +343,7 @@ SCM_DEFINE (scm_vector_fill_x, "vector-fill!", 2, 0, 0,
SCM_VALIDATE_VECTOR (1,v);
data = SCM_VELTS(v);
for(i = SCM_VECTOR_LENGTH(v) - 1; i >= 0; i--)
data[i] = fill_x;
data[i] = fill;
return SCM_UNSPECIFIED;
}
#undef FUNC_NAME

4
libguile/version.c
View file

@ -83,11 +83,11 @@ SCM_DEFINE (scm_version, "version", 0, 0, 0,
"@deffnx primitive minor-version\n"
"Return a string describing Guile's version number, or its major or minor\n"
"version numbers, respectively.\n\n"
"@example\n"
"@lisp\n"
"(version) @result{} \"1.3a\"\n"
"(major-version) @result{} \"1\"\n"
"(minor-version) @result{} \"3a\"\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_version
{
return scm_makfrom0str (GUILE_VERSION);

32
libguile/vports.c
View file

@ -147,10 +147,11 @@ sf_close (SCM port)
SCM_DEFINE (scm_make_soft_port, "make-soft-port", 2, 0, 0,
(SCM pv, SCM modes),
"Returns a port capable of receiving or delivering characters as\n"
"Return a port capable of receiving or delivering characters as\n"
"specified by the @var{modes} string (@pxref{File Ports,\n"
"open-file}). @var{vector} must be a vector of length 6. Its components\n"
"are as follows:\n\n"
"open-file}). @var{pv} must be a vector of length 5. Its\n"
"components are as follows:\n"
"\n"
"@enumerate 0\n"
"@item\n"
"procedure accepting one character for output\n"
@ -162,15 +163,19 @@ SCM_DEFINE (scm_make_soft_port, "make-soft-port", 2, 0, 0,
"thunk for getting one character\n"
"@item\n"
"thunk for closing port (not by garbage collection)\n"
"@end enumerate\n\n"
"@end enumerate\n"
"\n"
"For an output-only port only elements 0, 1, 2, and 4 need be\n"
"procedures. For an input-only port only elements 3 and 4 need be\n"
"procedures. Thunks 2 and 4 can instead be @code{#f} if there is no useful\n"
"operation for them to perform.\n\n"
"If thunk 3 returns @code{#f} or an @code{eof-object} (@pxref{Input,\n"
"eof-object?, ,r4rs, The Revised^4 Report on Scheme}) it indicates that\n"
"the port has reached end-of-file. For example:\n\n"
"@example\n"
"procedures. For an input-only port only elements 3 and 4 need\n"
"be procedures. Thunks 2 and 4 can instead be @code{#f} if\n"
"there is no useful operation for them to perform.\n"
"\n"
"If thunk 3 returns @code{#f} or an @code{eof-object}\n"
"(@pxref{Input, eof-object?, ,r4rs, The Revised^4 Report on\n"
"Scheme}) it indicates that the port has reached end-of-file.\n"
"For example:\n"
"\n"
"@lisp\n"
"(define stdout (current-output-port))\n"
"(define p (make-soft-port\n"
" (vector\n"
@ -179,9 +184,10 @@ SCM_DEFINE (scm_make_soft_port, "make-soft-port", 2, 0, 0,
" (lambda () (display \".\" stdout))\n"
" (lambda () (char-upcase (read-char)))\n"
" (lambda () (display \"@@\" stdout)))\n"
" \"rw\"))\n\n"
" \"rw\"))\n"
"\n"
"(write p p) @result{} #<input-output: soft 8081e20>\n"
"@end example")
"@end lisp")
#define FUNC_NAME s_scm_make_soft_port
{
scm_port *pt;

67
libguile/weaks.c
View file

@ -56,17 +56,18 @@
SCM_DEFINE (scm_make_weak_vector, "make-weak-vector", 1, 1, 0,
(SCM k, SCM fill),
(SCM size, SCM fill),
"Return a weak vector with @var{size} elements. If the optional\n"
"argument @var{fill} is given, all entries in the vector will be set to\n"
"@var{fill}. The default value for @var{fill} is the empty list.")
"argument @var{fill} is given, all entries in the vector will be\n"
"set to @var{fill}. The default value for @var{fill} is the\n"
"empty list.")
#define FUNC_NAME s_scm_make_weak_vector
{
/* Dirk:FIXME:: We should probably rather use a double cell for weak vectors. */
SCM v;
v = scm_make_vector (scm_sum (k, SCM_MAKINUM (2)), fill);
v = scm_make_vector (scm_sum (size, SCM_MAKINUM (2)), fill);
SCM_DEFER_INTS;
SCM_SET_VECTOR_LENGTH (v, SCM_INUM (k), scm_tc7_wvect);
SCM_SET_VECTOR_LENGTH (v, SCM_INUM (size), scm_tc7_wvect);
SCM_SETVELTS(v, SCM_VELTS(v) + 2);
SCM_VELTS(v)[-2] = SCM_EOL;
SCM_UNPACK (SCM_VELTS (v)[-1]) = 0;
@ -81,10 +82,10 @@ 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"
"Construct a weak vector from a list: @code{weak-vector} uses the list of\n"
"its arguments while @code{list->weak-vector} uses its only argument\n"
"@var{l} (a list) to construct a weak vector the same way\n"
"@code{vector->list} would.")
"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"
"the same way @code{list->vector} would.")
#define FUNC_NAME s_scm_weak_vector
{
SCM res;
@ -110,12 +111,12 @@ SCM_DEFINE (scm_weak_vector, "weak-vector", 0, 0, 1,
SCM_DEFINE (scm_weak_vector_p, "weak-vector?", 1, 0, 0,
(SCM x),
(SCM obj),
"Return @code{#t} if @var{obj} is a weak vector. Note that all\n"
"weak hashes are also weak vectors.")
#define FUNC_NAME s_scm_weak_vector_p
{
return SCM_BOOL(SCM_WVECTP (x) && !SCM_IS_WHVEC (x));
return SCM_BOOL(SCM_WVECTP (obj) && !SCM_IS_WHVEC (obj));
}
#undef FUNC_NAME
@ -126,18 +127,20 @@ 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 k),
(SCM size),
"@deffnx primitive make-weak-value-hash-table size\n"
"@deffnx primitive make-doubly-weak-hash-table size\n"
"Return a weak hash table with @var{size} buckets. As with any hash\n"
"table, choosing a good size for the table requires some caution.\n\n"
"You can modify weak hash tables in exactly the same way you would modify\n"
"regular hash tables. (@pxref{Hash Tables})")
"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"
"\n"
"You can modify weak hash tables in exactly the same way you\n"
"would modify regular hash tables. (@pxref{Hash Tables})")
#define FUNC_NAME s_scm_make_weak_key_hash_table
{
SCM v;
SCM_VALIDATE_INUM (1,k);
v = scm_make_weak_vector (k, SCM_EOL);
SCM_VALIDATE_INUM (1, size);
v = scm_make_weak_vector (size, SCM_EOL);
SCM_DEFER_INTS;
SCM_UNPACK (SCM_VELTS (v)[-1]) = 1;
SCM_ALLOW_INTS;
@ -147,14 +150,14 @@ SCM_DEFINE (scm_make_weak_key_hash_table, "make-weak-key-hash-table", 1, 0, 0,
SCM_DEFINE (scm_make_weak_value_hash_table, "make-weak-value-hash-table", 1, 0, 0,
(SCM k),
(SCM size),
"Return a hash table with weak values with @var{size} buckets.\n"
"(@pxref{Hash Tables})")
#define FUNC_NAME s_scm_make_weak_value_hash_table
{
SCM v;
SCM_VALIDATE_INUM (1,k);
v = scm_make_weak_vector (k, SCM_EOL);
SCM_VALIDATE_INUM (1, size);
v = scm_make_weak_vector (size, SCM_EOL);
SCM_DEFER_INTS;
SCM_UNPACK (SCM_VELTS (v)[-1]) = 2;
SCM_ALLOW_INTS;
@ -165,14 +168,14 @@ SCM_DEFINE (scm_make_weak_value_hash_table, "make-weak-value-hash-table", 1, 0,
SCM_DEFINE (scm_make_doubly_weak_hash_table, "make-doubly-weak-hash-table", 1, 0, 0,
(SCM k),
(SCM size),
"Return a hash table with weak keys and values with @var{size}\n"
"buckets. (@pxref{Hash Tables})")
#define FUNC_NAME s_scm_make_doubly_weak_hash_table
{
SCM v;
SCM_VALIDATE_INUM (1,k);
v = scm_make_weak_vector (k, SCM_EOL);
SCM_VALIDATE_INUM (1, size);
v = scm_make_weak_vector (size, SCM_EOL);
SCM_DEFER_INTS;
SCM_UNPACK (SCM_VELTS (v)[-1]) = 3;
SCM_ALLOW_INTS;
@ -181,7 +184,7 @@ SCM_DEFINE (scm_make_doubly_weak_hash_table, "make-doubly-weak-hash-table", 1, 0
#undef FUNC_NAME
SCM_DEFINE (scm_weak_key_hash_table_p, "weak-key-hash-table?", 1, 0, 0,
(SCM x),
(SCM obj),
"@deffnx primitive weak-value-hash-table? obj\n"
"@deffnx primitive doubly-weak-hash-table? obj\n"
"Return @code{#t} if @var{obj} is the specified weak hash\n"
@ -189,27 +192,27 @@ SCM_DEFINE (scm_weak_key_hash_table_p, "weak-key-hash-table?", 1, 0, 0,
"nor a weak value hash table.")
#define FUNC_NAME s_scm_weak_key_hash_table_p
{
return SCM_BOOL(SCM_WVECTP (x) && SCM_IS_WHVEC(x));
return SCM_BOOL(SCM_WVECTP (obj) && SCM_IS_WHVEC(obj));
}
#undef FUNC_NAME
SCM_DEFINE (scm_weak_value_hash_table_p, "weak-value-hash-table?", 1, 0, 0,
(SCM x),
"Return @code{#t} if @var{x} is a weak value hash table.")
(SCM obj),
"Return @code{#t} if @var{obj} is a weak value hash table.")
#define FUNC_NAME s_scm_weak_value_hash_table_p
{
return SCM_BOOL(SCM_WVECTP (x) && SCM_IS_WHVEC_V(x));
return SCM_BOOL(SCM_WVECTP (obj) && SCM_IS_WHVEC_V(obj));
}
#undef FUNC_NAME
SCM_DEFINE (scm_doubly_weak_hash_table_p, "doubly-weak-hash-table?", 1, 0, 0,
(SCM x),
"Return @code{#t} if @var{x} is a doubly weak hash table.")
(SCM obj),
"Return @code{#t} if @var{obj} is a doubly weak hash table.")
#define FUNC_NAME s_scm_doubly_weak_hash_table_p
{
return SCM_BOOL(SCM_WVECTP (x) && SCM_IS_WHVEC_B (x));
return SCM_BOOL(SCM_WVECTP (obj) && SCM_IS_WHVEC_B (obj));
}
#undef FUNC_NAME