* Changes to the distribution
+** libguile/append.h, libguile/append.c, libguile/extchrs.h,
+libguile/extchrs.c, libguile/mbstrings.h libguile/mbstrings.c,
+libguile/sequences.h, libguile/sequences.c removed.
+
* Changes to the stand-alone interpreter
+** New procedures have been added to implement a "batch mode":
+
+*** Function: batch-mode?
+
+ Returns a boolean indicating whether the interpreter is in batch
+ mode.
+
+*** Function: set-batch-mode?! ARG
+
+ If ARG is true, switches the interpreter to batch mode. The `#f'
+ case has not been implemented.
+
+** Guile now provides full command-line editing, when run interactively.
+To use this feature, you must have the readline library installed.
+The Guile build process will notice it, and automatically include
+support for it.
+
+The readline library is available via anonymous FTP from any GNU
+mirror site; the canonical location is "ftp://prep.ai.mit.edu/pub/gnu".
+
* Changes to the procedure for linking libguile with your programs
+** You can now use the 'build-guile' utility to link against Guile.
+
+Guile now includes a command-line utility called 'build-guile', which
+writes to its standard output a list of flags which you must pass to
+the linker to link against the Guile library. The flags include
+'-lguile' itself.
+
+This is necessary because the Guile library may depend on other
+libraries for networking functions, thread support, and so on. To
+link your program against libguile, you must link against these
+libraries as well. The exact set of libraries depends on the type of
+system you are running, and what you have installed on it. The
+'build-guile' command uses information recorded in libguile itself to
+determine which libraries you must link against.
+
+For example, here is a Makefile rule that builds a program named 'foo'
+from the object files ${FOO_OBJECTS}, and links them against Guile:
+
+ foo: ${FOO_OBJECTS}
+ ${CC} ${CFLAGS} ${FOO_OBJECTS} `build-guile link` -o foo
+
+
* Changes to Scheme functions and syntax
+** Multi-byte strings have been removed, as have multi-byte and wide
+ports.
+
+** New function: readline [PROMPT]
+Read a line from the terminal, and allow the user to edit it,
+prompting with PROMPT. READLINE provides a large set of Emacs-like
+editing commands, lets the user recall previously typed lines, and
+works on almost every kind of terminal, including dumb terminals.
+
+READLINE assumes that the cursor is at the beginning of the line when
+it is invoked. Thus, you can't print a prompt yourself, and then call
+READLINE; you need to package up your prompt as a string, pass it to
+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.
+
+See also ADD-HISTORY function.
+
+** New function: add-history STRING
+Add STRING as the most recent line in the history used by the READLINE
+command. READLINE does not add lines to the history itself; you must
+call ADD-HISTORY to make previous input available to the user.
+
+** Some magic has been added to the printer to better handle user
+written printing routines (like record printers, closure printers).
+
+The problem is that these user written routines must have access to
+the current `prine-state' to be able to handle fancy things like
+detection of circular references. These print-states have to be
+passed to the builtin printing routines (display, write, etc) to
+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,
+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
+port and the print-state will be used to control the detection of
+circular references, etc. If the builtin function does not care for a
+print-state, it is simply ignored.
+
+User written callbacks are now called with such a pair as their
+`port', but because every function now accepts this pair as a PORT
+argument, you don't have to worry about that. In fact, it is probably
+safest to not check for these pairs.
+
+However, it is sometimes necessary to continue a print chain on a
+different port, for example to get a intermediate string
+representation of the printed value, mangle that string somehow, and
+then to finally print the mangled string. Use the new function
+
+ inherit-print-state OLD-PORT NEW-PORT
+
+for this. It constructs a new `port' that prints to NEW-PORT but
+inherits the print-state of OLD-PORT.
+
+** struct-vtable-offset renamed to vtable-offset-user
+
+** New constants: vtable-index-layout, vtable-index-vtable, vtable-index-printer
+
+** There is now a fourth (optional) argument to make-vtable-vtable and
+ make-struct when constructing new types (vtables). This argument
+ initializes field vtable-index-printer of the vtable.
+
+** The detection of circular references has been extended to structs.
+That is, a structure that -- in the process of being printed -- prints
+itself does not lead to infinite recursion.
+
** There is now some basic support for fluids. Please read
"libguile/fluid.h" to find out more. It is accessible from Scheme with
-the following builtin procedures:
+the following functions and macros:
- (make-fluid)
+Function: make-fluid
- Create a new fluid object.
+ Create a new fluid object. Fluids are not special variables or
+ some other extension to the semantics of Scheme, but rather
+ ordinary Scheme objects. You can store them into variables (that
+ are still lexically scoped, of course) or into any other place you
+ like. Every fluid has a initial value of `#f'.
- (fluid-ref FLUID)
- (fluid-set! FLUID VAL)
+Function: fluid? OBJ
+
+ Test whether OBJ is a fluid.
+
+Function: fluid-ref FLUID
+Function: fluid-set! FLUID VAL
Access/modify the fluid FLUID. Modifications are only visible
within the current dynamic root (that includes threads).
-There is no `fluid-let' yet.
+Function: with-fluids* FLUIDS VALUES THUNK
+
+ FLUIDS is a list of fluids and VALUES a corresponding list of
+ values for these fluids. Before THUNK gets called the values are
+ installed in the fluids and the old values of the fluids are
+ saved in the VALUES list. When the flow of control leaves THUNK
+ or reenters it, the values get swapped again. You might think of
+ this as a `safe-fluid-excursion'. Note that the VALUES list is
+ modified by `with-fluids*'.
+
+Macro: with-fluids ((FLUID VALUE) ...) FORM ...
+
+ The same as `with-fluids*' but with a different syntax. It looks
+ just like `let', but both FLUID and VALUE are evaluated. Remember,
+ fluids are not special variables but ordinary objects. FLUID
+ should evaluate to a fluid.
+
+** Removed procedures:
+
+list-length, list-append, list-append!, list-reverse, list-reverse!
+
+** array-map renamed to array-map!
+
+** serial-array-map renamed to serial-array-map!
* Changes to system call interfaces:
also now possible for these procedures to raise an exception if an
error occurs (some errors from write can be delayed until close.)
+** the first argument to chmod, fcntl, ftell and fseek can now be a
+file descriptor.
+
+** the third argument to fcntl is now optional.
+
+** the first argument to chown can now be a file descriptor or a port.
+
+** the argument to stat can now be a port.
+
** The following new procedures have been added (most use scsh
interfaces):
-** close PORT/FD
-Similar to close-port, but also works on file descriptors. A side
-effect of closing a file descriptor is that any ports using that file
-descriptor are moved to a different file descriptor and have
-their revealed counts set to zero.
-
-The next five procedures perform a dup2 system call, if NEWFD (an
-integer) is supplied, otherwise a dup. The file descriptor to be
-duplicated can be supplied as an integer or wrapped in a port. The
+** procedure: close PORT/FD
+ Similar to close-port (*note close-port: Closing Ports.), but also
+ works on file descriptors. A side effect of closing a file
+ descriptor is that any ports using that file descriptor are moved
+ to a different file descriptor and have their revealed counts set
+ to zero.
+
+** procedure: port->fdes PORT
+ Returns the integer file descriptor underlying PORT. As a side
+ effect the revealed count of PORT is incremented.
+
+** procedure: fdes->ports FDES
+ Returns a list of existing ports which have FDES as an underlying
+ file descriptor, without changing their revealed counts.
+
+** procedure: fdes->inport FDES
+ Returns an existing input port which has FDES as its underlying
+ file descriptor, if one exists, and increments its revealed count.
+ Otherwise, returns a new input port with a revealed count of 1.
+
+** procedure: fdes->outport FDES
+ Returns an existing output port which has FDES as its underlying
+ file descriptor, if one exists, and increments its revealed count.
+ Otherwise, returns a new output port with a revealed count of 1.
+
+ The next group of procedures perform a `dup2' system call, if NEWFD
+(an integer) is supplied, otherwise a `dup'. The file descriptor to be
+duplicated can be supplied as an integer or contained in a port. The
type of value returned varies depending on which procedure is used.
-All procedures also have the side effect when performing dup2 that any
-ports using NEWFD are moved to a different file descriptor and have
+ All procedures also have the side effect when performing `dup2' that
+any ports using NEWFD are moved to a different file descriptor and have
their revealed counts set to zero.
-** dup->fdes PORT/FD [NEWFD]
-Returns an integer file descriptor.
+** procedure: dup->fdes PORT/FD [NEWFD]
+ Returns an integer file descriptor.
+
+** procedure: dup->inport PORT/FD [NEWFD]
+ Returns a new input port using the new file descriptor.
+
+** procedure: dup->outport PORT/FD [NEWFD]
+ Returns a new output port using the new file descriptor.
+
+** procedure: dup PORT/FD [NEWFD]
+ Returns a new port if PORT/FD is a port, with the same mode as the
+ supplied port, otherwise returns an integer file descriptor.
+
+** procedure: dup->port PORT/FD MODE [NEWFD]
+ Returns a new port using the new file descriptor. MODE supplies a
+ mode string for the port (*note open-file: File Ports.).
+
+** procedure: setenv NAME VALUE
+ Modifies the environment of the current process, which is also the
+ default environment inherited by child processes.
-** dup->inport PORT/FD [NEWFD]
-Returns a new input port using the new file descriptor.
+ If VALUE is `#f', then NAME is removed from the environment.
+ Otherwise, the string NAME=VALUE is added to the environment,
+ replacing any existing string with name matching NAME.
-** dup->outport PORT/FD [NEWFD]
-Returns a new output port using the new file descriptor.
+ The return value is unspecified.
-** dup PORT/FD [NEWFD]
-Returns a new port if PORT/FD is a port, with the same mode as the
-supplied port, otherwise returns an integer file descriptor.
+** procedure: truncate-file OBJ SIZE
+ Truncates the file referred to by OBJ to at most SIZE bytes. OBJ
+ can be a string containing a file name or an integer file
+ descriptor or port open for output on the file. The underlying
+ system calls are `truncate' and `ftruncate'.
-** dup->port PORT/FD MODE [NEWFD]
-Returns a new port using the new file descriptor. MODE supplies a
-mode string for the port (as for `open-file').
+ The return value is unspecified.
-** primitive-dup PORT/FD
-Performs a dup system call on the file descriptor FD, or the file
-descriptor underlying PORT and returns a new integer file descriptor.
+** procedure: setvbuf PORT MODE [SIZE]
+ Set the buffering mode for PORT. MODE can be:
+ `_IONBF'
+ non-buffered
-** primitive-dup2 PORT/FD NEWFD
+ `_IOLBF'
+ line buffered
-Performs a dup2 system call on the file descriptor FD, or the file
-descriptor underlying PORT, using NEWFD (an integer) as the target
-file descriptor. Any ports using NEWFD are moved to a different file
-descriptor and have their revealed counts set to zero. The value
-returned is NEWFD.
+ `_IOFBF'
+ block buffered, using a newly allocated buffer of SIZE bytes.
+ However if SIZE is zero or unspecified, the port will be made
+ non-buffered.
-** port->fdes PORT
-Returns the integer file descriptor underlying PORT. As a
-side effect the revealed count of PORT is incremented.
+ This procedure should not be used after I/O has been performed with
+ the port.
-** fdes->inport FDES
-Returns an existing input port which has FDES as its underlying file
-descriptor, if one exists, and increments its revealed count.
-Otherwise, returns a new input port with a revealed count of 1.
+ Ports are usually block buffered by default, with a default buffer
+ size. Procedures e.g., *Note open-file: File Ports, which accept a
+ mode string allow `0' to be added to request an unbuffered port.
-** fdes->outport FDES
-Returns an existing output port which has FDES as its underlying file
-descriptor, if one exists, and increments its revealed count.
-Otherwise, returns a new output port with a revealed count of 1.
+** procedure: fsync PORT/FD
+ Copies any unwritten data for the specified output file descriptor
+ to disk. If PORT/FD is a port, its buffer is flushed before the
+ underlying file descriptor is fsync'd. The return value is
+ unspecified.
-** setenv [NAME] [VALUE]
-If VALUE is `#f', removes NAME from the environment. Otherwise
-adds the string NAME=VALUE to the environment, replacing any previous
-value for NAME.
+** procedure: open-fdes PATH FLAGS [MODES]
+ Similar to `open' but returns a file descriptor instead of a port.
-** primitive-exit [STATUS]
-Terminates the current process without unwinding the Scheme stack.
-This would usually be used after a fork.
+** procedure: execle PATH ENV [ARG] ...
+ Similar to `execl', but the environment of the new process is
+ specified by ENV, which must be a list of strings as returned by
+ the `environ' procedure.
+
+ This procedure is currently implemented using the `execve' system
+ call, but we call it `execle' because of its Scheme calling
+ interface.
+
+** procedure: strerror ERRNO
+ Returns the Unix error message corresponding to ERRNO, an integer.
+
+** procedure: primitive-exit [STATUS]
+ Terminate the current process without unwinding the Scheme stack.
+ This is would typically be useful after a fork. The exit status
+ is STATUS if supplied, otherwise zero.
+
+** procedure: times
+ Returns an object with information about real and processor time.
+ The following procedures accept such an object as an argument and
+ return a selected component:
+
+ `tms:clock'
+ The current real time, expressed as time units relative to an
+ arbitrary base.
+
+ `tms:utime'
+ The CPU time units used by the calling process.
+
+ `tms:stime'
+ The CPU time units used by the system on behalf of the
+ calling process.
+
+ `tms:cutime'
+ The CPU time units used by terminated child processes of the
+ calling process, whose status has been collected (e.g., using
+ `waitpid').
+
+ `tms:cstime'
+ Similarly, the CPU times units used by the system on behalf of
+ terminated child processes.
* Changes to the gh_ interface
+** Function: void gh_write (SCM x)
+
+Write the printed representation of the scheme object x to the current
+output port. Corresponds to the scheme level `write'.
+
+** gh_list_length renamed to gh_length.
+
+** vector handling routines
+
+Several major changes. In particular, gh_vector() now resembles
+(vector ...) (with a caveat -- see manual), and gh_make_vector() now
+exists and behaves like (make-vector ...). gh_vset() and gh_vref()
+have been renamed gh_vector_set_x() and gh_vector_ref(). Some missing
+vector-related gh_ functions have been implemented.
+
+** pair and list routines
+
+Implemented several of the R4RS pair and list functions that were
+missing.
+
* Changes to the scm_ interface
+** Function: SCM scm_internal_stack_catch (SCM tag,
+ scm_catch_body_t body,
+ void *body_data,
+ scm_catch_handler_t handler,
+ void *handler_data)
+
+A new sibling to the other two C level `catch' functions
+scm_internal_catch and scm_internal_lazy_catch. Use it if you want
+the stack to be saved automatically into the variable `the-last-stack'
+(scm_the_last_stack_var) on error. This is necessary if you want to
+use advanced error reporting, such as calling scm_display_error and
+scm_display_backtrace. (They both take a stack object as argument.)
+
+** The hook scm_error_callback has been removed. It was originally
+intended as a way for the user to install his own error handler. But
+that method works badly since it intervenes between throw and catch,
+thereby changing the semantics of expressions like (catch #t ...).
+The correct way to do it is to use one of the C level catch functions
+in throw.c: scm_internal_catch/lazy_catch/stack_catch.
+
+** Removed functions:
+
+scm_obj_length, scm_list_length, scm_list_append, scm_list_append_x,
+scm_list_reverse, scm_list_reverse_x
+
+** New macros: SCM_LISTn where n is one of the integers 0-9.
+
+These can be used for pretty list creation from C. The idea is taken
+from Erick Gallesio's STk.
+
+** scm_array_map renamed to scm_array_map_x
+
+** mbstrings are now removed
+
+This means that the type codes scm_tc7_mb_string and
+scm_tc7_mb_substring has been removed.
+
+** 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.
+
\f
Changes in Guile 1.2 (released Tuesday, June 24 1997):
To use the scm_shell function, first initialize any guile modules
linked into your application, and then call scm_shell with the values
-of ARGC and ARGV your `main' function received. scm_shell will adding
+of ARGC and ARGV your `main' function received. scm_shell will add
any SCSH-style meta-arguments from the top of the script file to the
argument vector, and then process the command-line arguments. This
generally means loading a script file or starting up an interactive