X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/88482b31af4eee6a14d9a6d8f8c9dfbce3337b61..cc36e791ad17b77e0f89b6c03034990fdf709971:/NEWS diff --git a/NEWS b/NEWS index 4492ed3c7..2626a0d09 100644 --- a/NEWS +++ b/NEWS @@ -1,19 +1,1926 @@ Guile NEWS --- history of user-visible changes. -*- text -*- -Copyright (C) 1996, 1997 Free Software Foundation, Inc. +Copyright (C) 1996, 1997, 1998, 1999 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 since Guile 1.3.4: + + +Changes since Guile 1.3.2: + +* Changes to the stand-alone interpreter + +** Debugger + +An initial version of the Guile debugger written by Chris Hanson has +been added. The debugger is still under development but is included +in the distribution anyway since it is already quite useful. + +Type + + (debug) + +after an error to enter the debugger. Type `help' inside the debugger +for a description of available commands. + +If you prefer to have stack frames numbered and printed in +anti-chronological order and prefer up in the stack to be down on the +screen as is the case in gdb, you can put + + (debug-enable 'backwards) + +in your .guile startup file. (However, this means that Guile can't +use indentation to indicate stack level.) + +The debugger is autoloaded into Guile at the first use. + +** Further enhancements to backtraces + +There is a new debug option `width' which controls the maximum width +on the screen of printed stack frames. Fancy printing parameters +("level" and "length" as in Common LISP) are adaptively adjusted for +each stack frame to give maximum information while still fitting +within the bounds. If the stack frame can't be made to fit by +adjusting parameters, it is simply cut off at the end. This is marked +with a `$'. + +** Some modules are now only loaded when the repl is started + +The modules (ice-9 debug), (ice-9 session), (ice-9 threads) and (ice-9 +regex) are now loaded into (guile-user) only if the repl has been +started. The effect is that the startup time for scripts has been +reduced to 30% of what it was previously. + +Correctly written scripts load the modules they require at the top of +the file and should not be affected by this change. + +** Hooks are now represented as smobs + +* Changes to Scheme functions and syntax + +** Readline support has changed again. + +The old (readline-activator) module is gone. Use (ice-9 readline) +instead, which now contains all readline functionality. So the code +to activate readline is now + + (use-modules (ice-9 readline)) + (activate-readline) + +This should work at any time, including from the guile prompt. + +To avoid confusion about the terms of Guile's license, please only +enable readline for your personal use; please don't make it the +default for others. Here is why we make this rather odd-sounding +request: + +Guile is normally licensed under a weakened form of the GNU General +Public License, which allows you to link code with Guile without +placing that code under the GPL. This exception is important to some +people. + +However, since readline is distributed under the GNU General Public +License, when you link Guile with readline, either statically or +dynamically, you effectively change Guile's license to the strict GPL. +Whenever you link any strictly GPL'd code into Guile, uses of Guile +which are normally permitted become forbidden. This is a rather +non-obvious consequence of the licensing terms. + +So, to make sure things remain clear, please let people choose for +themselves whether to link GPL'd libraries like readline with Guile. + +** regexp-substitute/global has changed slightly, but incompatibly. + +If you include a function in the item list, the string of the match +object it receives is the same string passed to +regexp-substitute/global, not some suffix of that string. +Correspondingly, the match's positions are relative to the entire +string, not the suffix. + +If the regexp can match the empty string, the way matches are chosen +from the string has changed. regexp-substitute/global recognizes the +same set of matches that list-matches does; see below. + +** New function: list-matches REGEXP STRING [FLAGS] + +Return a list of match objects, one for every non-overlapping, maximal +match of REGEXP in STRING. The matches appear in left-to-right order. +list-matches only reports matches of the empty string if there are no +other matches which begin on, end at, or include the empty match's +position. + +If present, FLAGS is passed as the FLAGS argument to regexp-exec. + +** New function: fold-matches REGEXP STRING INIT PROC [FLAGS] + +For each match of REGEXP in STRING, apply PROC to the match object, +and the last value PROC returned, or INIT for the first call. Return +the last value returned by PROC. We apply PROC to the matches as they +appear from left to right. + +This function recognizes matches according to the same criteria as +list-matches. + +Thus, you could define list-matches like this: + + (define (list-matches regexp string . flags) + (reverse! (apply fold-matches regexp string '() cons flags))) + +If present, FLAGS is passed as the FLAGS argument to regexp-exec. + +** Hooks + +*** New function: hook? OBJ + +Return #t if OBJ is a hook, otherwise #f. + +*** New function: make-hook-with-name NAME [ARITY] + +Return a hook with name NAME and arity ARITY. The default value for +ARITY is 0. The only effect of NAME is that it will appear when the +hook object is printed to ease debugging. + +*** New function: hook-empty? HOOK + +Return #t if HOOK doesn't contain any procedures, otherwise #f. + +*** New function: hook->list HOOK + +Return a list of the procedures that are called when run-hook is +applied to HOOK. + +** `map' signals an error if its argument lists are not all the same length. + +This is the behavior required by R5RS, so this change is really a bug +fix. But it seems to affect a lot of people's code, so we're +mentioning it here anyway. + +** Print-state handling has been made more transparent + +Under certain circumstances, ports are represented as a port with an +associated print state. Earlier, this pair was represented as a pair +(see "Some magic has been added to the printer" below). It is now +indistinguishable (almost; see `get-print-state') from a port on the +user level. + +*** New function: port-with-print-state OUTPUT-PORT PRINT-STATE + +Return a new port with the associated print state PRINT-STATE. + +*** New function: get-print-state OUTPUT-PORT + +Return the print state associated with this port if it exists, +otherwise return #f. + +*** New function: directory-stream? OBJECT + +Returns true iff OBJECT is a directory stream --- the sort of object +returned by `opendir'. + +** New function: using-readline? + +Return #t if readline is in use in the current repl. + +** structs will be removed in 1.4 + +Structs will be replaced in Guile 1.4. We will merge GOOPS into Guile +and use GOOPS objects as the fundamental record type. + +* Changes to the scm_ interface + +** structs will be removed in 1.4 + +The entire current struct interface (struct.c, struct.h) will be +replaced in Guile 1.4. We will merge GOOPS into libguile and use +GOOPS objects as the fundamental record type. + +** The internal representation of subr's has changed + +Instead of giving a hint to the subr name, the CAR field of the subr +now contains an index to a subr entry in scm_subr_table. + +*** New variable: scm_subr_table + +An array of subr entries. A subr entry contains the name, properties +and documentation associated with the subr. The properties and +documentation slots are not yet used. + +** A new scheme for "forwarding" calls to a builtin to a generic function + +It is now possible to extend the functionality of some Guile +primitives by letting them defer a call to a GOOPS generic function on +argument mismatch. This means that there is no loss of efficiency in +normal evaluation. + +Example: + + (use-modules (oop goops)) ; Must be GOOPS version 0.2. + (define-method + ((x ) (y )) + (string-append x y)) + ++ will still be as efficient as usual in numerical calculations, but +can also be used for concatenating strings. + +Who will be the first one to extend Guile's numerical tower to +rationals? :) [OK, there a few other things to fix before this can +be made in a clean way.] + +*** New snarf macros for defining primitives: SCM_GPROC, SCM_GPROC1 + + New macro: SCM_GPROC (CNAME, SNAME, REQ, OPT, VAR, CFUNC, GENERIC) + + New macro: SCM_GPROC1 (CNAME, SNAME, TYPE, CFUNC, GENERIC) + +These do the same job as SCM_PROC and SCM_PROC1, but they also define +a variable GENERIC which can be used by the dispatch macros below. + +[This is experimental code which may change soon.] + +*** New macros for forwarding control to a generic on arg type error + + New macro: SCM_WTA_DISPATCH_1 (GENERIC, ARG1, POS, SUBR) + + New macro: SCM_WTA_DISPATCH_2 (GENERIC, ARG1, ARG2, POS, SUBR) + +These correspond to the scm_wta function call, and have the same +behaviour until the user has called the GOOPS primitive +`enable-primitive-generic!'. After that, these macros will apply the +generic function GENERIC to the argument(s) instead of calling +scm_wta. + +[This is experimental code which may change soon.] + +*** New macros for argument testing with generic dispatch + + New macro: SCM_GASSERT1 (COND, GENERIC, ARG1, POS, SUBR) + + New macro: SCM_GASSERT2 (COND, GENERIC, ARG1, ARG2, POS, SUBR) + +These correspond to the SCM_ASSERT macro, but will defer control to +GENERIC on error after `enable-primitive-generic!' has been called. + +[This is experimental code which may change soon.] + +** New function: SCM scm_eval_body (SCM body, SCM env) + +Evaluates the body of a special form. + +** The internal representation of struct's has changed + +Previously, four slots were allocated for the procedure(s) of entities +and operators. The motivation for this representation had to do with +the structure of the evaluator, the wish to support tail-recursive +generic functions, and efficiency. Since the generic function +dispatch mechanism has changed, there is no longer a need for such an +expensive representation, and the representation has been simplified. + +This should not make any difference for most users. + +** GOOPS support has been cleaned up. + +Some code has been moved from eval.c to objects.c and code in both of +these compilation units has been cleaned up and better structured. + +*** New functions for applying generic functions + + New function: SCM scm_apply_generic (GENERIC, ARGS) + New function: SCM scm_call_generic_0 (GENERIC) + New function: SCM scm_call_generic_1 (GENERIC, ARG1) + New function: SCM scm_call_generic_2 (GENERIC, ARG1, ARG2) + New function: SCM scm_call_generic_3 (GENERIC, ARG1, ARG2, ARG3) + +** Deprecated function: scm_make_named_hook + +It is now replaced by: + +** New function: SCM scm_create_hook (const char *name, int arity) + +Creates a hook in the same way as make-hook above but also +binds a variable named NAME to it. + +This is the typical way of creating a hook from C code. + +Currently, the variable is created in the "current" module. +This might change when we get the new module system. + +[The behaviour is identical to scm_make_named_hook.] + + + +Changes since Guile 1.3: + +* Changes to mailing lists + +** Some of the Guile mailing lists have moved to sourceware.cygnus.com. + +See the README file to find current addresses for all the Guile +mailing lists. + +* 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. + +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. + +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. + +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. + +You can activate the readline support by issuing + + (use-modules (readline-activator)) + (activate-readline) + +from your ".guile" file, for example. + +* Changes to the stand-alone interpreter + +** All builtins now print as primitives. +Previously builtin procedures not belonging to the fundamental subr +types printed as #>. +Now, they print as #. + +** Backtraces slightly more intelligible. +gsubr-apply and macro transformer application frames no longer appear +in backtraces. + +* Changes to Scheme functions and syntax + +** Guile now correctly handles internal defines by rewriting them into +their equivalent letrec. Previously, internal defines would +incrementally add to the innermost environment, without checking +whether the restrictions specified in RnRS were met. This lead to the +correct behaviour when these restriction actually were met, but didn't +catch all illegal uses. Such an illegal use could lead to crashes of +the Guile interpreter or or other unwanted results. An example of +incorrect internal defines that made Guile behave erratically: + + (let () + (define a 1) + (define (b) a) + (define c (1+ (b))) + (define d 3) + + (b)) + + => 2 + +The problem with this example is that the definition of `c' uses the +value of `b' directly. This confuses the meoization machine of Guile +so that the second call of `b' (this time in a larger environment that +also contains bindings for `c' and `d') refers to the binding of `c' +instead of `a'. You could also make Guile crash with a variation on +this theme: + + (define (foo flag) + (define a 1) + (define (b flag) (if flag a 1)) + (define c (1+ (b flag))) + (define d 3) + + (b #t)) + + (foo #f) + (foo #t) + +From now on, Guile will issue an `Unbound variable: b' error message +for both examples. + +** Hooks + +A hook contains a list of functions which should be called on +particular occasions in an existing program. Hooks are used for +customization. + +A window manager might have a hook before-window-map-hook. The window +manager uses the function run-hooks to call all functions stored in +before-window-map-hook each time a window is mapped. The user can +store functions in the hook using add-hook!. + +In Guile, hooks are first class objects. + +*** New function: make-hook [N_ARGS] + +Return a hook for hook functions which can take N_ARGS arguments. +The default value for N_ARGS is 0. + +(See also scm_make_named_hook below.) + +*** New function: add-hook! HOOK PROC [APPEND_P] + +Put PROC at the beginning of the list of functions stored in HOOK. +If APPEND_P is supplied, and non-false, put PROC at the end instead. + +PROC must be able to take the number of arguments specified when the +hook was created. + +If PROC already exists in HOOK, then remove it first. + +*** New function: remove-hook! HOOK PROC + +Remove PROC from the list of functions in HOOK. + +*** New function: reset-hook! HOOK + +Clear the list of hook functions stored in HOOK. + +*** New function: run-hook HOOK ARG1 ... + +Run all hook functions stored in HOOK with arguments ARG1 ... . +The number of arguments supplied must correspond to the number given +when the hook was created. + +** The function `dynamic-link' now takes optional keyword arguments. + The only keyword argument that is currently defined is `:global + BOOL'. With it, you can control whether the shared library will be + linked in global mode or not. In global mode, the symbols from the + linked library can be used to resolve references from other + dynamically linked libraries. In non-global mode, the linked + library is essentially invisible and can only be accessed via + `dynamic-func', etc. The default is now to link in global mode. + Previously, the default has been non-global mode. + + The `#:global' keyword is only effective on platforms that support + the dlopen family of functions. + +** New function `provided?' + + - Function: provided? FEATURE + Return true iff FEATURE is supported by this installation of + Guile. FEATURE must be a symbol naming a feature; the global + variable `*features*' is a list of available features. + +** Changes to the module (ice-9 expect): + +*** The expect-strings macro now matches `$' in a regular expression + only at a line-break or end-of-file by default. Previously it would + match the end of the string accumulated so far. The old behaviour + can be obtained by setting the variable `expect-strings-exec-flags' + to 0. + +*** The expect-strings macro now uses a variable `expect-strings-exec-flags' + for the regexp-exec flags. If `regexp/noteol' is included, then `$' + in a regular expression will still match before a line-break or + end-of-file. The default is `regexp/noteol'. + +*** The expect-strings macro now uses a variable + `expect-strings-compile-flags' for the flags to be supplied to + `make-regexp'. The default is `regexp/newline', which was previously + hard-coded. + +*** The expect macro now supplies two arguments to a match procedure: + the current accumulated string and a flag to indicate whether + end-of-file has been reached. Previously only the string was supplied. + If end-of-file is reached, the match procedure will be called an + additional time with the same accumulated string as the previous call + but with the flag set. + +** New module (ice-9 format), implementing the Common Lisp `format' function. + +This code, and the documentation for it that appears here, was +borrowed from SLIB, with minor adaptations for Guile. + + - Function: format DESTINATION FORMAT-STRING . ARGUMENTS + An almost complete implementation of Common LISP format description + according to the CL reference book `Common LISP' from Guy L. + Steele, Digital Press. Backward compatible to most of the + available Scheme format implementations. + + Returns `#t', `#f' or a string; has side effect of printing + according to FORMAT-STRING. If DESTINATION is `#t', the output is + to the current output port and `#t' is returned. If DESTINATION + is `#f', a formatted string is returned as the result of the call. + NEW: If DESTINATION is a string, DESTINATION is regarded as the + format string; FORMAT-STRING is then the first argument and the + output is returned as a string. If DESTINATION is a number, the + output is to the current error port if available by the + implementation. Otherwise DESTINATION must be an output port and + `#t' is returned. + + FORMAT-STRING must be a string. In case of a formatting error + format returns `#f' and prints a message on the current output or + error port. Characters are output as if the string were output by + the `display' function with the exception of those prefixed by a + tilde (~). For a detailed description of the FORMAT-STRING syntax + please consult a Common LISP format reference manual. For a test + suite to verify this format implementation load `formatst.scm'. + Please send bug reports to `lutzeb@cs.tu-berlin.de'. + + Note: `format' is not reentrant, i.e. only one `format'-call may + be executed at a time. + + +*** Format Specification (Format version 3.0) + + Please consult a Common LISP format reference manual for a detailed +description of the format string syntax. For a demonstration of the +implemented directives see `formatst.scm'. + + This implementation supports directive parameters and modifiers (`:' +and `@' characters). Multiple parameters must be separated by a comma +(`,'). Parameters can be numerical parameters (positive or negative), +character parameters (prefixed by a quote character (`''), variable +parameters (`v'), number of rest arguments parameter (`#'), empty and +default parameters. Directive characters are case independent. The +general form of a directive is: + +DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER + +DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ] + +*** Implemented CL Format Control Directives + + Documentation syntax: Uppercase characters represent the +corresponding control directive characters. Lowercase characters +represent control directive parameter descriptions. + +`~A' + Any (print as `display' does). + `~@A' + left pad. + + `~MINCOL,COLINC,MINPAD,PADCHARA' + full padding. + +`~S' + S-expression (print as `write' does). + `~@S' + left pad. + + `~MINCOL,COLINC,MINPAD,PADCHARS' + full padding. + +`~D' + Decimal. + `~@D' + print number sign always. + + `~:D' + print comma separated. + + `~MINCOL,PADCHAR,COMMACHARD' + padding. + +`~X' + Hexadecimal. + `~@X' + print number sign always. + + `~:X' + print comma separated. + + `~MINCOL,PADCHAR,COMMACHARX' + padding. + +`~O' + Octal. + `~@O' + print number sign always. + + `~:O' + print comma separated. + + `~MINCOL,PADCHAR,COMMACHARO' + padding. + +`~B' + Binary. + `~@B' + print number sign always. + + `~:B' + print comma separated. + + `~MINCOL,PADCHAR,COMMACHARB' + padding. + +`~NR' + Radix N. + `~N,MINCOL,PADCHAR,COMMACHARR' + padding. + +`~@R' + print a number as a Roman numeral. + +`~:@R' + print a number as an "old fashioned" Roman numeral. + +`~:R' + print a number as an ordinal English number. + +`~:@R' + print a number as a cardinal English number. + +`~P' + Plural. + `~@P' + prints `y' and `ies'. + + `~:P' + as `~P but jumps 1 argument backward.' + + `~:@P' + as `~@P but jumps 1 argument backward.' + +`~C' + Character. + `~@C' + prints a character as the reader can understand it (i.e. `#\' + prefixing). + + `~:C' + prints a character as emacs does (eg. `^C' for ASCII 03). + +`~F' + Fixed-format floating-point (prints a flonum like MMM.NNN). + `~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF' + `~@F' + If the number is positive a plus sign is printed. + +`~E' + Exponential floating-point (prints a flonum like MMM.NNN`E'EE). + `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE' + `~@E' + If the number is positive a plus sign is printed. + +`~G' + General floating-point (prints a flonum either fixed or + exponential). + `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG' + `~@G' + If the number is positive a plus sign is printed. + +`~$' + Dollars floating-point (prints a flonum in fixed with signs + separated). + `~DIGITS,SCALE,WIDTH,PADCHAR$' + `~@$' + If the number is positive a plus sign is printed. + + `~:@$' + A sign is always printed and appears before the padding. + + `~:$' + The sign appears before the padding. + +`~%' + Newline. + `~N%' + print N newlines. + +`~&' + print newline if not at the beginning of the output line. + `~N&' + prints `~&' and then N-1 newlines. + +`~|' + Page Separator. + `~N|' + print N page separators. + +`~~' + Tilde. + `~N~' + print N tildes. + +`~' + Continuation Line. + `~:' + newline is ignored, white space left. + + `~@' + newline is left, white space ignored. + +`~T' + Tabulation. + `~@T' + relative tabulation. + + `~COLNUM,COLINCT' + full tabulation. + +`~?' + Indirection (expects indirect arguments as a list). + `~@?' + extracts indirect arguments from format arguments. + +`~(STR~)' + Case conversion (converts by `string-downcase'). + `~:(STR~)' + converts by `string-capitalize'. + + `~@(STR~)' + converts by `string-capitalize-first'. + + `~:@(STR~)' + converts by `string-upcase'. + +`~*' + Argument Jumping (jumps 1 argument forward). + `~N*' + jumps N arguments forward. + + `~:*' + jumps 1 argument backward. + + `~N:*' + jumps N arguments backward. + + `~@*' + jumps to the 0th argument. + + `~N@*' + jumps to the Nth argument (beginning from 0) + +`~[STR0~;STR1~;...~;STRN~]' + Conditional Expression (numerical clause conditional). + `~N[' + take argument from N. + + `~@[' + true test conditional. + + `~:[' + if-else-then conditional. + + `~;' + clause separator. + + `~:;' + default clause follows. + +`~{STR~}' + Iteration (args come from the next argument (a list)). + `~N{' + at most N iterations. + + `~:{' + args from next arg (a list of lists). + + `~@{' + args from the rest of arguments. + + `~:@{' + args from the rest args (lists). + +`~^' + Up and out. + `~N^' + aborts if N = 0 + + `~N,M^' + aborts if N = M + + `~N,M,K^' + aborts if N <= M <= K + +*** Not Implemented CL Format Control Directives + +`~:A' + print `#f' as an empty list (see below). + +`~:S' + print `#f' as an empty list (see below). + +`~<~>' + Justification. + +`~:^' + (sorry I don't understand its semantics completely) + +*** Extended, Replaced and Additional Control Directives + +`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD' +`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX' +`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO' +`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB' +`~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR' + COMMAWIDTH is the number of characters between two comma + characters. + +`~I' + print a R4RS complex number as `~F~@Fi' with passed parameters for + `~F'. + +`~Y' + Pretty print formatting of an argument for scheme code lists. + +`~K' + Same as `~?.' + +`~!' + Flushes the output if format DESTINATION is a port. + +`~_' + Print a `#\space' character + `~N_' + print N `#\space' characters. + +`~/' + Print a `#\tab' character + `~N/' + print N `#\tab' characters. + +`~NC' + Takes N as an integer representation for a character. No arguments + are consumed. N is converted to a character by `integer->char'. N + must be a positive decimal number. + +`~:S' + Print out readproof. Prints out internal objects represented as + `#<...>' as strings `"#<...>"' so that the format output can always + be processed by `read'. + +`~:A' + Print out readproof. Prints out internal objects represented as + `#<...>' as strings `"#<...>"' so that the format output can always + be processed by `read'. + +`~Q' + Prints information and a copyright notice on the format + implementation. + `~:Q' + prints format version. + +`~F, ~E, ~G, ~$' + may also print number strings, i.e. passing a number as a string + and format it accordingly. + +*** Configuration Variables + + The format module exports some configuration variables to suit the +systems and users needs. There should be no modification necessary for +the configuration that comes with Guile. Format detects automatically +if the running scheme system implements floating point numbers and +complex numbers. + +format:symbol-case-conv + Symbols are converted by `symbol->string' so the case type of the + printed symbols is implementation dependent. + `format:symbol-case-conv' is a one arg closure which is either + `#f' (no conversion), `string-upcase', `string-downcase' or + `string-capitalize'. (default `#f') + +format:iobj-case-conv + As FORMAT:SYMBOL-CASE-CONV but applies for the representation of + implementation internal objects. (default `#f') + +format:expch + The character prefixing the exponent value in `~E' printing. + (default `#\E') + +*** Compatibility With Other Format Implementations + +SLIB format 2.x: + See `format.doc'. + +SLIB format 1.4: + Downward compatible except for padding support and `~A', `~S', + `~P', `~X' uppercase printing. SLIB format 1.4 uses C-style + `printf' padding support which is completely replaced by the CL + `format' padding style. + +MIT C-Scheme 7.1: + Downward compatible except for `~', which is not documented + (ignores all characters inside the format string up to a newline + character). (7.1 implements `~a', `~s', ~NEWLINE, `~~', `~%', + numerical and variable parameters and `:/@' modifiers in the CL + sense). + +Elk 1.5/2.0: + Downward compatible except for `~A' and `~S' which print in + uppercase. (Elk implements `~a', `~s', `~~', and `~%' (no + directive parameters or modifiers)). + +Scheme->C 01nov91: + Downward compatible except for an optional destination parameter: + S2C accepts a format call without a destination which returns a + formatted string. This is equivalent to a #f destination in S2C. + (S2C implements `~a', `~s', `~c', `~%', and `~~' (no directive + parameters or modifiers)). + + +** Changes to string-handling functions. + +These functions were added to support the (ice-9 format) module, above. + +*** New function: string-upcase STRING +*** New function: string-downcase STRING + +These are non-destructive versions of the existing string-upcase! and +string-downcase! functions. + +*** New function: string-capitalize! STRING +*** New function: string-capitalize STRING + +These functions convert the first letter of each word in the string to +upper case. Thus: + + (string-capitalize "howdy there") + => "Howdy There" + +As with the other functions, string-capitalize! modifies the string in +place, while string-capitalize returns a modified copy of its argument. + +*** New function: string-ci->symbol STRING + +Return a symbol whose name is STRING, but having the same case as if +the symbol had be read by `read'. + +Guile can be configured to be sensitive or insensitive to case +differences in Scheme identifiers. If Guile is case-insensitive, all +symbols are converted to lower case on input. The `string-ci->symbol' +function returns a symbol whose name in STRING, transformed as Guile +would if STRING were input. + +*** New function: substring-move! STRING1 START END STRING2 START + +Copy the substring of STRING1 from START (inclusive) to END +(exclusive) to STRING2 at START. STRING1 and STRING2 may be the same +string, and the source and destination areas may overlap; in all +cases, the function behaves as if all the characters were copied +simultanously. + +*** Extended functions: substring-move-left! substring-move-right! + +These functions now correctly copy arbitrarily overlapping substrings; +they are both synonyms for substring-move!. + + +** 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* ( ...) ...) +Each should have one of the following forms: + ( ) + () + +Each or should be an identifier. Each + should be a valid expression. The should be a +possibly empty sequence of expressions, like the of a +lambda form. + +Semantics: A LAND* expression is evaluated by evaluating the + or of each of the s from +left to right. The value of the first or + that evaluates to a false value is returned; the +remaining s and s are not evaluated. +The forms are evaluated iff all the s and +s evaluate to true values. + +The s and the are evaluated in an environment +binding each of the preceding ( ) +clauses to the value of the . Later bindings +shadow earlier bindings. + +Guile's and-let* macro was contributed by Michael Livshin. + +** New sorting functions + +*** 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 built-in random number support + +*** 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. + +** the procedures uniform-array-read! and uniform-array-write! now +work on any kind of port, not just ports which are open on a file. + +** Now 'l' in a port mode requests line buffering. + +** The procedure truncate-file now works on string ports as well +as file ports. If the size argument is omitted, the current +file position is used. + +** new procedure: seek PORT/FDES OFFSET WHENCE +The arguments are the same as for the old fseek procedure, but it +works on string ports as well as random-access file ports. + +** the fseek procedure now works on string ports, since it has been +redefined using seek. + +** the setvbuf procedure now uses a default size if mode is _IOFBF and +size is not supplied. + +** the newline procedure no longer flushes the port if it's not +line-buffered: previously it did if it was the current output port. + +** open-pipe and close-pipe are no longer primitive procedures, but +an emulation can be obtained using `(use-modules (ice-9 popen))'. + +** the freopen procedure has been removed. + +** new procedure: drain-input PORT +Drains PORT's read buffers (including any pushed-back characters) +and returns the contents as a single string. + +** 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. + +** `ls' and `lls' in module (ice-9 ls) now handle no arguments. + +These procedures return a list of definitions available in the specified +argument, a relative module reference. In the case of no argument, +`(current-module)' is now consulted for definitions to return, instead +of simply returning #f, the former behavior. + +** The #/ syntax for lists is no longer supported. + +Earlier versions of Scheme accepted this syntax, but printed a +warning. + +** Guile no longer consults the SCHEME_LOAD_PATH environment variable. + +Instead, you should set GUILE_LOAD_PATH to tell Guile where to find +modules. + +* 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 + +** Function: scm_make_named_hook (char* name, int n_args) + +Creates a hook in the same way as make-hook above but also +binds a variable named NAME to it. + +This is the typical way of creating a hook from C code. + +Currently, the variable is created in the "current" module. This +might change when we get the new module system. + +** The smob interface + +The interface for creating smobs has changed. For documentation, see +data-rep.info (made from guile-core/doc/data-rep.texi). + +*** Deprecated function: SCM scm_newsmob (scm_smobfuns *) + +>>> This function will be removed in 1.3.4. <<< + +It is replaced by: + +*** Function: SCM scm_make_smob_type (const char *name, scm_sizet size) +This function adds a new smob type, named NAME, with instance size +SIZE to the system. The return value is a tag that is used in +creating instances of the type. If SIZE is 0, then no memory will +be allocated when instances of the smob are created, and nothing +will be freed by the default free function. + +*** Function: void scm_set_smob_mark (long tc, SCM (*mark) (SCM)) +This function sets the smob marking procedure for the smob type +specified by the tag TC. TC is the tag returned by +`scm_make_smob_type'. + +*** Function: void scm_set_smob_free (long tc, SCM (*mark) (SCM)) +This function sets the smob freeing procedure for the smob type +specified by the tag TC. TC is the tag returned by +`scm_make_smob_type'. + +*** Function: void scm_set_smob_print (tc, print) + + - Function: void scm_set_smob_print (long tc, + scm_sizet (*print) (SCM, + SCM, + scm_print_state *)) + +This function sets the smob printing procedure for the smob type +specified by the tag TC. TC is the tag returned by +`scm_make_smob_type'. + +*** Function: void scm_set_smob_equalp (long tc, SCM (*equalp) (SCM, SCM)) +This function sets the smob equality-testing predicate for the +smob type specified by the tag TC. TC is the tag returned by +`scm_make_smob_type'. + +*** Macro: void SCM_NEWSMOB (SCM var, long tc, void *data) +Make VALUE contain a smob instance of the type with type code TC and +smob data DATA. VALUE must be previously declared as C type `SCM'. + +*** Macro: fn_returns SCM_RETURN_NEWSMOB (long tc, void *data) +This macro expands to a block of code that creates a smob instance +of the type with type code TC and smob data DATA, and returns that +`SCM' value. It should be the last piece of code in a block. + +** The interfaces for using I/O ports and implementing port types +(ptobs) have changed significantly. The new interface is based on +shared access to buffers and a new set of ptob procedures. + +*** scm_newptob has been removed + +It is replaced by: + +*** Function: SCM scm_make_port_type (type_name, fill_buffer, write_flush) + +- Function: SCM scm_make_port_type (char *type_name, + int (*fill_buffer) (SCM port), + void (*write_flush) (SCM port)); + +Similarly to the new smob interface, there is a set of function +setters by which the user can customize the behaviour of his port +type. See ports.h (scm_set_port_XXX). + +** scm_strport_to_string: New function: creates a new string from +a string port's buffer. + +** 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. + +The default random state is stored in: + +*** 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_c_uniform01 (SCM_RSTATE (SCM_CDR (scm_var_random_state))); + +*** Function: scm_rstate *scm_c_default_rstate (void) +This is a convenience function which returns the value of +scm_var_random_state. An error message is generated if this value +isn't a random state. + +*** Function: scm_rstate *scm_c_make_rstate (char *SEED, int LENGTH) +Make a new random state from the string SEED of length LENGTH. + +It is generally not a good idea to use multiple random states in a +program. While subsequent random numbers generated from one random +state are guaranteed to be reasonably independent, there is no such +guarantee for numbers generated from different random states. + +*** Macro: unsigned long scm_c_uniform32 (scm_rstate *STATE) +Return 32 random bits. + +*** Function: double scm_c_uniform01 (scm_rstate *STATE) +Return a sample from the uniform(0,1) distribution. + +*** Function: double scm_c_normal01 (scm_rstate *STATE) +Return a sample from the normal(0,1) distribution. + +*** Function: double scm_c_exp1 (scm_rstate *STATE) +Return a sample from the exp(1) distribution. + +*** Function: unsigned long scm_c_random (scm_rstate *STATE, unsigned long M) +Return a sample from the discrete uniform(0,M) distribution. + +*** Function: SCM scm_c_random_bignum (scm_rstate *STATE, SCM M) +Return a sample from the discrete uniform(0,M) distribution. +M must be a bignum object. The returned value may be an INUM. + + + +Changes in Guile 1.3 (released Monday, October 19, 1998): * 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, 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. + +** 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. + +** 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 # + debug: untrace # + the-scm-module: display-backtrace #> + the-scm-module: before-backtrace-hook () + the-scm-module: 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). + +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 +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 +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. @@ -57,78 +1964,88 @@ Macro: with-fluids ((FLUID VALUE) ...) FORM ... fluids are not special variables but ordinary objects. FLUID should evaluate to a fluid. -* Changes to system call interfaces: +** Changes to system call interfaces: -** close-port, close-input-port and close-output-port now return a +*** 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 +*** the first argument to chmod, fcntl, ftell and fseek can now be a file descriptor. -** the third argument to fcntl is now optional. +*** the third argument to fcntl is now optional. -** the first argument to chown can now be a file descriptor or a port. +*** the first argument to chown can now be a file descriptor or a port. -** the argument to stat can now be a port. +*** the argument to stat can now be a port. -** The following new procedures have been added (most use scsh +*** 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. - -** dup->inport PORT/FD [NEWFD] -Returns a new input port using the new file descriptor. +*** procedure: dup->fdes PORT/FD [NEWFD] + Returns an integer file descriptor. -** dup->outport PORT/FD [NEWFD] -Returns a new output port using the new file descriptor. +*** procedure: dup->inport PORT/FD [NEWFD] + Returns a new input port using the new file descriptor. -** 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->outport PORT/FD [NEWFD] + Returns a new output port using the new file descriptor. -** 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'). +*** 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. -** port->fdes PORT -Returns the integer file descriptor underlying PORT. As a -side effect the revealed count of PORT is incremented. +*** 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.). -** 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: setenv NAME VALUE + Modifies the environment of the current process, which is also the + default environment inherited by child processes. -** 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. + 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. -** 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. + The return value is unspecified. -** truncate-file OBJ SIZE +*** 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 @@ -136,7 +2053,7 @@ value for NAME. The return value is unspecified. -** setvbuf PORT MODE [SIZE] +*** procedure: setvbuf PORT MODE [SIZE] Set the buffering mode for PORT. MODE can be: `_IONBF' non-buffered @@ -156,16 +2073,16 @@ value for NAME. size. Procedures e.g., *Note open-file: File Ports, which accept a mode string allow `0' to be added to request an unbuffered port. -** fsync PORT/FD +*** 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. -** open-fdes PATH FLAGS [MODES] +*** procedure: open-fdes PATH FLAGS [MODES] Similar to `open' but returns a file descriptor instead of a port. -** procedure: execle PATH ENV [ARG] ... +*** 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. @@ -174,12 +2091,15 @@ value for NAME. call, but we call it `execle' because of its Scheme calling interface. -** procedure: primitive-exit [STATUS] +*** 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 +*** 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: @@ -204,10 +2124,188 @@ value for NAME. 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. + +** 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 +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, @@ -215,6 +2313,68 @@ 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. + +** 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. + +** 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): @@ -1398,7 +3558,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 @@ -1792,7 +3952,7 @@ null-terminated string, and returns it. 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. Older changes: