diff options
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/ChangeLog | 29 | ||||
-rw-r--r-- | doc/ref/api-control.texi | 2 | ||||
-rwxr-xr-x | doc/ref/api-data.texi | 4 | ||||
-rw-r--r-- | doc/ref/api-init.texi | 6 | ||||
-rw-r--r-- | doc/ref/posix.texi | 74 | ||||
-rw-r--r-- | doc/ref/srfi-modules.texi | 75 |
6 files changed, 158 insertions, 32 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index 8b8e0befe..9ffa06b25 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,32 @@ +2007-01-16 Kevin Ryde <user42@zip.com.au> + + * api-data.texi (Mapping Folding and Unfolding): In string-unfold, + ssay make_final default is nothing extra. The `(lambda (x) )' shown + was not quite right, it would have been `(lambda (x) "")' if anything. + + * api-init.texi (Initialization): Cross reference Runtime Environment + for scm_set_program_arguments. + + * posix.texi (Runtime Environment): Expand program-arguments + description, add set-program-arguments, add scm_set_program_arguments, + note args are per-thread. + +2006-12-14 Kevin Ryde <user42@zip.com.au> + + * api-procedures.texi (let-keywords Reference): Expand variously to + make it clear what's actually taken and done. Shortfalls reported by + Han-Wen Nienhuys. + +2006-12-13 Kevin Ryde <user42@zip.com.au> + + * api-control.texi (Handling Errors): Cross reference "Error + Reporting" for `scm-error', not just "above". + + * posix.texi (Encryption): Cross reference crypt in the glibc manual. + Clarify that key and salt are strings. + + * srfi-modules.texi (SRFI-17): Expand variously. + 2006-11-18 Ludovic Courtès <ludovic.courtes@laas.fr> * Makefile.am (BUILT_SOURCES): New variable. diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index 11a276a13..512733cd5 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -1476,7 +1476,7 @@ In the following C functions, @var{SUBR} and @var{MESSAGE} parameters can be @code{NULL} to give the effect of @code{#f} described above. @deftypefn {C Function} SCM scm_error (SCM @var{key}, char *@var{subr}, char *@var{message}, SCM @var{args}, SCM @var{rest}) -Throw an error, as per @code{scm-error} above. +Throw an error, as per @code{scm-error} (@pxref{Error Reporting}). @end deftypefn @deftypefn {C Function} void scm_syserror (char *@var{subr}) diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index abcb28de1..0b31b15e3 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -3525,7 +3525,7 @@ string. @item @var{make_final} is applied to the terminal seed value (on which @var{p} returns true) to produce the final/rightmost portion of the constructed string. -It defaults to @code{(lambda (x) )}. +The default is nothing extra. @end itemize @end deffn diff --git a/doc/ref/api-init.texi b/doc/ref/api-init.texi index 26e6e71ef..0e4e8b8b7 100644 --- a/doc/ref/api-init.texi +++ b/doc/ref/api-init.texi @@ -1,12 +1,13 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @node Initialization @section Initializing Guile +@cindex Initializing Guile Each thread that wants to use functions from the Guile API needs to put itself into guile mode with either @code{scm_with_guile} or @@ -93,7 +94,8 @@ The function @code{scm_boot_guile} arranges for the Scheme @code{command-line} function to return the strings given by @var{argc} and @var{argv}. If @var{main_func} modifies @var{argc} or @var{argv}, it should call @code{scm_set_program_arguments} with the final list, so -Scheme code will know which arguments have been processed. +Scheme code will know which arguments have been processed +(@pxref{Runtime Environment}). @end deftypefn @deftypefn {C Function} void scm_shell (int @var{argc}, char **@var{argv}) diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index 6f496fe8d..31ca20b0d 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -1348,15 +1348,72 @@ included but subprocesses are not. @deffn {Scheme Procedure} program-arguments @deffnx {Scheme Procedure} command-line +@deffnx {Scheme Procedure} set-program-arguments @deffnx {C Function} scm_program_arguments () +@deffnx {C Function} scm_set_program_arguments_scm (lst) @cindex command line @cindex program arguments -Return the list of command line arguments passed to Guile, as a list of -strings. The list includes the invoked program name, which is usually -@code{"guile"}, but excludes switches and parameters for command line -options like @code{-e} and @code{-l}. +Get the command line arguments passed to Guile, or set new arguments. + +The arguments are a list of strings, the first of which is the invoked +program name. This is just @nicode{"guile"} (or the executable path) +when run interactively, or it's the script name when running a script +with @option{-s} (@pxref{Invoking Guile}). + +@example +guile -L /my/extra/dir -s foo.scm abc def + +(program-arguments) @result{} ("foo.scm" "abc" "def") +@end example + +@code{set-program-arguments} allows a library module or similar to +modify the arguments, for example to strip options it recognises, +leaving the rest for the mainline. + +The argument list is held in a fluid, which means it's separate for +each thread. Neither the list nor the strings within it are copied at +any point and normally should not be mutated. + +The two names @code{program-arguments} and @code{command-line} are an +historical accident, they both do exactly the same thing. The name +@code{scm_set_program_arguments_scm} has an extra @code{_scm} on the +end to avoid clashing with the C function below. @end deffn +@deftypefn {C Function} void scm_set_program_arguments (int argc, char **argv, char *first) +@cindex command line +@cindex program arguments +Set the list of command line arguments for @code{program-arguments} +and @code{command-line} above. + +@var{argv} is an array of null-terminated strings, as in a C +@code{main} function. @var{argc} is the number of strings in +@var{argv}, or if it's negative then a @code{NULL} entry in @var{argv} +marks its end. + +@var{first} is an extra string put at the start of the arguments, or +@code{NULL} for no such extra. This is a convenient way to pass the +program name after advancing @var{argv} to strip option arguments. + +@example +@{ + char *progname = argv[0]; + int i; + for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++) + @{ + /* munch option ... */ + @} + /* remaining args for scheme level use */ + scm_set_program_arguments (-1, argv, progname); +@} +@end example + +This sort of thing is often done at startup under +@code{scm_boot_guile} with any options handled at the C level removed. +The given strings are all copied, so the C data is not accessed again +once @code{scm_set_program_arguments} returns. +@end deftypefn + @deffn {Scheme Procedure} getenv nam @deffnx {C Function} scm_getenv (nam) @cindex environment @@ -3174,12 +3231,13 @@ Please note that the procedures in this section are not suited for strong encryption, they are only interfaces to the well-known and common system library functions of the same name. They are just as good (or bad) as the underlying functions, so you should refer to your system -documentation before using them. +documentation before using them (@pxref{crypt,, Encrypting Passwords, +libc, The GNU C Library Reference Manual}). @deffn {Scheme Procedure} crypt key salt @deffnx {C Function} scm_crypt (key, salt) -Encrypt @var{key} using @var{salt} as the salt value to the -crypt(3) library call. +Encrypt @var{key}, with the addition of @var{salt} (both strings), +using the @code{crypt} C library call. @end deffn Although @code{getpass} is not an encryption procedure per se, it diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 8a027c00b..61c105c5b 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -1616,24 +1616,61 @@ applied to zero arguments, yields 1. @subsection SRFI-17 - Generalized set! @cindex SRFI-17 -This is an implementation of SRFI-17: Generalized set! - -@findex getter-with-setter -It exports the Guile procedure @code{make-procedure-with-setter} under -the SRFI name @code{getter-with-setter} and exports the standard -procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr}, -@code{string-ref} and @code{vector-ref} as procedures with setters, as -required by the SRFI. - -SRFI-17 was heavily criticized during its discussion period but it was -finalized anyway. One issue was its concept of globally associating -setter @dfn{properties} with (procedure) values, which is non-Schemy. -For this reason, this implementation chooses not to provide a way to set -the setter of a procedure. In fact, @code{(set! (setter @var{proc}) -@var{setter})} signals an error. The only way to attach a setter to a -procedure is to create a new object (a @dfn{procedure with setter}) via -the @code{getter-with-setter} procedure. This procedure is also -specified in the SRFI. Using it avoids the described problems. +This SRFI implements a generalized @code{set!}, allowing some +``referencing'' functions to be used as the target location of a +@code{set!}. This feature is available from + +@example +(use-modules (srfi srfi-17)) +@end example + +@noindent +For example @code{vector-ref} is extended so that + +@example +(set! (vector-ref vec idx) new-value) +@end example + +@noindent +is equivalent to + +@example +(vector-set! vec idx new-value) +@end example + +The idea is that a @code{vector-ref} expression identifies a location, +which may be either fetched or stored. The same form is used for the +location in both cases, encouraging visual clarity. This is similar +to the idea of an ``lvalue'' in C. + +The mechanism for this kind of @code{set!} is in the Guile core +(@pxref{Procedures with Setters}). This module adds definitions of +the following functions as procedures with setters, allowing them to +be targets of a @code{set!}, + +@quotation +@nicode{car}, @nicode{cdr}, @nicode{caar}, @nicode{cadr}, +@nicode{cdar}, @nicode{cddr}, @nicode{caaar}, @nicode{caadr}, +@nicode{cadar}, @nicode{caddr}, @nicode{cdaar}, @nicode{cdadr}, +@nicode{cddar}, @nicode{cdddr}, @nicode{caaaar}, @nicode{caaadr}, +@nicode{caadar}, @nicode{caaddr}, @nicode{cadaar}, @nicode{cadadr}, +@nicode{caddar}, @nicode{cadddr}, @nicode{cdaaar}, @nicode{cdaadr}, +@nicode{cdadar}, @nicode{cdaddr}, @nicode{cddaar}, @nicode{cddadr}, +@nicode{cdddar}, @nicode{cddddr} + +@nicode{string-ref}, @nicode{vector-ref} +@end quotation + +The SRFI specifies @code{setter} (@pxref{Procedures with Setters}) as +a procedure with setter, allowing the setter for a procedure to be +changed, eg.@: @code{(set! (setter foo) my-new-setter-handler)}. +Currently Guile does not implement this, a setter can only be +specified on creation (@code{getter-with-setter} below). + +@defun getter-with-setter +The same as the Guile core @code{make-procedure-with-setter} +(@pxref{Procedures with Setters}). +@end defun @node SRFI-19 |