X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/f5d54eb740f10e2ce4368e4fa807c7b5a863ca37..0b5a0521d121f525d340fc72e385a7c0f8cea65f:/NEWS diff --git a/NEWS b/NEWS index e01646070..31054acb0 100644 --- a/NEWS +++ b/NEWS @@ -12,7 +12,7 @@ Each release reports the NEWS in the following sections: * Changes to the C interface -Changes since the stable branch: +Changes since the 1.6.x series: * Changes to the distribution @@ -23,37 +23,21 @@ Changes since the stable branch: ** Guile now requires GNU MP (http://swox.com/gmp). Guile now uses the GNU MP library for arbitrary precision arithmetic. -At the moment it is being used to handle Guile's bignums. ** Guile now has separate private and public configuration headers. -Guile now has config.h and libguile/scmconfig.h. The former is not -installed and is private. The latter is installed and used by Guile's -public headers. config.h is generated by configure and autoheader, -and scmconfig.h is generated by a small C program, gen-scmconfig at -build time based in part on the contents of config.h. - -Seen libguile/__scm.h and gen-scmconfig.c for more information. - -Note too that nearly all public defines are now set to either 1 or 0 -rather than being set to 1 or left undefined. See gen-scmconfig.c and -the GNU Coding Guidelines for the rationale. However, pre-existing -defines that were not renamed were not changed. i.e. GUILE_DEBUG is -still either 1 or undefined. - -** The INSTALL file is now the generic automake installed one. - -Guile specific instructions can be found in the README. +That is, things like HAVE_STRING_H no longer leak from Guile's +headers. ** Guile now provides and uses an "effective" version number. Guile now provides scm_effective_version and effective-version functions which return the "effective" version number. This is just the normal full version string without the final micro-version number, -so the current effective-version is "1.6". The effective version +so the current effective-version is "1.7". The effective version should remain unchanged during a stable series, and should be used for items like the versioned share directory name -i.e. /usr/share/guile/1.6. +i.e. /usr/share/guile/1.7. Providing an unchanging version number during a stable release for things like the versioned share directory can be particularly @@ -79,6 +63,24 @@ the GC. See the manual for details. [XXX - write this.] The default is "pthreads", unless your platform doesn't have pthreads, in which case "null" threads are used. +** There is the new notion of 'discouraged' features. + +This is a milder form of deprecation. + +Things that are discouraged should not be used in new code, but it is +OK to leave them in old code for now. When a discouraged feature is +used, no warning message is printed like there is for 'deprecated' +features. Also, things that are merely discouraged are nevertheless +implemented efficiently, while deprecated features can be very slow. + +You can omit discouraged features from libguile by configuring it with +the '--disable-discouraged' option. + +** Deprecation warnings can be controlled at run-time. + +(debug-enable 'warn-deprecated) switches them on and (debug-disable +'warn-deprecated) switches them off. + ** New module (ice-9 serialize): (serialize FORM1 ...) and (parallelize FORM1 ...) are useful when @@ -86,6 +88,8 @@ you don't trust the thread safety of most of your program, but where you have some section(s) of code which you consider can run in parallel to other sections. +### move rest to manual + They "flag" (with dynamic extent) sections of code to be of "serial" or "parallel" nature and have the single effect of preventing a serial section from being run in parallel with any @@ -123,13 +127,33 @@ This is an implementation of SRFI-26. This is an implementation of SRFI-31 which provides a special form `rec' for recursive evaluation. -** Guile now includes its own version of libltdl. +** The modules (srfi srfi-13), (srfi srfi-14) and (srfi srfi-4) have + been merged with the core, making their functionality always + available. + +The modules are still available, tho, and you could use them together +with a renaming import, for example. -We now use a modified version of libltdl that allows us to make -improvements to it without having to rely on libtool releases. +** Guile no longer includes its own version of libltdl. + +The official version is good enough now. + +** The --enable-htmldoc option has been removed from 'configure'. + +Support for translating the documentation into HTML is now always +provided. Use 'make html'. + +** The configure option '--disable-arrays' has been removed. + +Support for arrays and uniform numeric arrays is now always included +in Guile. * Changes to the stand-alone interpreter +** New command line option `-L'. + +This option adds a directory to the front of the load path. + ** New command line option `--no-debug'. Specifying `--no-debug' on the command line will keep the debugging @@ -158,6 +182,67 @@ be used with '-e'. For example, you can now write a script like * Changes to Scheme functions and syntax +** The default load path no longer includes "." at the end. + +Automatically loading modules from the current directory should not +happen by default. If you want to allow it in a more controlled +manner, set the environment variable GUILE_LOAD_PATH or the Scheme +variable %load-path. + +** The uniform vector and array support has been overhauled. + +It now complies with SRFI-4 and the weird prototype based uniform +array creation has been deprecated. See the manual for more details. + +Some non-compatible changes have been made: + - characters can no longer be stored into byte arrays. + - strings and bit vectors are no longer considered to be uniform vectors. + - array-rank throws an error for non-arrays instead of returning zero. + - array-ref does no longer accept non-arrays when no indices are given. + +There is the new notion of 'generalized vectors' and corresponding +procedures like 'generalized-vector-ref'. Generalized vectors include +strings, bitvectors, ordinary vectors, and uniform numeric vectors. + +Arrays use generalized vectors their storage, so that you still have +arrays of characters, bits, etc. However, uniform-array-read! and +uniform-array-write can no longer read/write strings and bitvectors. + +** There is now support for copy-on-write substrings, mutation-sharing + substrings and read-only strings. + +Three new procedures are related to this: substring/shared, +substring/copy, and substring/read-only. See the manual for more +information. + +** Backtraces will now highlight the value that caused the error. + +By default, these values are enclosed in "{...}", such as in this +example: + + guile> (car 'a) + + Backtrace: + In current input: + 1: 0* [car {a}] + + :1:1: In procedure car in expression (car (quote a)): + :1:1: Wrong type (expecting pair): a + ABORT: (wrong-type-arg) + +The prefix and suffix used for highlighting can be set via the two new +printer options 'highlight-prefix' and 'highlight-suffix'. For +example, putting this into ~/.guile will output the bad value in bold +on an ANSI terminal: + + (print-set! highlight-prefix "\x1b[1m") + (print-set! highlight-suffix "\x1b[22m") + + +** 'gettext' support for internationalization has been added. + +See the manual for details. + ** New syntax '@' and '@@': You can now directly refer to variables exported from a module by @@ -168,13 +253,44 @@ writing For example (@ (ice-9 pretty-print) pretty-print) will directly access the pretty-print variable exported from the (ice-9 pretty-print) module. You don't need to 'use' that module first. You can also use -'@' with 'set!'. +'@' as a target of 'set!', as in (set! (@ mod var) val). The related syntax (@@ MODULE-NAME VARIABLE-NAME) works just like '@', but it can also access variables that have not been exported. It is intended only for kluges and temporary fixes and for debugging, not for ordinary code. +** Keyword syntax has been made more disciplined. + +Previously, the name of a keyword was read as a 'token' but printed as +a symbol. Now, it is read as a general Scheme datum which must be a +symbol. + +Previously: + + guile> #:12 + #:#{12}# + guile> #:#{12}# + #:#{\#{12}\#}# + guile> #:(a b c) + #:#{}# + ERROR: In expression (a b c): + Unbound variable: a + guile> #: foo + #:#{}# + ERROR: Unbound variable: foo + +Now: + + guile> #:12 + ERROR: Wrong type (expecting symbol): 12 + guile> #:#{12}# + #:#{12}# + guile> #:(a b c) + ERROR: Wrong type (expecting symbol): (a b c) + guile> #: foo + #:foo + ** 'while' now provides 'break' and 'continue' break and continue were previously bound in a while loop, but not @@ -185,12 +301,12 @@ dropped. ** 'call-with-current-continuation' is now also available under the name 'call/cc'. -** Checking for duplicate bindings in module system +** The module system now checks for duplicate bindings. The module system now can check for name conflicts among imported bindings. -The behavior can be controlled by specifying one or more duplicates +The behavior can be controlled by specifying one or more 'duplicates' handlers. For example, to make Guile return an error for every name collision, write: @@ -214,6 +330,8 @@ can add the line: to your .guile init file. +### move rest to manual + The syntax for the :duplicates option is: :duplicates HANDLER-NAME | (HANDLER1-NAME HANDLER2-NAME ...) @@ -266,7 +384,13 @@ a prefix to all imported bindings. will import all bindings exported from bar, but rename them by adding the prefix `bar:'. -** Merging generic functions +** Conflicting generic functions can be automatically merged. + +When two imported bindings conflict and they are both generic +functions, the two functions can now be merged automatically. This is +activated with the 'duplicates' handler 'merge-generics'. + +### move the rest to the manual It is sometimes tempting to use GOOPS accessors with short names. For example, it is tempting to use the name `x' for the x-coordinate @@ -329,10 +453,10 @@ Returns the "effective" version number. This is just the normal full version string without the final micro-version number. See "Changes to the distribution" above. -** Futures: future, make-future, future-ref +** New feature, 'futures': future, make-future, future-ref -Futures are like promises, but begun immediately in a new thread. See -the "Futures" section in the reference manual. +Futures are like promises, but begin execution immediately in a new +thread. See the "Futures" section in the reference manual. ** New threading functions: parallel, letpar, par-map, and friends @@ -356,7 +480,7 @@ A fair condition variable must be used together with a fair mutex, just as a standard condition variable must be used together with a standard mutex. -** New functions: make-fair-mutex, make-fair-condition-variable' +*** New functions: make-fair-mutex, make-fair-condition-variable' Make a new fair mutex and a new fair condition variable respectively. @@ -508,9 +632,9 @@ Previously, (odd? 1.0) would signal an error since only exact integers were recognized as integers. Now (odd? 1.0) returns #t, (odd? 2.0) returns #f and (odd? 1.5) signals an error. -** We now have uninterned symbols. +** Guile now has uninterned symbols. -The new function 'make-symbol' will return a uninterned symbol. This +The new function 'make-symbol' will return an uninterned symbol. This is a symbol that is unique and is guaranteed to remain unique. However, uninterned symbols can not yet be read back in. @@ -536,9 +660,9 @@ when evaluated and simply be ignored in a definition context. ** Deprecated: procedure->macro -Change your code to use either procedure->memoizing-macro or, probably better, -to use r5rs macros. Also, be aware that macro expansion will not be done -during evaluation, but prior to evaluation. +Change your code to use 'define-macro' or r5rs macros. Also, be aware +that macro expansion will not be done during evaluation, but prior to +evaluation. ** Soft ports now allow a `char-ready?' procedure @@ -557,335 +681,342 @@ chapter in the reference manual. There is no replacement for undefine. -** call-with-output-string doesn't segv on closed port - -Previously call-with-output-string would give a segmentation fault if -the string port was closed by the called function. An exception is -raised now. +* The functions make-keyword-from-dash-symbol and keyword-dash-symbol + have been discouraged. -** (ice-9 popen) duplicate pipe fd fix +They are relics from a time where a keyword like #:foo was used +directly as a Tcl option "-foo" and thus keywords were internally +stored as a symbol with a starting dash. We now store a symbol +without the dash. -open-pipe, open-input-pipe and open-output-pipe left an extra copy of -their pipe file descriptor in the child, which was normally harmless, -but it can prevent the parent seeing eof or a broken pipe immediately -and has now been fixed. +Use symbol->keyword and keyword->symbol instead. -** source-properties and set-source-properties! fix -Properties set with set-source-properties! can now be read back -correctly with source-properties. - -** SRFI-1 fixes - -delete and delete! now call the "=" procedure with arguments in the -order described by the SRFI-1 specification - -list-copy now accepts improper lists, per the specification. - -** SRFI-4 fixes - -Larger values in 64-bit vectors should print correctly now. - -** SRFI-19 fixes +* Changes to the C interface -date-week-number now correctly respects the requested day of week -starting the week. +** A new family of functions for converting between C values and + Scheme values has been added. -* Changes to the C interface +These functions follow a common naming scheme and are designed to be +easier to use, thread-safe and more future-proof than the older +alternatives. -** SCM_CELL_WORD_LOC has been deprecated. + - int scm_is_* (...) + + These are predicates that return a C boolean: 1 or 0. Instead of + SCM_NFALSEP, you can now use scm_is_true, for example. -Use the new macro SCM_CELL_OBJECT_LOC instead, which return a pointer -to a SCM, as opposed to a pointer to a scm_t_bits. + - scm_to_ (SCM val, ...) -This was done to allow the correct use of pointers into the Scheme -heap. Previously, the heap words were of type scm_t_bits and local -variables and function arguments were of type SCM, making it -non-standards-conformant to have a pointer that can point to both. + These are functions that convert a Scheme value into an appropriate + C value. For example, you can use scm_to_int to safely convert from + a SCM to an int. -** New macros SCM_SMOB_DATA_2, SM_SMOB_DATA_3, etc. + - SCM scm_from_ ( val, ...) -These macros should be used instead of SCM_CELL_WORD_2/3 to access the -second and third words of double smobs. Likewise for -SCM_SET_SMOB_DATA_2 and SCM_SET_SMOB_DATA_3. + These functions convert from a C type to a SCM value; for example, + scm_from_int for ints. -Also, there is SCM_SMOB_FLAGS and SCM_SET_SMOB_FLAGS that should be -used to get and set the 16 exra bits in the zeroth word of a smob. +There is a huge number of these functions, for numbers, strings, +symbols, vectors, etc. They are documented in the reference manual in +the API section together with the types that they apply to. -And finally, there is SCM_SMOB_OBJECT and SCM_SMOB_SET_OBJECT for -accesing the first immediate word of a smob as a SCM value, and there -is SCM_SMOB_OBJECT_LOC for getting a pointer to the first immediate -smob words. Like wise for SCM_SMOB_OBJECT_2, etc. +** New functions for dealing with complex numbers in C have been added. -** New way to deal with non-local exits and reentries. +The new functions are scm_c_make_rectangular, scm_c_make_polar, +scm_c_real_part, scm_c_imag_part, scm_c_magnitude and scm_c_angle. +They work like scm_make_rectangular etc but take or return doubles +directly. -There is a new set of functions that essentially do what -scm_internal_dynamic_wind does, but in a way that is more convenient -for C code in some situations. Here is a quick example of how to -prevent a potential memory leak: +** The function scm_make_complex has been discouraged. - void - foo () - { - char *mem; +Use scm_c_make_rectangular instead. - scm_frame_begin (0); +** The INUM macros have been deprecated. - mem = scm_malloc (100); - scm_frame_unwind_handler (free, mem, SCM_F_WIND_EXPLICITELY); +A lot of code uses these macros to do general integer conversions, +although the macros only work correctly with fixnums. Use the +following alternatives. - /* MEM would leak if BAR throws an error. - SCM_FRAME_UNWIND_HANDLER frees it nevertheless. */ + SCM_INUMP -> scm_is_integer or similar + SCM_NINUMP -> !scm_is_integer or similar + SCM_MAKINUM -> scm_from_int or similar + SCM_INUM -> scm_to_int or similar - bar (); - - scm_frame_end (); + SCM_VALIDATE_INUM_* -> Do not use these; scm_to_int, etc. will + do the validating for you. - /* Because of SCM_F_WIND_EXPLICITELY, MEM will be freed by - SCM_FRAME_END as well. - */ - } +** The scm_num2 and scm_2num functions and scm_make_real + have been discouraged. -For full documentation, see the node "Frames" in the manual. +Use the newer scm_to_ and scm_from_ functions instead for +new code. The functions have been discouraged since they don't fit +the naming scheme. -** New way to block and unblock asyncs +** The 'boolean' macros SCM_FALSEP etc have been discouraged. -In addition to scm_c_call_with_blocked_asyncs you can now also use -scm_frame_block_asyncs in a 'frame' (see above). Likewise for -scm_c_call_with_unblocked_asyncs and scm_frame_unblock_asyncs. +They have strange names, especially SCM_NFALSEP, and SCM_BOOLP +evaluates its argument twice. Use scm_is_true, etc. instead for new +code. -** New way to temporarily set the current input, output or error ports +** The macro SCM_EQ_P has been discouraged. -C code can now use scm_frame_current__port in a 'frame' (see -above). is one of "input", "output" or "error". +Use scm_is_eq for new code, which fits better into the naming +conventions. -** New way to temporarily set fluids +** The macros SCM_CONSP, SCM_NCONSP, SCM_NULLP, and SCM_NNULLP have + been discouraged. -C code can now use scm_frame_fluid in a 'frame' (see -above) to temporarily set the value of a fluid. +Use the function scm_is_pair or scm_is_null instead. -** New types scm_t_intmax and scm_t_uintmax. +** The functions scm_round and scm_truncate have been deprecated and + are now available as scm_c_round and scm_c_truncate, respectively. -On platforms that have them, these types are identical to intmax_t and -uintmax_t, respectively. On other platforms, they are identical to -the largest integer types that Guile knows about. +These functions occupy the names that scm_round_number and +scm_truncate_number should have. -** Many public #defines with generic names have been made private. +** The functions scm_c_string2str, scm_c_substring2str, and + scm_c_symbol2str have been deprecated. -#defines with generic names like HAVE_FOO or SIZEOF_FOO have been made -private or renamed with a more suitable public name. See below for -the ones which have been renamed. +Use scm_to_locale_stringbuf or similar instead, maybe together with +scm_substring. -** HAVE_STDINT_H and HAVE_INTTYPES_H have been removed from public use. +** New functions scm_c_make_string, scm_c_string_length, + scm_c_string_ref, scm_c_string_set_x, scm_c_substring, + scm_c_substring_shared, scm_c_substring_copy. -HAVE_STDINT_H and HAVE_INTTYPES_H removed from public use. These are -no longer needed since the older uses of stdint.h and inttypes.h are -now handled by configure.in and gen-scmconfig.c. +These are like scm_make_string, scm_length, etc. but are slightly +easier to use from C. -** USE_DLL_IMPORT is no longer defined publically. +** The macros SCM_STRINGP, SCM_STRING_CHARS, SCM_STRING_LENGTH, + SCM_SYMBOL_CHARS, and SCM_SYMBOL_LENGTH have been deprecated. -gen-scmconfig now uses it to decide what contents to place in the -public scmconfig.h header without adding the USE_DLL_IMPORT itself. +They export too many assumptions about the implementation of strings +and symbols that are no longer true in the presence of +mutation-sharing substrings and when Guile switches to some form of +Unicode. -** HAVE_LIMITS_H has been removed from public use. +When working with strings, it is often best to use the normal string +functions provided by Guile, such as scm_c_string_ref, +scm_c_string_set_x, scm_string_append, etc. Be sure to look in the +manual since many more such functions are now provided than +previously. -gen-scmconfig now just uses HAVE_LIMITS_H to decide whether or not to -add a limits.h include in scmconfig.h. +When you want to convert a SCM string to a C string, use the +scm_to_locale_string function or similar instead. For symbols, use +scm_symbol_to_string and then work with that string. Because of the +new string representation, scm_symbol_to_string does not need to copy +and is thus quite efficient. -** time.h, sys/time.h, etc. #ifdefery has been removed from public headers. +** Some string, symbol and keyword functions have been discouraged. -gen-scmconfig now just uses the same logic to decide what time related -#includes to add to scmconfig.h. +They don't fit into the uniform naming scheme and are not explicit +about the character encoding. -** HAVE_STRUCT_TIMESPEC has been removed from public use. +Replace according to the following table: -scmconfig.h now just defines scm_t_timespec. + scm_allocate_string -> scm_c_make_string + scm_take_str -> scm_take_locale_stringn + scm_take0str -> scm_take_locale_string + scm_mem2string -> scm_from_locale_stringn + scm_str2string -> scm_from_locale_string + scm_makfrom0str -> scm_from_locale_string + scm_mem2symbol -> scm_from_locale_symboln + scm_mem2uninterned_symbol -> scm_from_locale_stringn + scm_make_symbol + scm_str2symbol -> scm_from_locale_symbol -** HAVE_PTRDIFF has been removed from public use and Guile doesn't - define ptrdiff_t. + SCM_SYMBOL_HASH -> scm_hashq + SCM_SYMBOL_INTERNED_P -> scm_symbol_interned_p -Guile now publically defines scm_t_ptrdiff and -SCM_SIZEOF_SCM_T_PTRDIFF in scmconfig.h, and all occurrences of -ptrdiff_t have been replaced with scm_t_ptrdiff. + scm_c_make_keyword -> scm_from_locale_keyword -Guile defines its own type this rather than just relying on ptrdiff_t -and SCM_SIZEOF_PTRDIFF_T because Guile actually typedefs long to -scm_t_ptrdiff when ptrdiff_t isn't available. A public "typedef long -ptrdiff_t" could conflict with other headers. +** The functions scm_keyword_to_symbol and sym_symbol_to_keyword are + now also available to C code. -** HAVE_UINTPTR_T and HAVE_UINTPTR_T have been removed from public use. +** SCM_KEYWORDP and SCM_KEYWORDSYM have been deprecated. -They are replaced by public definitions of SCM_SIZEOF_UINTPTR_T and -SCM_SIZEOF_INTPTR_T. These are defined to 0 if the corresponding type -is not available. +Use scm_is_keyword and scm_keyword_to_symbol instead, but note that +the latter returns the true name of the keyword, not the 'dash name', +as SCM_KEYWORDSYM used to do. -** The public #define STDC_HEADERS has been renamed to SCM_HAVE_STDC_HEADERS. +** A new way to access arrays in a thread-safe and efficient way has + been added. -The previous name was too generic for the global public namespace. +See the manual, node "Accessing Arrays From C". -** The public #define HAVE_SYS_SELECT has been renamed to - SCM_HAVE_SYS_SELECT_H. +** The old uniform vector and bitvector implementations have been + unceremoniously removed. -The previous name was too generic for the global public namespace. +This implementation exposed the detailes of the tagging system of +Guile. Use the new C API explained in the manual in node "Uniform +Numeric Vectors" and "Bit Vectors", respectively. -** The public #define HAVE_FLOATINGPOINT_H has been renamed to - SCM_HAVE_FLOATINGPOINT_H. +The following macros are gone: SCM_UVECTOR_BASE, SCM_SET_UVECTOR_BASE, +SCM_UVECTOR_MAXLENGTH, SCM_UVECTOR_LENGTH, SCM_MAKE_UVECTOR_TAG, +SCM_SET_UVECTOR_LENGTH, SCM_BITVECTOR_P, SCM_BITVECTOR_BASE, +SCM_SET_BITVECTOR_BASE, SCM_BITVECTOR_MAX_LENGTH, +SCM_BITVECTOR_LENGTH, SCM_MAKE_BITVECTOR_TAG, +SCM_SET_BITVECTOR_LENGTH, SCM_BITVEC_REF, SCM_BITVEC_SET, +SCM_BITVEC_CLR. -The previous name was too generic for the global public namespace. +** The macros dealing with vectors have been deprecated. -** The public #define HAVE_IEEEFP_H has been renamed to SCM_HAVE_IEEEFP_H. +Use the new functions scm_is_vector, scm_vector_elements, +scm_vector_writable_elements, etc, or scm_is_simple_vector, +SCM_SIMPLE_VECTOR_REF, SCM_SIMPLE_VECTOR_SET, etc instead. See the +manual for more details. -The previous name was too generic for the global public namespace. +Deprecated are SCM_VECTORP, SCM_VELTS, SCM_VECTOR_MAX_LENGTH, +SCM_VECTOR_LENGTH, SCM_VECTOR_REF, SCM_VECTOR_SET, SCM_WRITABLE_VELTS. -** The public #define HAVE_NAN_H has been renamed to SCM_HAVE_NAN_H. +The following macros have been removed: SCM_VECTOR_BASE, +SCM_SET_VECTOR_BASE, SCM_MAKE_VECTOR_TAG, SCM_SET_VECTOR_LENGTH, +SCM_VELTS_AS_STACKITEMS, SCM_SETVELTS, SCM_GC_WRITABLE_VELTS. -The previous name was too generic for the global public namespace. +** Some C functions and macros related to arrays have been deprecated. -** The public #define HAVE_WINSOCK2_H has been renamed to SCM_HAVE_WINSOCK2_H. +Migrate according to the following table: -The previous name was too generic for the global public namespace. + scm_make_uve -> scm_make_typed_aray, scm_make_u8vector etc. + scm_make_ra -> scm_make_array + scm_shap2ra -> scm_make_array + scm_cvref -> scm_c_generalized_vector_ref + scm_ra_set_contp -> do not use + scm_aind -> scm_array_handle_pos + scm_raprin1 -> scm_display or scm_write -** The public #define HAVE_ARRAYS has been renamed to SCM_HAVE_ARRAYS. + SCM_ARRAYP -> scm_is_array + SCM_ARRAY_NDIM -> scm_c_array_rank + SCM_ARRAY_DIMS -> scm_array_handle_dims + SCM_ARRAY_CONTP -> do not use + SCM_ARRAY_MEM -> do not use + SCM_ARRAY_V -> scm_array_handle_elements or similar + SCM_ARRAY_BASE -> do not use -The previous name was too generic for the global public namespace. +** SCM_CELL_WORD_LOC has been deprecated. -** The public #define STACK_GROWS_UP has been renamed to SCM_STACK_GROWS_UP. +Use the new macro SCM_CELL_OBJECT_LOC instead, which returns a pointer +to a SCM, as opposed to a pointer to a scm_t_bits. -The previous name was too generic for the global public namespace. +This was done to allow the correct use of pointers into the Scheme +heap. Previously, the heap words were of type scm_t_bits and local +variables and function arguments were of type SCM, making it +non-standards-conformant to have a pointer that can point to both. -** The public #define USE_PTHREAD_THREADS has been renamed to - SCM_USE_PTHREAD_THREADS. +** New macros SCM_SMOB_DATA_2, SCM_SMOB_DATA_3, etc. -The previous name was too generic for the global public namespace. +These macros should be used instead of SCM_CELL_WORD_2/3 to access the +second and third words of double smobs. Likewise for +SCM_SET_SMOB_DATA_2 and SCM_SET_SMOB_DATA_3. -** The public #define USE_NULL_THREADS has been renamed to - SCM_USE_NULL_THREADS. +Also, there is SCM_SMOB_FLAGS and SCM_SET_SMOB_FLAGS that should be +used to get and set the 16 exra bits in the zeroth word of a smob. -The previous name was too generic for the global public namespace. +And finally, there is SCM_SMOB_OBJECT and SCM_SMOB_SET_OBJECT for +accesing the first immediate word of a smob as a SCM value, and there +is SCM_SMOB_OBJECT_LOC for getting a pointer to the first immediate +smob word. Like wise for SCM_SMOB_OBJECT_2, etc. -** The public #define USE_COOP_THREADS has been renamed to - SCM_USE_COOP_THREADS. +** New way to deal with non-local exits and re-entries. -The previous name was too generic for the global public namespace. +There is a new set of functions that essentially do what +scm_internal_dynamic_wind does, but in a way that is more convenient +for C code in some situations. Here is a quick example of how to +prevent a potential memory leak: -** SCM_C_INLINE is publically defined if possible. + void + foo () + { + char *mem; -If the platform has a way to define inline functions, SCM_C_INLINE -will be defined to that text. Otherwise it will be undefined. This -is a little bit different than autoconf's normal handling of the -inline define via AC_C_INLINE. + scm_frame_begin (0); -** Guile now publically defines some basic type infrastructure. + mem = scm_malloc (100); + scm_frame_unwind_handler (free, mem, SCM_F_WIND_EXPLICITELY); -Guile always defines + /* MEM would leak if BAR throws an error. + SCM_FRAME_UNWIND_HANDLER frees it nevertheless. + */ - SCM_SIZEOF_CHAR - SCM_SIZEOF_UNSIGNED_CHAR - SCM_SIZEOF_SHORT - SCM_SIZEOF_UNSIGNED_SHORT - SCM_SIZEOF_LONG - SCM_SIZEOF_UNSIGNED_LONG - SCM_SIZEOF_INT - SCM_SIZEOF_UNSIGNED_INT - SCM_SIZEOF_LONG_LONG /* defined to 0 if type not available */ - SCM_SIZEOF_UNSIGNED_LONG_LONG /* defined to 0 if type not available */ + bar (); + + scm_frame_end (); - scm_t_int8 - scm_t_uint8 - scm_t_int16 - scm_t_uint16 - scm_t_int32 - scm_t_uint32 + /* Because of SCM_F_WIND_EXPLICITELY, MEM will be freed by + SCM_FRAME_END as well. + */ + } -Guile always defines these to 0 or 1 +For full documentation, see the node "Frames" in the manual. - SCM_HAVE_T_INT64 - SCM_HAVE_T_UINT64 +** New function scm_frame_free -and when either of these are defined to 1, also defines +This function calls 'free' on a given pointer when a frame is left. +Thus the call to scm_frame_unwind_handler above could be replaced with +simply scm_frame_free (mem). - scm_t_int64 - scm_t_uint64 +** New way to block and unblock asyncs -respectively. +In addition to scm_c_call_with_blocked_asyncs you can now also use +scm_frame_block_asyncs in a 'frame' (see above). Likewise for +scm_c_call_with_unblocked_asyncs and scm_frame_unblock_asyncs. -Guile always defines +** New way to temporarily set the current input, output or error ports - scm_t_timespec +C code can now use scm_frame_current__port in a 'frame' (see +above). is one of "input", "output" or "error". -** The function scm_unmemocopy now expects a sequence of body forms +** New way to temporarily set fluids -Formerly, scm_unmemocopy would have accepted both, a single expression and a -sequence of body forms for unmemoization. Now, it only accepts only a -sequence of body forms, which was the normal way of using it. Passing it a -single expression won't work any more. +C code can now use scm_frame_fluid in a 'frame' (see +above) to temporarily set the value of a fluid. -** The macro SCM_IFLAGP now only returns true for flags +** New types scm_t_intmax and scm_t_uintmax. -User code should never have used this macro anyway. And, you should not use -it in the future either. Thus, the following explanation is just for the -impropable case that your code actually made use of this macro, and that you -are willing to depend on internals which will probably change in the near -future. +On platforms that have them, these types are identical to intmax_t and +uintmax_t, respectively. On other platforms, they are identical to +the largest integer types that Guile knows about. -Formerly, SCM_IFLAGP also returned true for evaluator bytecodes created with -SCM_MAKSPCSYM (short instructions) and evaluator bytecodes created with -SCM_MAKISYM (short instructions). Now, SCM_IFLAG only returns true for -Guile's special constants created with SCM_MAKIFLAG. To achieve the old -behaviour, instead of +** The functions scm_unmemocopy and scm_unmemoize have been removed. - SCM_IFLAGP(x) +You should not have used them. -you would have to write +** Many public #defines with generic names have been made private. - (SCM_ISYMP(x) || SCM_IFLAGP(x)) +#defines with generic names like HAVE_FOO or SIZEOF_FOO have been made +private or renamed with a more suitable public name. ** The macro SCM_TYP16S has been deprecated. -This macro is not intended for public use. However, if you allocated types -with tc16 type codes in a way that you would have needed this macro, you are -expected to have a deep knowledge of Guile's type system. Thus, you should -know how to replace this macro. +This macro is not intended for public use. ** The macro SCM_SLOPPY_INEXACTP has been deprecated. -Use SCM_INEXACTP instead. +Use scm_is_true (scm_inexact_p (...)) instead. ** The macro SCM_SLOPPY_REALP has been deprecated. -Use SCM_REALP instead. +Use scm_is_real instead. ** The macro SCM_SLOPPY_COMPLEXP has been deprecated. -Use SCM_COMPLEXP instead. +Use scm_is_complex instead. -** The preprocessor define USE_THREADS has been deprecated. +** Some preprocessor defines have been deprecated. -Going forward, assume that the thread API is always present. +These defines indicated whether a certain feature was present in Guile +or not. Going forward, assume that the features are always present. -** The preprocessor define GUILE_ISELECT has been deprecated. +The macros are: USE_THREADS, GUILE_ISELECT, READER_EXTENSIONS, +DEBUG_EXTENSIONS, DYNAMIC_LINKING. -Going forward, assume that scm_internal_select is always present. - -** The preprocessor define READER_EXTENSIONS has been deprecated. - -Going forward, assume that the features represented by -READER_EXTENSIONS are always present. - -** The preprocessor define DEBUG_EXTENSIONS has been deprecated. - -Going forward, assume that the features represented by -DEBUG_EXTENSIONS are always present. - -** The preprocessor define DYNAMIC_LINKING has been deprecated. - -Going forward, assume that the features represented by -DYNAMIC_LINKING are always present. +The following macros have been removed completely: MEMOIZE_LOCALS, +SCM_RECKLESS, SCM_CAUTIOUS. ** The preprocessor define STACK_DIRECTION has been deprecated. There should be no need to know about the stack direction for ordinary -programs. (Do not use.) +programs. ** New function: scm_effective_version @@ -951,7 +1082,7 @@ GUILE_INIT_SEGMENT_SIZE_1, and GUILE_MIN_YIELD_2 should be used. The name scm_definedp is deprecated. -** The struct scm_cell has been renamed to scm_t_cell +** The struct scm_cell type has been renamed to scm_t_cell This is in accordance to Guile's naming scheme for types. Note that the name scm_cell is now used for a function that allocates and @@ -977,11 +1108,6 @@ The old functions for memory management have been deprecated. They are: scm_must_malloc, scm_must_realloc, scm_must_free, scm_must_strdup, scm_must_strndup, scm_done_malloc, scm_done_free. -** New function: scm_str2string - -This function creates a scheme string from a 0-terminated C string. The input -string is copied. - ** Declarations of exported features are marked with SCM_API. Every declaration of a feature that belongs to the exported Guile API @@ -994,15 +1120,16 @@ If you `#define SCM_IMPORT' before including , SCM_API will expand into "__declspec (dllimport) extern", which is needed for linking to the Guile DLL in Windows. -There are also SCM_RL_IMPORT, QT_IMPORT, SCM_SRFI1314_IMPORT, and +There are also SCM_RL_IMPORT, SCM_SRFI1314_IMPORT, and SCM_SRFI4_IMPORT, for the corresponding libraries. ** SCM_NEWCELL and SCM_NEWCELL2 have been deprecated. -Use the new functions scm_cell and scm_double_cell instead. The old macros -had problems because with them allocation and initialization was separated and -the GC could sometimes observe half initialized cells. Only careful coding by -the user of SCM_NEWCELL and SCM_NEWCELL2 could make this safe and efficient. +Use the new functions scm_cell and scm_double_cell instead. The old +macros had problems because with them allocation and initialization +was separated and the GC could sometimes observe half initialized +cells. Only careful coding by the user of SCM_NEWCELL and +SCM_NEWCELL2 could make this safe and efficient. ** CHECK_ENTRY, CHECK_APPLY and CHECK_EXIT have been deprecated. @@ -1015,105 +1142,35 @@ Use scm_c_source_property_breakpoint_p instead. ** Deprecated: scm_makmacro -Change your code to use either scm_makmmacro or, probably better, to use r5rs -macros. Also, be aware that macro expansion will not be done during -evaluation, but prior to evaluation. - -** Removed from scm_root_state: def_inp, def_outp, def_errp, together -with corresponding macros scm_def_inp, scm_def_outp and scm_def_errp. -These were undocumented and unused copies of the standard ports at the -time that Guile was initialised. Normally the current ports should be -used instead, obtained from scm_current_input_port () etc. If an -application needs to retain earlier ports, it should save them in a -gc-protected location. - -** Removed compile time option MEMOIZE_LOCALS - -Now, caching of local variable positions during memoization is mandatory. -However, the option to disable the caching has most probably not been used -anyway. - -** Removed compile time option SCM_RECKLESS - -Full number of arguments checking of closures is mandatory now. However, the -option to disable the checking has most probably not been used anyway. - -** Removed compile time option SCM_CAUTIOUS - -Full number of arguments checking of closures is mandatory now. However, the -option to disable the checking has most probably not been used anyway. - -** Deprecated configure flags USE_THREADS and GUILE_ISELECT - -Previously, when the C preprocessor macro USE_THREADS was defined, -libguile included a thread API. This API is now always included, even -when threads are not really supported. Thus, you don't need to test -for USE_THREADS. - -Analogously, GUILE_ISELECT was defined when the function -scm_internal_select was provided by Guile. This function is now -always defined, and GUILE_ISELECT with it. +Change your code to use either scm_makmmacro or to define macros in +Scheme, using 'define-macro'. ** New function scm_c_port_for_each. This function is like scm_port_for_each but takes a pointer to a C function as the callback instead of a SCM value. -** Deprecated definitions of error strings: scm_s_expression, scm_s_test, -scm_s_body, scm_s_bindings, scm_s_variable, scm_s_clauses, scm_s_formals - -These error message strings were used to issue syntax error messages by -guile's evaluator. It's unlikely that they have been used by user code. - -** Deprecated helper macros for evaluation and application: SCM_EVALIM2, -SCM_EVALIM, SCM_XEVAL, SCM_XEVALCAR - -These macros were used in the implementation of the evaluator. It's unlikely -that they have been used by user code. - -** Deprecated helper functions for evaluation and application: -scm_m_expand_body, scm_macroexp - -These functions were used in the implementation of the evaluator. It's -unlikely that they have been used by user code. - -** Deprecated functions and variables for evaluation and application: -scm_ceval, scm_deval and scm_ceval_ptr - -These functions and variables were used in the implementation of the -evaluator. It's unlikely that they have been used by user code. If you have -used these functions, switch to scm_eval or scm_eval_x. - -** Deprecated functions for unmemoization: scm_unmemocar - -** Deprecated definitions for iloc and isym handling - -SCM_ILOC00, SCM_IDINC, SCM_IDSTMSK, SCM_IFRINC, SCM_ICDR, SCM_IFRAME, -SCM_IDIST, SCM_ICDRP, SCM_ISYMNUM, SCM_ISYMCHARS, scm_isymnames. - -These definitions were used in the implementation of the evaluator. It's -unlikely that they have been used by user code. - -** Removed definitions: scm_lisp_nil, scm_lisp_t, s_nil_ify, -scm_m_nil_ify, s_t_ify, scm_m_t_ify, s_0_cond, scm_m_0_cond, s_0_ify, -scm_m_0_ify, s_1_ify, scm_m_1_ify, scm_debug_newcell, -scm_debug_newcell2, scm_tc16_allocated, SCM_SET_SYMBOL_HASH, -SCM_IM_NIL_IFY, SCM_IM_T_IFY, SCM_IM_0_COND, SCM_IM_0_IFY, -SCM_IM_1_IFY, SCM_GC_SET_ALLOCATED, scm_debug_newcell, -scm_debug_newcell2, SCM_HUP_SIGNAL, SCM_INT_SIGNAL, SCM_FPE_SIGNAL, -SCM_BUS_SIGNAL, SCM_SEGV_SIGNAL, SCM_ALRM_SIGNAL, SCM_GC_SIGNAL, -SCM_TICK_SIGNAL, SCM_SIG_ORD, SCM_ORD_SIG, SCM_NUM_SIGS, -scm_top_level_lookup_closure_var, *top-level-lookup-closure*, -scm_system_transformer, scm_eval_3, scm_eval2, -root_module_lookup_closure, SCM_SLOPPY_STRINGP, SCM_RWSTRINGP, -scm_read_only_string_p, scm_make_shared_substring, scm_tc7_substring, -sym_huh, SCM_VARVCELL, SCM_UDVARIABLEP, SCM_DEFVARIABLEP, scm_mkbig, -scm_big2inum, scm_adjbig, scm_normbig, scm_copybig, scm_2ulong2big, -scm_dbl2big, scm_big2dbl, SCM_FIXNUM_BIT, SCM_SETCHARS, -SCM_SLOPPY_SUBSTRP, SCM_SUBSTR_STR, SCM_SUBSTR_OFFSET, SCM_LENGTH_MAX, -SCM_SETLENGTH, SCM_ROSTRINGP, SCM_ROLENGTH, SCM_ROCHARS, SCM_ROUCHARS, -SCM_SUBSTRP, SCM_COERCE_SUBSTR, scm_sym2vcell, scm_intern, -scm_intern0, scm_sysintern, scm_sysintern0, +** Many definitions have been removed that were previously deprecated. + +scm_lisp_nil, scm_lisp_t, s_nil_ify, scm_m_nil_ify, s_t_ify, +scm_m_t_ify, s_0_cond, scm_m_0_cond, s_0_ify, scm_m_0_ify, s_1_ify, +scm_m_1_ify, scm_debug_newcell, scm_debug_newcell2, +scm_tc16_allocated, SCM_SET_SYMBOL_HASH, SCM_IM_NIL_IFY, SCM_IM_T_IFY, +SCM_IM_0_COND, SCM_IM_0_IFY, SCM_IM_1_IFY, SCM_GC_SET_ALLOCATED, +scm_debug_newcell, scm_debug_newcell2, SCM_HUP_SIGNAL, SCM_INT_SIGNAL, +SCM_FPE_SIGNAL, SCM_BUS_SIGNAL, SCM_SEGV_SIGNAL, SCM_ALRM_SIGNAL, +SCM_GC_SIGNAL, SCM_TICK_SIGNAL, SCM_SIG_ORD, SCM_ORD_SIG, +SCM_NUM_SIGS, scm_top_level_lookup_closure_var, +*top-level-lookup-closure*, scm_system_transformer, scm_eval_3, +scm_eval2, root_module_lookup_closure, SCM_SLOPPY_STRINGP, +SCM_RWSTRINGP, scm_read_only_string_p, scm_make_shared_substring, +scm_tc7_substring, sym_huh, SCM_VARVCELL, SCM_UDVARIABLEP, +SCM_DEFVARIABLEP, scm_mkbig, scm_big2inum, scm_adjbig, scm_normbig, +scm_copybig, scm_2ulong2big, scm_dbl2big, scm_big2dbl, SCM_FIXNUM_BIT, +SCM_SETCHARS, SCM_SLOPPY_SUBSTRP, SCM_SUBSTR_STR, SCM_SUBSTR_OFFSET, +SCM_LENGTH_MAX, SCM_SETLENGTH, SCM_ROSTRINGP, SCM_ROLENGTH, +SCM_ROCHARS, SCM_ROUCHARS, SCM_SUBSTRP, SCM_COERCE_SUBSTR, +scm_sym2vcell, scm_intern, scm_intern0, scm_sysintern, scm_sysintern0, scm_sysintern0_no_module_lookup, scm_init_symbols_deprecated, scm_vector_set_length_x, scm_contregs, scm_debug_info, scm_debug_frame, SCM_DSIDEVAL, SCM_CONST_LONG, SCM_VCELL, @@ -1124,17 +1181,8 @@ SCM_VALIDATE_RWSTRING, DIGITS, scm_small_istr2int, scm_istr2int, scm_istr2flo, scm_istring2number, scm_istr2int, scm_istr2flo, scm_istring2number, scm_vtable_index_vcell, scm_si_vcell, SCM_ECONSP, SCM_NECONSP, SCM_GLOC_VAR, SCM_GLOC_VAL, SCM_GLOC_SET_VAL, -SCM_GLOC_VAL_LOC, scm_make_gloc, scm_gloc_p, scm_tc16_variable - -** Deprecated definitions for debugging: scm_debug_mode, SCM_DEBUGGINGP - -These functions were used in the implementation of the evaluator. It's -unlikely that they have been used by user code. - -** Removed macro SCM_MAKSPCSYM - -This macro was used for defining byte codes of the evaluator. It is almost -impossible that user code has used this macro. +SCM_GLOC_VAL_LOC, scm_make_gloc, scm_gloc_p, scm_tc16_variable, +SCM_CHARS, SCM_LENGTH, SCM_SET_STRING_CHARS, SCM_SET_STRING_LENGTH. Changes since Guile 1.4: