From f50ca8da5bedd4a9efddf3005c9b73ade9873c99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Sat, 11 Aug 2007 10:08:10 +0000 Subject: [PATCH] Changes from arch/CVS synchronization --- ChangeLog | 4 + NEWS | 1 + doc/ref/ChangeLog | 5 + doc/ref/srfi-modules.texi | 192 ++++++++++++++++++++++++++++++++++++++ srfi/ChangeLog | 5 + srfi/Makefile.am | 1 + test-suite/ChangeLog | 5 + test-suite/Makefile.am | 3 +- 8 files changed, 215 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index a41c3935a..dff475721 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2007-08-11 Ludovic Courtès + + * NEWS: Mention SRFI-35. + 2007-08-08 Ludovic Courtès * NEWS: Mention changes to `record-accessor' and diff --git a/NEWS b/NEWS index 11d04ea03..349369c14 100644 --- a/NEWS +++ b/NEWS @@ -36,6 +36,7 @@ Changes in 1.8.3 (since 1.8.2) * New modules (see the manual for details) +** `(srfi srfi-35)' ** `(srfi srfi-37)' * Bugs fixed diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index fc2840d55..eb90c711a 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,8 @@ +2007-08-11 Ludovic Courtès + + * srfi-modules.texi (SRFI-34): New node. + (SRFI-35): New node. + 2007-07-18 Stephen Compall * srfi-modules.texi: Describe SRFI-37 in a new subsection. diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index c71578dab..cacd769c2 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -37,6 +37,8 @@ get the relevant SRFI documents from the SRFI home page * SRFI-19:: Time/Date library. * SRFI-26:: Specializing parameters * SRFI-31:: A special form `rec' for recursive evaluation +* SRFI-34:: Exception handling. +* SRFI-35:: Conditions. * SRFI-37:: args-fold program argument processor * SRFI-39:: Parameter objects * SRFI-55:: Requiring Features. @@ -2402,6 +2404,196 @@ The second syntax can be used to create anonymous recursive functions: @end lisp +@node SRFI-34 +@subsection SRFI-34 - Exception handling for programs + +@cindex SRFI-34 +Guile provides an implementation of +@uref{http://srfi.schemers.org/srfi-34/srfi-34.html, SRFI-34's exception +handling mechanisms} as an alternative to its own built-in mechanisms +(@pxref{Exceptions}). It can be made available as follows: + +@lisp +(use-modules (srfi srfi-34)) +@end lisp + +@c FIXME: Document it. + + +@node SRFI-35 +@subsection SRFI-35 - Conditions + +@cindex SRFI-35 +@cindex conditions +@cindex exceptions + +@uref{http://srfi.schemers.org/srfi-35/srfi-35.html, SRFI-35} implements +@dfn{conditions}, a data structure akin to records designed to convey +information about exceptional conditions between parts of a program. It +is normally used in conjunction with SRFI-34's @code{raise}: + +@lisp +(raise (condition (&message + (message "An error occurred")))) +@end lisp + +Users can define @dfn{condition types} containing arbitrary information. +Condition types may inherit from one another. This allows the part of +the program that handles (or ``catches'') conditions to get accurate +information about the exceptional condition that arose. + +SRFI-35 conditions are made available using: + +@lisp +(use-modules (srfi srfi-35)) +@end lisp + +The procedures available to manipulate condition types are the +following: + +@deffn {Scheme Procedure} make-condition-type id parent field-names +Return a new condition type named @var{id}, inheriting from +@var{parent}, and with the fields whose names are listed in +@var{field-names}. @var{field-names} must be a list of symbols and must +not contain names already used by @var{parent} or one of its supertypes. +@end deffn + +@deffn {Scheme Procedure} condition-type? obj +Return true if @var{obj} is a condition type. +@end deffn + +Conditions can be created and accessed with the following procedures: + +@deffn {Scheme Procedure} make-condition type . field+value +Return a new condition of type @var{type} with fields initialized as +specified by @var{field+value}, a sequence of field names (symbols) and +values as in the following example: + +@lisp +(let* ((&ct (make-condition-type 'foo &condition '(a b c)))) + (make-condition &ct 'a 1 'b 2 'c 3)) +@end lisp + +Note that all fields of @var{type} and its supertypes must be specified. +@end deffn + +@deffn {Scheme Procedure} make-compound-condition . conditions +Return a new compound condition composed of @var{conditions}. The +returned condition has the type of each condition of @var{conditions} +(per @code{condition-has-type?}). +@end deffn + +@deffn {Scheme Procedure} condition-has-type? c type +Return true if condition @var{c} has type @var{type}. +@end deffn + +@deffn {Scheme Procedure} condition-ref c field-name +Return the value of the field named @var{field-name} from condition @var{c}. + +If @var{c} is a compound condition and several underlying condition +types contain a field named @var{field-name}, then the value of the +first such field is returned, using the order in which conditions were +passed to @var{make-compound-condition}. +@end deffn + +@deffn {Scheme Procedure} extract-condition c type +Return a condition of condition type @var{type} with the field values +specified by @var{c}. + +If @var{c} is a compound condition, extract the field values from the +subcondition belonging to @var{type} that appeared first in the call to +@code{make-compound-condition} that created the the condition. +@end deffn + +Convenience macros are also available to create condition types and +conditions. + +@deffn {library syntax} define-condition-type type supertype predicate field-spec... +Define a new condition type named @var{type} that inherits from +@var{supertype}. In addition, bind @var{predicate} to a type predicate +that returns true when passed a condition of type @var{type} or any of +its subtypes. @var{field-spec} must have the form @code{(field +accessor)} where @var{field} is the name of field of @var{type} and +@var{accessor} is the name of a procedure to access field @var{field} in +conditions of type @var{type}. + +The example below defines condition type @code{&foo}, inheriting from +@code{&condition} with fields @code{a}, @code{b} and @code{c}: + +@lisp +(define-condition-type &foo &condition + foo-condition? + (a foo-a) + (b foo-b) + (c foo-c)) +@end lisp +@end deffn + +@deffn {library syntax} condition type-field-bindings... +Return a new condition, or compound condition, initialized according to +@var{type-field-bindings}. Each @var{type-field-binding} must have the +form @code{(type field-specs...)}, where @var{type} is the name of a +variable bound to condition type; each @var{field-spec} must have the +form @code{(field-name value)} where @var{field-name} is a symbol +denoting the field being initialized to @var{value}. As for +@code{make-condition}, all fields must be specified. + +The following example returns a simple condition: + +@lisp +(condition (&message (message "An error occurred"))) +@end lisp + +The one below returns a compound condition: + +@lisp +(condition (&message (message "An error occurred")) + (&serious)) +@end lisp +@end deffn + +Finally, SRFI-35 defines a several standard condition types. + +@defvar &condition +This condition type is the root of all condition types. It has no +fields. +@end defvar + +@defvar &message +A condition type that carries a message describing the nature of the +condition to humans. +@end defvar + +@deffn {Scheme Procedure} message-condition? c +Return true if @var{c} is of type @code{&message} or one of its +subtypes. +@end deffn + +@deffn {Scheme Procedure} condition-message c +Return the message associated with message condition @var{c}. +@end deffn + +@defvar &serious +This type describes conditions serious enough that they cannot safely be +ignored. It has no fields. +@end defvar + +@deffn {Scheme Procedure} serious-condition? c +Return true if @var{c} is of type @code{&serious} or one of its +subtypes. +@end deffn + +@defvar &error +This condition describes errors, typically caused by something that has +gone wrong in the interaction of the program with the external world or +the user. +@end defvar + +@deffn {Scheme Procedure} error? c +Return true if @var{c} is of type @code{&error} or one of its subtypes. +@end deffn + + @node SRFI-37 @subsection SRFI-37 - args-fold @cindex SRFI-37 diff --git a/srfi/ChangeLog b/srfi/ChangeLog index cd04e7508..551c2fc1b 100644 --- a/srfi/ChangeLog +++ b/srfi/ChangeLog @@ -1,3 +1,8 @@ +2007-08-11 Ludovic Courtès + + * srfi-35.scm: New file. + * Makefile.am (srfi_DATA): Added `srfi-35.scm'. + 2007-07-29 Ludovic Courtès * Makefile.am (INCLUDES): Added Gnulib includes. diff --git a/srfi/Makefile.am b/srfi/Makefile.am index 359c19ba2..8f5976e5c 100644 --- a/srfi/Makefile.am +++ b/srfi/Makefile.am @@ -79,6 +79,7 @@ srfi_DATA = srfi-1.scm \ srfi-26.scm \ srfi-31.scm \ srfi-34.scm \ + srfi-35.scm \ srfi-37.scm \ srfi-39.scm \ srfi-60.scm diff --git a/test-suite/ChangeLog b/test-suite/ChangeLog index ee8e37795..6fe9282a9 100644 --- a/test-suite/ChangeLog +++ b/test-suite/ChangeLog @@ -1,3 +1,8 @@ +2007-08-11 Ludovic Courtès + + * tests/srfi-35.test: New file. + * Makefile.am (SCM_TESTS): Added `tests/srfi-35.test'. + 2007-08-08 Ludovic Courtès * tests/srfi-9.test (exception:not-a-record): Removed. diff --git a/test-suite/Makefile.am b/test-suite/Makefile.am index 11e8900e0..34ac1ff07 100644 --- a/test-suite/Makefile.am +++ b/test-suite/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with automake to produce Makefile.in. ## -## Copyright 2001, 2002, 2003, 2004, 2005, 2006 Software Foundation, Inc. +## Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007 Software Foundation, Inc. ## ## This file is part of GUILE. ## @@ -76,6 +76,7 @@ SCM_TESTS = tests/alist.test \ tests/srfi-26.test \ tests/srfi-31.test \ tests/srfi-34.test \ + tests/srfi-35.test \ tests/srfi-37.test \ tests/srfi-39.test \ tests/srfi-60.test \