\f
Changes since Guile 1.3:
-* Changes to the stand-alone interpreter
+* Changes to the distribution
+
+** Readline support is no longer included with Guile by default.
+
+Based on the different license terms of Guile and Readline, we
+concluded that Guile should not *by default* cause the linking of
+Readline into an application program. Readline support is now offered
+as a separate module, which is linked into an application only when
+you explicitly specify it.
-** New options interface: readline-options,
-readline-enable, readline-disable, readline-set!
+Although Guile is GNU software, its distribution terms add a special
+exception to the usual GNU General Public License (GPL). Guile's
+license includes a clause that allows you to link Guile with non-free
+programs. We add this exception so as not to put Guile at a
+disadvantage vis-a-vis other extensibility packages that support other
+languages.
-** Command line history is now restored from and saved to file
+In contrast, the GNU Readline library is distributed under the GNU
+General Public License pure and simple. This means that you may not
+link Readline, even dynamically, into an application unless it is
+distributed under a free software license that is compatible the GPL.
-If readline is used and the readline option `history-file' is enabled,
-the command line history is read from file when the interpreter is
-entered, and written to file on exit. The filename used can be
-specified with the environment variable GUILE_HISTORY. Default file
-name is "$HOME/.guile_history". Nothing special happens if errors
-occur during read or write.
+Because of this difference in distribution terms, an application that
+can use Guile may not be able to use Readline. Now users will be
+explicitly offered two independent decisions about the use of these
+two packages.
-** Command line history length can now be customized.
-Command line history length is now controlled by the readline option
-`history-length'. Default is 200 lines.
+* Changes to the stand-alone interpreter
** All builtins now print as primitives.
Previously builtin procedures not belonging to the fundamental subr
* Changes to Scheme functions and syntax
+** New module (ice-9 getopt-long), with the function `getopt-long'.
+
+getopt-long is a function for parsing command-line arguments in a
+manner consistent with other GNU programs.
+
+(getopt-long ARGS GRAMMAR)
+Parse the arguments ARGS according to the argument list grammar GRAMMAR.
+
+ARGS should be a list of strings. Its first element should be the
+name of the program; subsequent elements should be the arguments
+that were passed to the program on the command line. The
+`program-arguments' procedure returns a list of this form.
+
+GRAMMAR is a list of the form:
+((OPTION (PROPERTY VALUE) ...) ...)
+
+Each OPTION should be a symbol. `getopt-long' will accept a
+command-line option named `--OPTION'.
+Each option can have the following (PROPERTY VALUE) pairs:
+
+ (single-char CHAR) --- Accept `-CHAR' as a single-character
+ equivalent to `--OPTION'. This is how to specify traditional
+ Unix-style flags.
+ (required? BOOL) --- If BOOL is true, the option is required.
+ getopt-long will raise an error if it is not found in ARGS.
+ (value BOOL) --- If BOOL is #t, the option accepts a value; if
+ it is #f, it does not; and if it is the symbol
+ `optional', the option may appear in ARGS with or
+ without a value.
+ (predicate FUNC) --- If the option accepts a value (i.e. you
+ specified `(value #t)' for this option), then getopt
+ will apply FUNC to the value, and throw an exception
+ if it returns #f. FUNC should be a procedure which
+ accepts a string and returns a boolean value; you may
+ need to use quasiquotes to get it into GRAMMAR.
+
+The (PROPERTY VALUE) pairs may occur in any order, but each
+property may occur only once. By default, options do not have
+single-character equivalents, are not required, and do not take
+values.
+
+In ARGS, single-character options may be combined, in the usual
+Unix fashion: ("-x" "-y") is equivalent to ("-xy"). If an option
+accepts values, then it must be the last option in the
+combination; the value is the next argument. So, for example, using
+the following grammar:
+ ((apples (single-char #\a))
+ (blimps (single-char #\b) (value #t))
+ (catalexis (single-char #\c) (value #t)))
+the following argument lists would be acceptable:
+ ("-a" "-b" "bang" "-c" "couth") ("bang" and "couth" are the values
+ for "blimps" and "catalexis")
+ ("-ab" "bang" "-c" "couth") (same)
+ ("-ac" "couth" "-b" "bang") (same)
+ ("-abc" "couth" "bang") (an error, since `-b' is not the
+ last option in its combination)
+
+If an option's value is optional, then `getopt-long' decides
+whether it has a value by looking at what follows it in ARGS. If
+the next element is a string, and it does not appear to be an
+option itself, then that string is the option's value.
+
+The value of a long option can appear as the next element in ARGS,
+or it can follow the option name, separated by an `=' character.
+Thus, using the same grammar as above, the following argument lists
+are equivalent:
+ ("--apples" "Braeburn" "--blimps" "Goodyear")
+ ("--apples=Braeburn" "--blimps" "Goodyear")
+ ("--blimps" "Goodyear" "--apples=Braeburn")
+
+If the option "--" appears in ARGS, argument parsing stops there;
+subsequent arguments are returned as ordinary arguments, even if
+they resemble options. So, in the argument list:
+ ("--apples" "Granny Smith" "--" "--blimp" "Goodyear")
+`getopt-long' will recognize the `apples' option as having the
+value "Granny Smith", but it will not recognize the `blimp'
+option; it will return the strings "--blimp" and "Goodyear" as
+ordinary argument strings.
+
+The `getopt-long' function returns the parsed argument list as an
+assocation list, mapping option names --- the symbols from GRAMMAR
+--- onto their values, or #t if the option does not accept a value.
+Unused options do not appear in the alist.
+
+All arguments that are not the value of any option are returned
+as a list, associated with the empty list.
+
+`getopt-long' throws an exception if:
+- it finds an unrecognized option in ARGS
+- a required option is omitted
+- an option that requires an argument doesn't get one
+- an option that doesn't accept an argument does get one (this can
+ only happen using the long option `--opt=value' syntax)
+- an option predicate fails
+
+So, for example:
+
+(define grammar
+ `((lockfile-dir (required? #t)
+ (value #t)
+ (single-char #\k)
+ (predicate ,file-is-directory?))
+ (verbose (required? #f)
+ (single-char #\v)
+ (value #f))
+ (x-includes (single-char #\x))
+ (rnet-server (single-char #\y)
+ (predicate ,string?))))
+
+(getopt-long '("my-prog" "-vk" "/tmp" "foo1" "--x-includes=/usr/include"
+ "--rnet-server=lamprod" "--" "-fred" "foo2" "foo3")
+ grammar)
+=> ((() "foo1" "-fred" "foo2" "foo3")
+ (rnet-server . "lamprod")
+ (x-includes . "/usr/include")
+ (lockfile-dir . "/tmp")
+ (verbose . #t))
+
+** The (ice-9 getopt-gnu-style) module is obsolete; use (ice-9 getopt-long).
+
+It will be removed in a few releases.
+
+** New syntax: lambda*
+** New syntax: define*
+** New syntax: define*-public
+** New syntax: defmacro*
+** New syntax: defmacro*-public
+Guile now supports optional arguments.
+
+`lambda*', `define*', `define*-public', `defmacro*' and
+`defmacro*-public' are identical to the non-* versions except that
+they use an extended type of parameter list that has the following BNF
+syntax (parentheses are literal, square brackets indicate grouping,
+and `*', `+' and `?' have the usual meaning):
+
+ ext-param-list ::= ( [identifier]* [#&optional [ext-var-decl]+]?
+ [#&key [ext-var-decl]+ [#&allow-other-keys]?]?
+ [[#&rest identifier]|[. identifier]]? ) | [identifier]
+
+ ext-var-decl ::= identifier | ( identifier expression )
+
+The semantics are best illustrated with the following documentation
+and examples for `lambda*':
+
+ lambda* args . body
+ lambda extended for optional and keyword arguments
+
+ lambda* creates a procedure that takes optional arguments. These
+ are specified by putting them inside brackets at the end of the
+ paramater list, but before any dotted rest argument. For example,
+ (lambda* (a b #&optional c d . e) '())
+ creates a procedure with fixed arguments a and b, optional arguments c
+ and d, and rest argument e. If the optional arguments are omitted
+ in a call, the variables for them are unbound in the procedure. This
+ can be checked with the bound? macro.
+
+ lambda* can also take keyword arguments. For example, a procedure
+ defined like this:
+ (lambda* (#&key xyzzy larch) '())
+ can be called with any of the argument lists (#:xyzzy 11)
+ (#:larch 13) (#:larch 42 #:xyzzy 19) (). Whichever arguments
+ are given as keywords are bound to values.
+
+ Optional and keyword arguments can also be given default values
+ which they take on when they are not present in a call, by giving a
+ two-item list in place of an optional argument, for example in:
+ (lambda* (foo #&optional (bar 42) #&key (baz 73)) (list foo bar baz))
+ foo is a fixed argument, bar is an optional argument with default
+ value 42, and baz is a keyword argument with default value 73.
+ Default value expressions are not evaluated unless they are needed
+ and until the procedure is called.
+
+ lambda* now supports two more special parameter list keywords.
+
+ lambda*-defined procedures now throw an error by default if a
+ keyword other than one of those specified is found in the actual
+ passed arguments. However, specifying #&allow-other-keys
+ immediately after the kyword argument declarations restores the
+ previous behavior of ignoring unknown keywords. lambda* also now
+ guarantees that if the same keyword is passed more than once, the
+ last one passed is the one that takes effect. For example,
+ ((lambda* (#&key (heads 0) (tails 0)) (display (list heads tails)))
+ #:heads 37 #:tails 42 #:heads 99)
+ would result in (99 47) being displayed.
+
+ #&rest is also now provided as a synonym for the dotted syntax rest
+ argument. The argument lists (a . b) and (a #&rest b) are equivalent in
+ all respects to lambda*. This is provided for more similarity to DSSSL,
+ MIT-Scheme and Kawa among others, as well as for refugees from other
+ Lisp dialects.
+
+Further documentation may be found in the optargs.scm file itself.
+
+The optional argument module also exports the macros `let-optional',
+`let-optional*', `let-keywords', `let-keywords*' and `bound?'. These
+are not documented here because they may be removed in the future, but
+full documentation is still available in optargs.scm.
+
+** New syntax: and-let*
+Guile now supports the `and-let*' form, described in the draft SRFI-2.
+
+Syntax: (land* (<clause> ...) <body> ...)
+Each <clause> should have one of the following forms:
+ (<variable> <expression>)
+ (<expression>)
+ <bound-variable>
+Each <variable> or <bound-variable> should be an identifier. Each
+<expression> should be a valid expression. The <body> should be a
+possibly empty sequence of expressions, like the <body> of a
+lambda form.
+
+Semantics: A LAND* expression is evaluated by evaluating the
+<expression> or <bound-variable> of each of the <clause>s from
+left to right. The value of the first <expression> or
+<bound-variable> that evaluates to a false value is returned; the
+remaining <expression>s and <bound-variable>s are not evaluated.
+The <body> forms are evaluated iff all the <expression>s and
+<bound-variable>s evaluate to true values.
+
+The <expression>s and the <body> are evaluated in an environment
+binding each <variable> of the preceding (<variable> <expression>)
+clauses to the value of the <expression>. Later bindings
+shadow earlier bindings.
+
+Guile's and-let* macro was contributed by Michael Livshin.
+
+** New function: sorted? SEQUENCE LESS?
+Returns `#t' when the sequence argument is in non-decreasing order
+according to LESS? (that is, there is no adjacent pair `... x y
+...' for which `(less? y x)').
+
+Returns `#f' when the sequence contains at least one out-of-order
+pair. It is an error if the sequence is neither a list nor a
+vector.
+
+** New function: merge LIST1 LIST2 LESS?
+LIST1 and LIST2 are sorted lists.
+Returns the sorted list of all elements in LIST1 and LIST2.
+
+Assume that the elements a and b1 in LIST1 and b2 in LIST2 are "equal"
+in the sense that (LESS? x y) --> #f for x, y in {a, b1, b2},
+and that a < b1 in LIST1. Then a < b1 < b2 in the result.
+(Here "<" should read "comes before".)
+
+** New procedure: merge! LIST1 LIST2 LESS?
+Merges two lists, re-using the pairs of LIST1 and LIST2 to build
+the result. If the code is compiled, and LESS? constructs no new
+pairs, no pairs at all will be allocated. The first pair of the
+result will be either the first pair of LIST1 or the first pair of
+LIST2.
+
+** New function: sort SEQUENCE LESS?
+Accepts either a list or a vector, and returns a new sequence
+which is sorted. The new sequence is the same type as the input.
+Always `(sorted? (sort sequence less?) less?)'. The original
+sequence is not altered in any way. The new sequence shares its
+elements with the old one; no elements are copied.
+
+** New procedure: sort! SEQUENCE LESS
+Returns its sorted result in the original boxes. No new storage is
+allocated at all. Proper usage: (set! slist (sort! slist <))
+
+** New function: stable-sort SEQUENCE LESS?
+Similar to `sort' but stable. That is, if "equal" elements are
+ordered a < b in the original sequence, they will have the same order
+in the result.
+
+** New function: stable-sort! SEQUENCE LESS?
+Similar to `sort!' but stable.
+Uses temporary storage when sorting vectors.
+
+** New functions: sort-list, sort-list!
+Added for compatibility with scsh.
+
+** New function: random N [STATE]
+Accepts a positive integer or real N and returns a number of the
+same type between zero (inclusive) and N (exclusive). The values
+returned have a uniform distribution.
+
+The optional argument STATE must be of the type produced by
+`copy-random-state' or `seed->random-state'. It defaults to the value
+of the variable `*random-state*'. This object is used to maintain the
+state of the pseudo-random-number generator and is altered as a side
+effect of the `random' operation.
+
+** New variable: *random-state*
+Holds a data structure that encodes the internal state of the
+random-number generator that `random' uses by default. The nature
+of this data structure is implementation-dependent. It may be
+printed out and successfully read back in, but may or may not
+function correctly as a random-number state object in another
+implementation.
+
+** New function: copy-random-state [STATE]
+Returns a new object of type suitable for use as the value of the
+variable `*random-state*' and as a second argument to `random'.
+If argument STATE is given, a copy of it is returned. Otherwise a
+copy of `*random-state*' is returned.
+
+** New function: seed->random-state SEED
+Returns a new object of type suitable for use as the value of the
+variable `*random-state*' and as a second argument to `random'.
+SEED is a string or a number. A new state is generated and
+initialized using SEED.
+
+** New function: random:uniform [STATE]
+Returns an uniformly distributed inexact real random number in the
+range between 0 and 1.
+
+** New procedure: random:solid-sphere! VECT [STATE]
+Fills VECT with inexact real random numbers the sum of whose
+squares is less than 1.0. Thinking of VECT as coordinates in
+space of dimension N = `(vector-length VECT)', the coordinates are
+uniformly distributed within the unit N-shere. The sum of the
+squares of the numbers is returned. VECT can be either a vector
+or a uniform vector of doubles.
+
+** New procedure: random:hollow-sphere! VECT [STATE]
+Fills VECT with inexact real random numbers the sum of whose squares
+is equal to 1.0. Thinking of VECT as coordinates in space of
+dimension n = `(vector-length VECT)', the coordinates are uniformly
+distributed over the surface of the unit n-shere. VECT can be either
+a vector or a uniform vector of doubles.
+
+** New function: random:normal [STATE]
+Returns an inexact real in a normal distribution with mean 0 and
+standard deviation 1. For a normal distribution with mean M and
+standard deviation D use `(+ M (* D (random:normal)))'.
+
+** New procedure: random:normal-vector! VECT [STATE]
+Fills VECT with inexact real random numbers which are independent and
+standard normally distributed (i.e., with mean 0 and variance 1).
+VECT can be either a vector or a uniform vector of doubles.
+
+** New function: random:exp STATE
+Returns an inexact real in an exponential distribution with mean 1.
+For an exponential distribution with mean U use (* U (random:exp)).
+
+** The range of logand, logior, logxor, logtest, and logbit? have changed.
+
+These functions now operate on numbers in the range of a C unsigned
+long.
+
+These functions used to operate on numbers in the range of a C signed
+long; however, this seems inappropriate, because Guile integers don't
+overflow.
+
+** New function: make-guardian
+This is an implementation of guardians as described in
+R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in a
+Generation-Based Garbage Collector" ACM SIGPLAN Conference on
+Programming Language Design and Implementation, June 1993
+ftp://ftp.cs.indiana.edu/pub/scheme-repository/doc/pubs/guardians.ps.gz
+
** New functions: delq1!, delv1!, delete1!
These procedures behave similar to delq! and friends but delete only
one object if at all.
If unread-char is called multiple times, the unread characters will be
read again in last-in first-out order.
-** New function: serial-map PROC LIST1 LIST2 ...
+** New function: map-in-order PROC LIST1 LIST2 ...
Version of `map' which guarantees that the procedure is applied to the
lists in serial order.
-** New syntax: sequence->list BODY1 ...
+** Renamed `serial-array-copy!' and `serial-array-map!' to
+`array-copy-in-order!' and `array-map-in-order!'. The old names are
+now obsolete and will go away in release 1.5.
+
+** New syntax: collect BODY1 ...
Version of `begin' which returns a list of the results of the body
forms instead of the result of the last body form. In contrast to
-`begin', sequence->list allows an empty body.
+`begin', `collect' allows an empty body.
** New functions: read-history FILENAME, write-history FILENAME
Read/write command line history from/to file. Returns #t on success
New functions.
+* Changes to the scm_ interface
+
+** Plug in interface for random number generators
+The variable `scm_the_rng' in random.c contains a value and three
+function pointers which together define the current random number
+generator being used by the Scheme level interface and the random
+number library functions.
+
+The user is free to replace the default generator with the generator
+of his own choice.
+
+*** Variable: size_t scm_the_rng.rstate_size
+The size of the random state type used by the current RNG
+measured in chars.
+
+*** Function: unsigned long scm_the_rng.random_bits (scm_rstate *STATE)
+Given the random STATE, return 32 random bits.
+
+*** Function: void scm_the_rng.init_rstate (scm_rstate *STATE, chars *S, int N)
+Seed random state STATE using string S of length N.
+
+*** Function: scm_rstate *scm_the_rng.copy_rstate (scm_rstate *STATE)
+Given random state STATE, return a malloced copy.
+
+** Default RNG
+The default RNG is the MWC (Multiply With Carry) random number
+generator described by George Marsaglia at the Department of
+Statistics and Supercomputer Computations Research Institute, The
+Florida State University (http://stat.fsu.edu/~geo).
+
+It uses 64 bits, has a period of 4578426017172946943 (4.6e18), and
+passes all tests in the DIEHARD test suite
+(http://stat.fsu.edu/~geo/diehard.html). The generation of 32 bits
+costs one multiply and one add on platforms which either supports long
+longs (gcc does this on most systems) or have 64 bit longs. The cost
+is four multiply on other systems but this can be optimized by writing
+scm_i_uniform32 in assembler.
+
+These functions are provided through the scm_the_rng interface for use
+by libguile and the application.
+
+*** Function: unsigned long scm_i_uniform32 (scm_i_rstate *STATE)
+Given the random STATE, return 32 random bits.
+Don't use this function directly. Instead go through the plugin
+interface (see "Plug in interface" above).
+
+*** Function: void scm_i_init_rstate (scm_i_rstate *STATE, char *SEED, int N)
+Initialize STATE using SEED of length N.
+
+*** Function: scm_i_rstate *scm_i_copy_rstate (scm_i_rstate *STATE)
+Return a malloc:ed copy of STATE. This function can easily be re-used
+in the interfaces to other RNGs.
+
+** Random number library functions
+These functions use the current RNG through the scm_the_rng interface.
+It might be a good idea to use these functions from your C code so
+that only one random generator is used by all code in your program.
+
+You can get the default random state using:
+
+*** Variable: SCM scm_var_random_state
+Contains the vcell of the Scheme variable "*random-state*" which is
+used as default state by all random number functions in the Scheme
+level interface.
+
+Example:
+
+ double x = scm_i_uniform01 (SCM_RSTATE (SCM_CDR (scm_var_random_state)));
+
+*** Function: double scm_i_uniform01 (scm_rstate *STATE)
+Return a sample from the uniform(0,1) distribution.
+
+*** Function: double scm_i_normal01 (scm_rstate *STATE)
+Return a sample from the normal(0,1) distribution.
+
+*** Function: double scm_i_exp1 (scm_rstate *STATE)
+Return a sample from the exp(1) distribution.
+
+*** Function: unsigned long scm_i_random (unsigned long M, scm_rstate *STATE)
+Return a sample from the discrete uniform(0,M) distribution.
+
\f
Changes in Guile 1.3 (released Monday, October 19, 1998):
HCoop / bpt / guile.git / blobdiff