diff options
author | Kevin Ryde <user42@zip.com.au> | 2004-07-24 00:08:47 +0000 |
---|---|---|
committer | Kevin Ryde <user42@zip.com.au> | 2004-07-24 00:08:47 +0000 |
commit | 5eef0f619ad131dc7054abf5685649df0ec91811 (patch) | |
tree | 701db28aff9515f94388165988a85ae1b9b893f7 | |
parent | 33bea692e5193750d76882d065ba1f77c56ffa94 (diff) | |
download | guile-5eef0f619ad131dc7054abf5685649df0ec91811.tar.gz |
(SRFI-0): Revise for clarity, drop BNF in favour
of plain description, emphasise this is just for portable programs.
-rw-r--r-- | doc/ref/srfi-modules.texi | 127 |
1 files changed, 49 insertions, 78 deletions
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index f67544946..cecb1664a 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -77,100 +77,71 @@ automatically (@pxref{Invoking Guile}). @node SRFI-0 @subsection SRFI-0 - cond-expand @cindex SRFI-0 -@findex cond-expand -@c FIXME::martin: Review me! - -SRFI-0 defines a means for checking whether a Scheme implementation has -support for a specified feature. The syntactic form @code{cond-expand}, -which implements this means, has the following syntax. - -@example -@group -<cond-expand> - --> (cond-expand <cond-expand-clause>+) - | (cond-expand <cond-expand-clause>* (else <command-or-definition>)) -<cond-expand-clause> - --> (<feature-requirement> <command-or-definition>*) -<feature-requirement> - --> <feature-identifier> - | (and <feature-requirement>*) - | (or <feature-requirement>*) - | (not <feature-requirement>) -<feature-identifier> - --> <a symbol which is the name or alias of a SRFI> -@end group -@end example +This SRFI lets a portable Scheme program test for the presence of +certain features, and adapt itself by using different blocks of code, +or fail if the necessary features are not available. There's no +module to load, this is in the Guile core. -When evaluated, this form checks all clauses in order, until it finds -one whose feature requirement is satisfied. Then the form expands into -the commands or definitions in the clause. A requirement is tested as -follows: - -@itemize @bullet -@item -If it is a symbol, it is satisfied if the feature identifier is -supported. - -@item -If it is an @code{and} form, all requirements must be satisfied. If no -requirements are given, it is satisfied, too. - -@item -If it is an @code{or} form, at least one of the requirements must be -satisfied. If no requirements are given, it is not satisfied. +A program designed only for Guile will generally not need this +mechanism, such a program can of course directly use the various +documented parts of Guile. -@item -If it is a @code{not} form, the feature requirement must @emph{not} be +@deffn syntax cond-expand (feature body@dots{}) @dots{} +Expand to the @var{body} of the first clause whose @var{feature} +specification is satisfied. It is an error if no @var{feature} is satisfied. -@item -If the feature requirement is the keyword @code{else} and it is the last -clause, it is satisfied if no prior clause matched. -@end itemize +Features are symbols such as @code{srfi-1}, and a feature +specification can use @code{and}, @code{or} and @code{not} forms to +test combinations. The last clause can be an @code{else}, to be used +if no other passes. -If no clause is satisfied, an error is signalled. +For example, define a private version of @code{alist-cons} if SRFI-1 +is not available. -Since @code{cond-expand} is needed to tell what a Scheme implementation -provides, it must be accessible without using any -implementation-dependent operations, such as @code{use-modules} in -Guile. Thus, it is not necessary to use any module to get access to -this form. +@example +(cond-expand (srfi-1 + ) + (else + (define (alist-cons key val alist) + (cons (cons key val) alist)))) +@end example -Currently, the feature identifiers @code{guile}, @code{r5rs}, @code{srfi-0} and -@code{srfi-6} are supported. The other SRFIs are not in that list by -default, because the SRFI modules must be explicitly used before their -exported bindings can be used. +Or demand a certain set of SRFIs (list operations, string ports, +@code{receive} and string operations), failing if they're not +available. -So if a Scheme program wishes to use SRFI-8, it has two possibilities: -First, it can check whether the running Scheme implementation is Guile, -and if it is, it can use the appropriate module: +@example +(cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13) + )) +@end example +@end deffn -@lisp -(cond-expand - (guile - (use-modules (srfi srfi-8))) - (srfi-8 - #t)) - ;; otherwise fail. -@end lisp +The Guile core provides features @code{guile}, @code{r5rs}, +@code{srfi-0} and @code{srfi-6} initially. Other SRFI feature symbols +are defined once their code has been loaded with @code{use-modules}, +since only then are their bindings available. -The other possibility is to use the @code{--use-srfi} command line -option when invoking Guile (@pxref{Invoking Guile}). When you do that, -the specified SRFI support modules will be loaded and add their feature -identifier to the list of symbols checked by @code{cond-expand}. +The @samp{--use-srfi} command line option (@pxref{Invoking Guile}) is +a good way to load SRFIs to satisfy @code{cond-expand} when running a +portable program. -So, if you invoke Guile like this: +Testing the @code{guile} feature allows a program to adapt itself to +the Guile module system, but still run on other Scheme systems. For +example the following demands SRFI-8 (@code{receive}), but also knows +how to load it with the Guile mechanism. @example -$ guile --use-srfi=8 +(cond-expand (srfi-8 + ) + (guile + (use-modules (srfi srfi-8)))) @end example -the following snippet will expand to @code{'hooray}. - -@lisp -(cond-expand (srfi-8 'hooray)) -@end lisp +It should be noted that @code{cond-expand} is separate from the +@code{*features*} mechanism (@pxref{Feature Tracking}), feature +symbols in one are unrelated to those in the other. @node SRFI-1 |