guile/guile-core/doc ChangeLog posix.texi schem...

[Neil Jerram]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Neil Jerram <address@hidden>    01/05/19 04:13:47

Modified files:
        guile-core/doc : ChangeLog posix.texi scheme-control.texi 

Log message:
        * Doc updates for lazy-catch and IP address conversion

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/ChangeLog.diff?cvsroot=OldCVS&tr1=1.90&tr2=1.91&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/posix.texi.diff?cvsroot=OldCVS&tr1=1.8&tr2=1.9&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/doc/scheme-control.texi.diff?cvsroot=OldCVS&tr1=1.14&tr2=1.15&r1=text&r2=text

Patches:
Index: guile/guile-core/doc/ChangeLog
diff -u guile/guile-core/doc/ChangeLog:1.90 guile/guile-core/doc/ChangeLog:1.91
--- guile/guile-core/doc/ChangeLog:1.90 Wed May 16 12:30:57 2001
+++ guile/guile-core/doc/ChangeLog      Sat May 19 04:13:47 2001
@@ -1,3 +1,11 @@
+2001-05-19  Neil Jerram  <address@hidden>
+
+       * posix.texi (Networking): Split existing material into new nodes
+       `Network Address Conversion' and `Network Databases'.
+
+       * scheme-control.texi (Lazy Catch): Update doc for new constraint
+       that lazy-catch handlers are not allowed to return.
+
 2001-05-16  Neil Jerram  <address@hidden>
 
        * data-rep.texi, srfi-modules.texi (SRFI-14 Iterating Over
Index: guile/guile-core/doc/posix.texi
diff -u guile/guile-core/doc/posix.texi:1.8 guile/guile-core/doc/posix.texi:1.9
--- guile/guile-core/doc/posix.texi:1.8 Wed May 16 11:08:12 2001
+++ guile/guile-core/doc/posix.texi     Sat May 19 04:13:47 2001
@@ -1542,18 +1542,18 @@
 @section Networking
 
 @menu
-* Network Databases and Address Conversion::  
+* Network Address Conversion::
+* Network Databases::  
 * Network Sockets and Communication::  
 @end menu
 
address@hidden Network Databases and Address Conversion
address@hidden Network Databases and Address Conversion
address@hidden Network Address Conversion
address@hidden Network Address Conversion
 
 This section describes procedures which convert internet addresses
-and query various network databases.  Care should be taken when using
-the database routines since they are not reentrant.
+between numeric and string formats.
 
address@hidden Address Conversion
address@hidden IPv4 Address Conversion
 
 @deffn primitive inet-aton address
 Convert an IPv4 Internet address from printable string
@@ -1629,6 +1629,14 @@
 (inet-pton AF_INET6 "::1") @result{} 1
 @end lisp
 @end deffn
+
+
address@hidden Network Databases
address@hidden Network Databases
+
+This section describes procedures which query various network databases.
+Care should be taken when using the database routines since they are not
+reentrant.
 
 @subsubsection The Host Database
 
Index: guile/guile-core/doc/scheme-control.texi
diff -u guile/guile-core/doc/scheme-control.texi:1.14 
guile/guile-core/doc/scheme-control.texi:1.15
--- guile/guile-core/doc/scheme-control.texi:1.14       Wed May 16 12:30:57 2001
+++ guile/guile-core/doc/scheme-control.texi    Sat May 19 04:13:47 2001
@@ -602,28 +602,25 @@
 A @dfn{lazy catch} is used in the same way as a normal @code{catch},
 with @var{key}, @var{thunk} and @var{handler} arguments specifying the
 exception type, normal case code and handler procedure, but differs in
-two important respects.
+one important respect: the handler procedure is executed without
+unwinding the call stack from the context of the @code{throw} expression
+that caused the handler to be invoked.
 
address@hidden @bullet
address@hidden
-The handler procedure is executed without unwinding the call stack from
-the context of the @code{throw} expression that caused the handler to be
-invoked.
-
address@hidden
-If the handler returns normally --- i.e. does not @emph{itself} throw an
-exception --- then the @code{throw} expression returns normally to its
-caller with the handler's value.
address@hidden itemize
-
 @deffn primitive lazy-catch key thunk handler
 This behaves exactly like @code{catch}, except that it does
-not unwind the stack (this is the major difference), and if
-handler returns, its value is returned from the throw.
+not unwind the stack before invoking @var{handler}.
+The @var{handler} procedure is not allowed to return:
+it must throw to another catch, or otherwise exit non-locally.
 @end deffn
+
+Typically, @var{handler} should save any desired state associated with
+the stack at the point where the corresponding @code{throw} occurred,
+and then throw an exception itself --- usually the same exception as the
+one it caught.  If @var{handler} is invoked and does @emph{not} throw an
+exception, Guile itself throws an exception with key @code{misc-error}.
 
-The net result is that throwing an exception that is caught by a
address@hidden is @emph{almost} equivalent to calling the
+Not unwinding the stack means that throwing an exception that is caught
+by a @code{lazy-catch} is @emph{almost} equivalent to calling the
 @code{lazy-catch}'s handler inline instead of each @code{throw}, and
 then omitting the surrounding @code{lazy-catch}.  In other words,
 
@@ -642,37 +639,20 @@
 
 @noindent
 But why only @emph{almost}?  The difference is that with
address@hidden, the dynamic context is unwound back to just outside
-the @code{lazy-catch} expression before invoking the handler.  (For an
-introduction to what is meant by dynamic context, @xref{Dynamic Wind}.)
address@hidden (as with normal @code{catch}), the dynamic context is
+unwound back to just outside the @code{lazy-catch} expression before
+invoking the handler.  (For an introduction to what is meant by dynamic
+context, @xref{Dynamic Wind}.)
 
-Then, if the handler @emph{itself} throws an exception, that exception
+Then, when the handler @emph{itself} throws an exception, that exception
 must be caught by some kind of @code{catch} (including perhaps another
address@hidden) higher up the call stack.  On the other hand, if the
-handler returns normally, the dynamic context is wound back to that of
-the @code{throw} expression before passing the handler's return value to
-the continuation of the @code{throw}.
-
-In most cases where @code{lazy-catch} is used, the handler does indeed
-throw another exception, which is caught by a higher-level @code{catch}.
-But this pattern is not mandatory, and it can be useful for the handler
-to return normally.  In the following example, the @code{lazy-catch}
-handler is called twice and the results of the two calls added together.
-
address@hidden
-(lazy-catch 'foo
-            (lambda ()
-              (+ (throw 'foo 1)
-                 (throw 'foo 2)))
-            (lambda args
-              (cadr args)))
address@hidden
-3
address@hidden lisp
address@hidden) higher up the call stack.
 
-To see the point about dynamic context, consider the case where the
-normal case thunk uses @code{with-fluids} (REFFIXME) to temporarily
-change the value of a fluid:
+The dynamic context also includes @code{with-fluids} blocks (REFFIXME),
+so the effect of unwinding the dynamic context can also be seen in fluid
+variable values.  This is illustrated by the following code, in which
+the normal case thunk uses @code{with-fluids} to temporarily change the
+value of a fluid:
 
 @lisp
 (define f (make-fluid))