X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/04c76b58094b2bcfc1db9b9b121ebf01d46784ad..97c524bd4a7b621bb904032b44bfafe4660ca76e:/NEWS diff --git a/NEWS b/NEWS index 8ed77a74c..96315ccdb 100644 --- a/NEWS +++ b/NEWS @@ -2,42 +2,670 @@ Guile NEWS --- history of user-visible changes. -*- text -*- Copyright (C) 1996, 1997 Free Software Foundation, Inc. See the end for copying conditions. -Please send Guile bug reports to bug-guile@prep.ai.mit.edu. +Please send Guile bug reports to bug-guile@gnu.org. Changes since Guile 1.2: * Changes to the distribution +** We renamed the SCHEME_LOAD_PATH environment variable to GUILE_LOAD_PATH. +To avoid conflicts, programs should name environment variables after +themselves, except when there's a common practice establishing some +other convention. + +For now, Guile supports both GUILE_LOAD_PATH and SCHEME_LOAD_PATH, +giving the former precedence, and printing a warning message if the +latter is set. Guile 1.4 will not recognize SCHEME_LOAD_PATH at all. + +** The header files related to multi-byte characters have been removed. +They were: libguile/extchrs.h and libguile/mbstrings.h. Any C code +which referred to these explicitly will probably need to be rewritten, +since the support for the variant string types has been removed; see +below. + +** The header files append.h and sequences.h have been removed. These +files implemented non-R4RS operations which would encourage +non-portable programming style and less easy-to-read code. + * 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". + +** the-last-stack is now a fluid. + * Changes to the procedure for linking libguile with your programs +** You can now use the `guile-config' utility to build programs that use Guile. + +Guile now includes a command-line utility called `guile-config', which +can provide information about how to compile and link programs that +use Guile. + +*** `guile-config compile' prints any C compiler flags needed to use Guile. +You should include this command's output on the command line you use +to compile C or C++ code that #includes the Guile header files. It's +usually just a `-I' flag to help the compiler find the Guile headers. + + +*** `guile-config link' prints any linker flags necessary to link with Guile. + +This command writes to its standard output a list of flags which you +must pass to the linker to link your code against the Guile library. +The flags include '-lguile' itself, any other libraries the Guile +library depends upon, and any `-L' flags needed to help the linker +find those libraries. + +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} `guile-config link` -o foo + +Previous Guile releases recommended that you use autoconf to detect +which of a predefined set of libraries were present on your system. +It is more robust to use `guile-config', since it records exactly which +libraries the installed Guile library requires. + +This was originally called `build-guile', but was renamed to +`guile-config' before Guile 1.3 was released, to be consistent with +the analogous script for the GTK+ GUI toolkit, which is called +`gtk-config'. + + +** Use the GUILE_FLAGS macro in your configure.in file to find Guile. + +If you are using the GNU autoconf package to configure your program, +you can use the GUILE_FLAGS autoconf macro to call `guile-config' +(described above) and gather the necessary values for use in your +Makefiles. + +The GUILE_FLAGS macro expands to configure script code which runs the +`guile-config' script, to find out where Guile's header files and +libraries are installed. It sets two variables, marked for +substitution, as by AC_SUBST. + + GUILE_CFLAGS --- flags to pass to a C or C++ compiler to build + code that uses Guile header files. This is almost always just a + -I flag. + + GUILE_LDFLAGS --- flags to pass to the linker to link a + program against Guile. This includes `-lguile' for the Guile + library itself, any libraries that Guile itself requires (like + -lqthreads), and so on. It may also include a -L flag to tell the + compiler where to find the libraries. + +GUILE_FLAGS is defined in the file guile.m4, in the top-level +directory of the Guile distribution. You can copy it into your +package's aclocal.m4 file, and then use it in your configure.in file. + +If you are using the `aclocal' program, distributed with GNU automake, +to maintain your aclocal.m4 file, the Guile installation process +installs guile.m4 where aclocal will find it. All you need to do is +use GUILE_FLAGS in your configure.in file, and then run `aclocal'; +this will copy the definition of GUILE_FLAGS into your aclocal.m4 +file. + + * Changes to Scheme functions and syntax +** Multi-byte strings have been removed, as have multi-byte and wide +ports. We felt that these were the wrong approach to +internationalization support. + +** 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. + +** New module (ice-9 getopt-gnu-style): Parse command-line arguments. + +This module provides some simple argument parsing. It exports one +function: + +Function: getopt-gnu-style ARG-LS + Parse a list of program arguments into an alist of option + descriptions. + + Each item in the list of program arguments is examined to see if + it meets the syntax of a GNU long-named option. An argument like + `--MUMBLE' produces an element of the form (MUMBLE . #t) in the + returned alist, where MUMBLE is a keyword object with the same + name as the argument. An argument like `--MUMBLE=FROB' produces + an element of the form (MUMBLE . FROB), where FROB is a string. + + As a special case, the returned alist also contains a pair whose + car is the symbol `rest'. The cdr of this pair is a list + containing all the items in the argument list that are not options + of the form mentioned above. + + The argument `--' is treated specially: all items in the argument + list appearing after such an argument are not examined, and are + returned in the special `rest' list. + + 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. + +** 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 `print-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: + +Function: make-fluid - (make-fluid) + 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'. - Create a new fluid object. +Function: fluid? OBJ - (fluid-ref FLUID) - (fluid-set! FLUID VAL) + 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. + +** Changes to system call interfaces: + +*** close-port, close-input-port and close-output-port now return a +boolean instead of an `unspecified' object. #t means that the port +was successfully closed, while #f means it was already closed. It is +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. -** A new procedure primitive-exit can be used to terminate the current -process without unwinding the Scheme stack. This would usually be used -after a fork. +*** The following new procedures have been added (most use scsh +interfaces): + +*** 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 +their revealed counts set to zero. + +*** 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. + + 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. + + The return value is unspecified. + +*** 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'. + + The return value is unspecified. + +*** procedure: setvbuf PORT MODE [SIZE] + Set the buffering mode for PORT. MODE can be: + `_IONBF' + non-buffered + + `_IOLBF' + line buffered + + `_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. + + This procedure should not be used after I/O has been performed with + the port. + + 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. + +*** 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. + +*** procedure: open-fdes PATH FLAGS [MODES] + Similar to `open' but returns a file descriptor instead of a port. + +*** 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. + +** Removed: list-length +** Removed: list-append, list-append! +** Removed: list-reverse, list-reverse! + +** array-map renamed to array-map! + +** serial-array-map renamed to serial-array-map! + +** catch doesn't take #f as first argument any longer + +Previously, it was possible to pass #f instead of a key to `catch'. +That would cause `catch' to pass a jump buffer object to the procedure +passed as second argument. The procedure could then use this jump +buffer objekt as an argument to throw. + +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. * Changes to the gh_ interface +** The gh_enter function now takes care of loading the Guile startup files. +gh_enter works by calling scm_boot_guile; see the remarks below. + +** 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. + +** gh_scm2doubles, gh_doubles2scm, gh_doubles2dvect + +New function. Converts double arrays back and forth between Scheme +and C. + * Changes to the scm_ interface +** The function scm_boot_guile now takes care of loading the startup files. + +Guile's primary initialization function, scm_boot_guile, now takes +care of loading `boot-9.scm', in the `ice-9' module, to initialize +Guile, define the module system, and put together some standard +bindings. It also loads `init.scm', which is intended to hold +site-specific initialization code. + +Since Guile cannot operate properly until boot-9.scm is loaded, there +is no reason to separate loading boot-9.scm from Guile's other +initialization processes. + +This job used to be done by scm_compile_shell_switches, which didn't +make much sense; in particular, it meant that people using Guile for +non-shell-like applications had to jump through hoops to get Guile +initialized properly. + +** The function scm_compile_shell_switches no longer loads the startup files. +Now, Guile always loads the startup files, whenever it is initialized; +see the notes above for scm_boot_guile and scm_load_startup_files. + +** Function: scm_load_startup_files +This new function takes care of loading Guile's initialization file +(`boot-9.scm'), and the site initialization file, `init.scm'. Since +this is always called by the Guile initialization process, it's +probably not too useful to call this yourself, but it's there anyway. + +** The semantics of smob marking have changed slightly. + +The smob marking function (the `mark' member of the scm_smobfuns +structure) is no longer responsible for setting the mark bit on the +smob. The generic smob handling code in the garbage collector will +set this bit. The mark function need only ensure that any other +objects the smob refers to get marked. + +Note that this change means that the smob's GC8MARK bit is typically +already set upon entry to the mark function. Thus, marking functions +which look like this: + + { + if (SCM_GC8MARKP (ptr)) + return SCM_BOOL_F; + SCM_SETGC8MARK (ptr); + ... mark objects to which the smob refers ... + } + +are now incorrect, since they will return early, and fail to mark any +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, + SELECT_TYPE *wfds, + SELECT_TYPE *efds, + struct timeval *timeout); + +This is a replacement for the `select' function provided by the OS. +It enables I/O blocking and sleeping to happen for one cooperative +thread without blocking other threads. It also avoids busy-loops in +these situations. It is intended that all I/O blocking and sleeping +will finally go through this function. Currently, this function is +only available on systems providing `gettimeofday' and `select'. + +** 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.) + +** Function: SCM scm_spawn_thread (scm_catch_body_t body, + void *body_data, + scm_catch_handler_t handler, + void *handler_data) + +Spawns a new thread. It does a job similar to +scm_call_with_new_thread but takes arguments more suitable when +spawning threads from application C code. + +** 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. + +** 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. + Changes in Guile 1.2 (released Tuesday, June 24 1997): @@ -1221,7 +1849,7 @@ the Scheme shell). 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