doc srfi-0 cond-expand

[Kevin Ryde]

Some new words below for cond-expand, a bit more concise, and
emphasising that this is really meant for a portable scheme program.
A couple more examples would be good, if anyone can think of something
vaguely realistic.



2.1.1 SRFI-0 - cond-expand
--------------------------

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.

   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.

 -- syntax: cond-expand (feature body...) ...
     Expand to the BODY of the first clause whose FEATURE specification
     is satisfied.  It is an error if no FEATURE is satisfied.

     Features are symbols such as `srfi-1', and a feature specification
     can use `and', `or' and `not' forms to test combinations.  The
     last clause can be an `else', to be used if no other passes.

     For example, define a private version of `alist-cons' if SRFI-1 is
     not available.

          (cond-expand (srfi-1
                        )
                       (else
                        (define (alist-cons key val alist)
                          (cons (cons key val) alist))))

     Or demand a certain set of SRFIs (list operations, string ports,
     `receive' and string operations), failing if they're not available.

          (cond-expand ((and srfi-1 srfi-6 srfi-8 srfi-13)
                        ))

   The Guile core defines features `guile', `r5rs', `srfi-0' and
`srfi-6' initially.  Other SRFI feature symbols are defined once their
code has been loaded with `use-modules', since only then are their
bindings available.

   The `--use-srfi' command line option (*note Invoking Guile::) is a
good way to load SRFIs to satisfy `cond-expand' when running a portable
program.

   Testing the `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 (`receive'), but also knows how to
load it with the Guile mechanism.

     (cond-expand (srfi-8
                   )
                  (guile
                   (use-modules (srfi srfi-8))))

   It should be noted that `cond-expand' is separate from the
`*features*' mechanism (*note Feature Tracking::).  Feature symbols in
one mechanism are unrelated to those in the other.