Guile NEWS --- history of user-visible changes. -*- text -*-
-Copyright (C) 1996, 1997 Free Software Foundation, Inc.
+Copyright (C) 1996, 1997, 1998 Free Software Foundation, Inc.
See the end for copying conditions.
Please send Guile bug reports to bug-guile@gnu.org.
\f
-Changes since Guile 1.2:
+Changes since Guile 1.3:
+
+* Changes to the stand-alone interpreter
+
+** Command-line editing is enhanced.
+
+If you have a sufficiently recent version of the GNU readline library
+installed on your system, Guile will use it to read expressions
+interactively.
+
+You can now use the readline-options interface to control readline's
+behavior. You can now control the readline library's behavior by
+changing the options listed below.
+
+ (readline-enable 'history-file)
+ Tell readline to record your commands in a file when you exit
+ Guile, and restore them when you restart Guile. By default, Guile
+ saves commands to `$HOME/.guile_history', but if the
+ `GUILE_HISTORY' environment variable is set, Guile will use its
+ value as the name of the history file.
+
+ If Guile is unable to save or restore lines from the history file,
+ the operation is simply not performed; the user is not notified.
+
+ (readline-disable 'history-file)
+ Tell Guile not to save or restore command history.
+
+ (readline-set! history-length N)
+ Tell Guile to save at most N lines of command history.
+
+ (readline-set! bounce-parens N)
+ Tell Guile to indicate the matching opening parenthesis when you
+ type a closing parenthesis, by resting the cursor on it for N
+ milliseconds. If N is zero, do not highlight opening parethesis.
+
+** All builtins now print as primitives.
+Previously builtin procedures not belonging to the fundamental subr
+types printed as #<compiled closure #<primitive-procedure gsubr-apply>>.
+Now, they print as #<primitive-procedure NAME>.
+
+** Backtraces slightly more intelligible.
+gsubr-apply and macro transformer application frames no longer appear
+in backtraces.
+
+* Changes to Scheme functions and syntax
+
+** 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.
+
+** New function: unread-string STRING PORT
+Unread STRING to PORT, that is, push it back onto the port so that
+next read operation will work on the pushed back characters.
+
+** unread-char can now be called multiple times
+If unread-char is called multiple times, the unread characters will be
+read again in last-in first-out order.
+
+** New function: map-in-order PROC LIST1 LIST2 ...
+Version of `map' which guarantees that the procedure is applied to the
+lists in serial order.
+
+** 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', `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
+and #f if an error occured.
+
+* Changes to the gh_ interface
+
+** gh_scm2doubles
+
+Now takes a second argument which is the result array. If this
+pointer is NULL, a new array is malloced (the old behaviour).
+
+** gh_chars2byvect, gh_shorts2svect, gh_floats2fvect, gh_scm2chars,
+ gh_scm2shorts, gh_scm2longs, gh_scm2floats
+
+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):
* Changes to the distribution
the function, and let READLINE print the prompt itself. This is
because READLINE needs to know the prompt's screen width.
-For Guile to provide this function, you must have the readline library
-installed on your system.
+For Guile to provide this function, you must have the readline
+library, version 2.1 or later, installed on your system. Readline is
+available via anonymous FTP from prep.ai.mit.edu in pub/gnu, or from
+any GNU mirror site.
See also ADD-HISTORY function.
command. READLINE does not add lines to the history itself; you must
call ADD-HISTORY to make previous input available to the user.
+** The behavior of the read-line function has changed.
+
+This function now uses standard C library functions to read the line,
+for speed. This means that it doesn not respect the value of
+scm-line-incrementors; it assumes that lines are delimited with
+#\newline.
+
+(Note that this is read-line, the function that reads a line of text
+from a port, not readline, the function that reads a line from a
+terminal, providing full editing capabilities.)
+
** New module (ice-9 getopt-gnu-style): Parse command-line arguments.
This module provides some simple argument parsing. It exports one
This function does not parse normal single-character switches.
You will need to parse them out of the `rest' list yourself.
-** macro-eval! is removed. Use local-eval instead.
+** The read syntax for byte vectors and short vectors has changed.
+
+Instead of #bytes(...), write #y(...).
+
+Instead of #short(...), write #h(...).
+
+This may seem nutty, but, like the other uniform vectors, byte vectors
+and short vectors want to have the same print and read syntax (and,
+more basic, want to have read syntax!). Changing the read syntax to
+use multiple characters after the hash sign breaks with the
+conventions used in R5RS and the conventions used for the other
+uniform vectors. It also introduces complexity in the current reader,
+both on the C and Scheme levels. (The Right solution is probably to
+change the syntax and prototypes for uniform vectors entirely.)
+
+
+** The new module (ice-9 session) provides useful interactive functions.
+
+*** New procedure: (apropos REGEXP OPTION ...)
+
+Display a list of top-level variables whose names match REGEXP, and
+the modules they are imported from. Each OPTION should be one of the
+following symbols:
+
+ value --- Show the value of each matching variable.
+ shadow --- Show bindings shadowed by subsequently imported modules.
+ full --- Same as both `shadow' and `value'.
+
+For example:
+
+ guile> (apropos "trace" 'full)
+ debug: trace #<procedure trace args>
+ debug: untrace #<procedure untrace args>
+ the-scm-module: display-backtrace #<compiled-closure #<primitive-procedure gsubr-apply>>
+ the-scm-module: before-backtrace-hook ()
+ the-scm-module: backtrace #<primitive-procedure backtrace>
+ the-scm-module: after-backtrace-hook ()
+ the-scm-module: has-shown-backtrace-hint? #f
+ guile>
+
+** There are new functions and syntax for working with macros.
+
+Guile implements macros as a special object type. Any variable whose
+top-level binding is a macro object acts as a macro. The macro object
+specifies how the expression should be transformed before evaluation.
+
+*** Macro objects now print in a reasonable way, resembling procedures.
+
+*** New function: (macro? OBJ)
+True iff OBJ is a macro object.
+
+*** New function: (primitive-macro? OBJ)
+Like (macro? OBJ), but true only if OBJ is one of the Guile primitive
+macro transformers, implemented in eval.c rather than Scheme code.
+
+Why do we have this function?
+- For symmetry with procedure? and primitive-procedure?,
+- to allow custom print procedures to tell whether a macro is
+ primitive, and display it differently, and
+- to allow compilers and user-written evaluators to distinguish
+ builtin special forms from user-defined ones, which could be
+ compiled.
+
+*** New function: (macro-type OBJ)
+Return a value indicating what kind of macro OBJ is. Possible return
+values are:
+
+ The symbol `syntax' --- a macro created by procedure->syntax.
+ The symbol `macro' --- a macro created by procedure->macro.
+ The symbol `macro!' --- a macro created by procedure->memoizing-macro.
+ The boolean #f --- if OBJ is not a macro object.
+
+*** New function: (macro-name MACRO)
+Return the name of the macro object MACRO's procedure, as returned by
+procedure-name.
+
+*** New function: (macro-transformer MACRO)
+Return the transformer procedure for MACRO.
+
+*** New syntax: (use-syntax MODULE ... TRANSFORMER)
+
+Specify a new macro expander to use in the current module. Each
+MODULE is a module name, with the same meaning as in the `use-modules'
+form; each named module's exported bindings are added to the current
+top-level environment. TRANSFORMER is an expression evaluated in the
+resulting environment which must yield a procedure to use as the
+module's eval transformer: every expression evaluated in this module
+is passed to this function, and the result passed to the Guile
+interpreter.
+
+*** macro-eval! is removed. Use local-eval instead.
** Some magic has been added to the printer to better handle user
written printing routines (like record printers, closure printers).
properly continue the print chain.
We didn't want to change all existing print code so that it
-explicitely passes thru a print state in addition to a port. Instead,
+explicitly passes thru a print state in addition to a port. Instead,
we extented the possible values that the builtin printing routines
accept as a `port'. In addition to a normal port, they now also take
a pair of a normal port and a print-state. Printing will go to the
This mechanism has been removed since its utility doesn't motivate the
extra complexity it introduces.
+** The `#/' notation for lists now provokes a warning message from Guile.
+This syntax will be removed from Guile in the near future.
+
+To disable the warning message, set the GUILE_HUSH environment
+variable to any non-empty value.
+
+** The newline character now prints as `#\newline', following the
+normal Scheme notation, not `#\nl'.
+
* Changes to the gh_ interface
** The gh_enter function now takes care of loading the Guile startup files.
other objects the smob refers to. Some code in the Guile library used
to work this way.
+** The semantics of the I/O port functions in scm_ptobfuns have changed.
+
+If you have implemented your own I/O port type, by writing the
+functions required by the scm_ptobfuns and then calling scm_newptob,
+you will need to change your functions slightly.
+
+The functions in a scm_ptobfuns structure now expect the port itself
+as their argument; they used to expect the `stream' member of the
+port's scm_port_table structure. This allows functions in an
+scm_ptobfuns structure to easily access the port's cell (and any flags
+it its CAR), and the port's scm_port_table structure.
+
+Guile now passes the I/O port itself as the `port' argument in the
+following scm_ptobfuns functions:
+
+ int (*free) (SCM port);
+ int (*fputc) (int, SCM port);
+ int (*fputs) (char *, SCM port);
+ scm_sizet (*fwrite) SCM_P ((char *ptr,
+ scm_sizet size,
+ scm_sizet nitems,
+ SCM port));
+ int (*fflush) (SCM port);
+ int (*fgetc) (SCM port);
+ int (*fclose) (SCM port);
+
+The interfaces to the `mark', `print', `equalp', and `fgets' methods
+are unchanged.
+
+If you have existing code which defines its own port types, it is easy
+to convert your code to the new interface; simply apply SCM_STREAM to
+the port argument to yield the value you code used to expect.
+
+Note that since both the port and the stream have the same type in the
+C code --- they are both SCM values --- the C compiler will not remind
+you if you forget to update your scm_ptobfuns functions.
+
** Function: int scm_internal_select (int fds,
SELECT_TYPE *rfds,
This means that the type codes scm_tc7_mb_string and
scm_tc7_mb_substring has been removed.
+** scm_gen_putc, scm_gen_puts, scm_gen_write, and scm_gen_getc have changed.
+
+Since we no longer support multi-byte strings, these I/O functions
+have been simplified, and renamed. Here are their old names, and
+their new names and arguments:
+
+scm_gen_putc -> void scm_putc (int c, SCM port);
+scm_gen_puts -> void scm_puts (char *s, SCM port);
+scm_gen_write -> void scm_lfwrite (char *ptr, scm_sizet size, SCM port);
+scm_gen_getc -> void scm_getc (SCM port);
+
+
** The macros SCM_TYP7D and SCM_TYP7SD has been removed.
** The macro SCM_TYP7S has taken the role of the old SCM_TYP7D
SCM_TYP7S now masks away the bit which distinguishes substrings from
strings.
-** All genio functions changed names and interfaces; new functions are
-scm_putc, scm_puts, scm_lfwrite, scm_getc, scm_ungetc, and
-scm_do_read_line.
-
** scm_catch_body_t: Backward incompatible change!
Body functions to scm_internal_catch and friends do not any longer
take a second argument. This is because it is no longer possible to
pass a #f arg to catch.
+** Calls to scm_protect_object and scm_unprotect now nest properly.
+
+The function scm_protect_object protects its argument from being freed
+by the garbage collector. scm_unprotect_object removes that
+protection.
+
+These functions now nest properly. That is, for every object O, there
+is a counter which scm_protect_object(O) increments and
+scm_unprotect_object(O) decrements, if the counter is greater than
+zero. Every object's counter is zero when it is first created. If an
+object's counter is greater than zero, the garbage collector will not
+reclaim its storage.
+
+This allows you to use scm_protect_object in your code without
+worrying that some other function you call will call
+scm_unprotect_object, and allow it to be freed. Assuming that the
+functions you call are well-behaved, and unprotect only those objects
+they protect, you can follow the same rule and have confidence that
+objects will be freed only at appropriate times.
+
\f
Changes in Guile 1.2 (released Tuesday, June 24 1997):
to a Scheme port object.
** The new function `scm_set_program_arguments' allows C code to set
-the value teruturned by the Scheme `program-arguments' function.
+the value returned by the Scheme `program-arguments' function.
\f
Older changes: