>From 0cb77a1b15db2f88829879187bd28e42822704be Mon Sep 17 00:00:00 2001 From: David Kastrup Date: Sun, 11 May 2014 14:21:13 +0200 Subject: [PATCH 3/3] Document semantics and API of (values)/*unspecified* --- doc/ref/api-compound.texi | 4 ++-- doc/ref/api-control.texi | 10 ++++++++-- doc/ref/data-rep.texi | 20 +++++++++++++++----- libguile/values.c | 5 ++++- 4 files changed, 29 insertions(+), 10 deletions(-) diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index 055de99..30d9691 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -1359,8 +1359,8 @@ array that uses a @code{f64vector} for storing its elements, and When @var{fill} is not the special @emph{unspecified} value, the new array is filled with @var{fill}. Otherwise, the initial contents of the array is unspecified. The special @emph{unspecified} value is -stored in the variable @code{*unspecified*} so that for example address@hidden(make-typed-array 'u32 *unspecified* 4)} creates a uninitialized +available as @code{*unspecified*} so that for example address@hidden(make-typed-array 'u32 *unspecified* 4)} creates an uninitialized @code{u32} vector of length 4. Each @var{bound} may be a positive non-zero integer @var{n}, in which diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index 4253a20..3612693 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -882,7 +882,13 @@ Delivers all of its arguments to its continuation. Except for continuations created by the @code{call-with-values} procedure, all continuations take exactly one value. The effect of passing no value or more than one value to continuations that -were not created by @code{call-with-values} is unspecified. +were not created by @code{call-with-values} is unspecified by the Scheme +standard. + +Guile's behavior in that case is to drop all but the first value when +given more than one value, and to use @code{*unspecified*} +(@code{SCM_UNSPECIFIED} address@hidden) as an identifiable single-value +representation of @code{(values)}. For @code{scm_values}, @var{args} is a list of arguments and the return is a multiple-values object which the caller can return. In @@ -902,7 +908,7 @@ representation. @deftypefn {C Function} size_t scm_c_nvalues (SCM obj) If @var{obj} is a multiple-values object, returns the number of values -it contains. Otherwise returns 1. +it contains. It returns 0 for @code{SCM_UNSPECIFIED}, and 1 otherwise. @end deftypefn @deftypefn {C Function} SCM scm_c_value_ref (SCM obj, size_t idx) diff --git a/doc/ref/data-rep.texi b/doc/ref/data-rep.texi index d0a76e9..5a6e055 100644 --- a/doc/ref/data-rep.texi +++ b/doc/ref/data-rep.texi @@ -444,12 +444,22 @@ representation, for obvious reasons. @deftypefn Macro SCM SCM_UNSPECIFIED The value returned by some (but not all) expressions that the Scheme -standard says return an ``unspecified'' value. +standard says return an ``unspecified'' value. From Scheme, it is +available as @code{*unspecified*} and is the representation of address@hidden(values)}, a `multi-valued' expression without value. + +As such, the standard read-eval-print loop prints nothing when some +expression returns this value, so it's not a bad idea to return this +when you can't think of anything else helpful. + address@hidden differs from calls of @code{values} with multiple +arguments in that it can serve as a first-class value, be stored in +variables, compared with @code{eq?} and used in other single-value +contexts. + +The Scheme standard neither provides an @code{*unspecified*} value, nor +does it define the behavior of @code{(values)} in single-value contexts. -This is sort of a weirdly literal way to take things, but the standard -read-eval-print loop prints nothing when the expression returns this -value, so it's not a bad idea to return this when you can't think of -anything else helpful. @end deftypefn @deftypefn Macro SCM SCM_UNDEFINED diff --git a/libguile/values.c b/libguile/values.c index 12c79d5..541f55f 100644 --- a/libguile/values.c +++ b/libguile/values.c @@ -109,7 +109,10 @@ SCM_DEFINE (scm_values, "values", 0, 0, 1, "continuations created by the @code{call-with-values} procedure,\n" "all continuations take exactly one value. The effect of\n" "passing no value or more than one value to continuations that\n" - "were not created by @code{call-with-values} is unspecified.") + "were not created by @code{call-with-values} is unspecified by\n" + "the Scheme standard.\n\n" + "Guile in that case uses the first of multiple values,\n" + "or @code{*unspecified*} when given no value.") #define FUNC_NAME s_scm_values { long n; -- 1.9.1