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 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.
+
+\f
+Changes in Guile 1.3 (released Monday, October 19, 1998):
* Changes to the distribution
* Changes to the procedure for linking libguile with your programs
-** You can now use the 'build-guile' utility to link against Guile.
+** 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 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, and any other libraries the Guile library depends
-upon.
+
+*** `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} `build-guile link` -o foo
+ ${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 build-guile, since it records exactly which
+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
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.
-** macro-eval! is removed. Use local-eval instead.
+** 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
+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.
+
+** 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.
+
+*** 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
** 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.
+
+** 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.
+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
* 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,
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,
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: