*** empty log message ***
[bpt/guile.git] / NEWS
1 Guile NEWS --- history of user-visible changes. -*- text -*-
2 Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
3 See the end for copying conditions.
4
5 Please send Guile bug reports to bug-guile@gnu.org.
6 \f
7 Changes since the stable branch:
8
9 ** Variables have no longer a special behavior for `equal?'.
10
11 Previously, comparing two variables with `equal?' would recursivly
12 compare their values. This is no longer done. Variables are now only
13 `equal?' if they are `eq?'.
14
15 Changes since Guile 1.4:
16
17 * Changes to the distribution
18
19 ** A top-level TODO file is included.
20
21 ** Guile now uses a versioning scheme similar to that of the Linux kernel.
22
23 Guile now always uses three numbers to represent the version,
24 i.e. "1.6.5". The first number, 1, is the major version number, the
25 second number, 6, is the minor version number, and the third number,
26 5, is the micro version number. Changes in major version number
27 indicate major changes in Guile.
28
29 Minor version numbers that are even denote stable releases, and odd
30 minor version numbers denote development versions (which may be
31 unstable). The micro version number indicates a minor sub-revision of
32 a given MAJOR.MINOR release.
33
34 In keeping with the new scheme, (minor-version) and scm_minor_version
35 no longer return everything but the major version number. They now
36 just return the minor version number. Two new functions
37 (micro-version) and scm_micro_version have been added to report the
38 micro version number.
39
40 In addition, ./GUILE-VERSION now defines GUILE_MICRO_VERSION.
41
42 ** Guile now actively warns about deprecated features.
43
44 The new configure option `--enable-deprecated=LEVEL' and the
45 environment variable GUILE_WARN_DEPRECATED control this mechanism.
46 See INSTALL and README for more information.
47
48 ** New functions: setitimer and getitimer.
49
50 These implement a fairly direct interface to the libc functions of the
51 same name.
52
53 ** The #. reader extension is now disabled by default.
54
55 For safety reasons, #. evaluation is disabled by default. To
56 re-enable it, set the fluid read-eval? to #t. For example:
57
58 (fluid-set! read-eval? #t)
59
60 but make sure you realize the potential security risks involved. With
61 read-eval? enabled, reading a data file from an untrusted source can
62 be dangerous.
63
64 ** New SRFI modules have been added:
65
66 SRFI-0 `cond-expand' is now supported in Guile, without requiring
67 using a module.
68
69 (srfi srfi-1) is a library containing many useful pair- and list-processing
70 procedures.
71
72 (srfi srfi-2) exports and-let*.
73
74 (srfi srfi-4) implements homogeneous numeric vector datatypes.
75
76 (srfi srfi-6) is a dummy module for now, since guile already provides
77 all of the srfi-6 procedures by default: open-input-string,
78 open-output-string, get-output-string.
79
80 (srfi srfi-8) exports receive.
81
82 (srfi srfi-9) exports define-record-type.
83
84 (srfi srfi-10) exports define-reader-ctor and implements the reader
85 extension #,().
86
87 (srfi srfi-11) exports let-values and let*-values.
88
89 (srfi srfi-13) implements the SRFI String Library.
90
91 (srfi srfi-14) implements the SRFI Character-Set Library.
92
93 (srfi srfi-17) implements setter and getter-with-setter and redefines
94 some accessor procedures as procedures with getters. (such as car,
95 cdr, vector-ref etc.)
96
97 (srfi srfi-19) implements the SRFI Time/Date Library.
98
99 ** New scripts / "executable modules"
100
101 Subdirectory "scripts" contains Scheme modules that are packaged to
102 also be executable as scripts. At this time, these scripts are available:
103
104 display-commentary
105 doc-snarf
106 generate-autoload
107 punify
108 read-scheme-source
109 use2dot
110
111 See README there for more info.
112
113 These scripts can be invoked from the shell with the new program
114 "guile-tools", which keeps track of installation directory for you.
115 For example:
116
117 $ guile-tools display-commentary srfi/*.scm
118
119 guile-tools is copied to the standard $bindir on "make install".
120
121 ** New module (ice-9 stack-catch):
122
123 stack-catch is like catch, but saves the current state of the stack in
124 the fluid the-last-stack. This fluid can be useful when using the
125 debugger and when re-throwing an error.
126
127 ** The module (ice-9 and-let*) has been renamed to (ice-9 and-let-star)
128
129 This has been done to prevent problems on lesser operating systems
130 that can't tolerate `*'s in file names. The exported macro continues
131 to be named `and-let*', of course.
132
133 On systems that support it, there is also a compatibility module named
134 (ice-9 and-let*). It will go away in the next release.
135
136 ** New modules (oop goops) etc.:
137
138 (oop goops)
139 (oop goops describe)
140 (oop goops save)
141 (oop goops active-slot)
142 (oop goops composite-slot)
143
144 The Guile Object Oriented Programming System (GOOPS) has been
145 integrated into Guile. For further information, consult the GOOPS
146 manual and tutorial in the `doc' directory.
147
148 ** New module (ice-9 rdelim).
149
150 This exports the following procedures which were previously defined
151 in the default environment:
152
153 read-line read-line! read-delimited read-delimited! %read-delimited!
154 %read-line write-line
155
156 For backwards compatibility the definitions are still imported into the
157 default environment in this version of Guile. However you should add:
158
159 (use-modules (ice-9 rdelim))
160
161 to any program which uses the definitions, since this may change in
162 future.
163
164 Alternatively, if guile-scsh is installed, the (scsh rdelim) module
165 can be used for similar functionality.
166
167 ** New module (ice-9 rw)
168
169 This is a subset of the (scsh rw) module from guile-scsh. Currently
170 it defines two procedures:
171
172 *** New function: read-string!/partial str [port_or_fdes [start [end]]]
173
174 Read characters from a port or file descriptor into a string STR.
175 A port must have an underlying file descriptor -- a so-called
176 fport. This procedure is scsh-compatible and can efficiently read
177 large strings.
178
179 *** New function: write-string/partial str [port_or_fdes [start [end]]]
180
181 Write characters from a string STR to a port or file descriptor.
182 A port must have an underlying file descriptor -- a so-called
183 fport. This procedure is mostly compatible and can efficiently
184 write large strings.
185
186 ** New module (ice-9 match)
187
188 This module includes Andrew K. Wright's pattern matcher. See
189 ice-9/match.scm for brief description or
190
191 http://www.star-lab.com/wright/code.html
192
193 for complete documentation.
194
195 ** New module (ice-9 buffered-input)
196
197 This module provides procedures to construct an input port from an
198 underlying source of input that reads and returns its input in chunks.
199 The underlying input source is a Scheme procedure, specified by the
200 caller, which the port invokes whenever it needs more input.
201
202 This is useful when building an input port whose back end is Readline
203 or a UI element such as the GtkEntry widget.
204
205 ** Documentation
206
207 The reference and tutorial documentation that was previously
208 distributed separately, as `guile-doc', is now included in the core
209 Guile distribution. The documentation consists of the following
210 manuals.
211
212 - The Guile Tutorial (guile-tut.texi) contains a tutorial introduction
213 to using Guile.
214
215 - The Guile Reference Manual (guile.texi) contains (or is intended to
216 contain) reference documentation on all aspects of Guile.
217
218 - The GOOPS Manual (goops.texi) contains both tutorial-style and
219 reference documentation for using GOOPS, Guile's Object Oriented
220 Programming System.
221
222 - The Revised^5 Report on the Algorithmic Language Scheme
223 (r5rs.texi).
224
225 See the README file in the `doc' directory for more details.
226
227 ** There are a couple of examples in the examples/ directory now.
228
229 * Changes to the stand-alone interpreter
230
231 ** New command line option `--use-srfi'
232
233 Using this option, SRFI modules can be loaded on startup and be
234 available right from the beginning. This makes programming portable
235 Scheme programs easier.
236
237 The option `--use-srfi' expects a comma-separated list of numbers,
238 each representing a SRFI number to be loaded into the interpreter
239 before starting evaluating a script file or the REPL. Additionally,
240 the feature identifier for the loaded SRFIs is recognized by
241 `cond-expand' when using this option.
242
243 Example:
244 $ guile --use-srfi=8,13
245 guile> (receive (x z) (values 1 2) (+ 1 2))
246 3
247 guile> (string-pad "bla" 20)
248 " bla"
249
250 ** Guile now always starts up in the `(guile-user)' module.
251
252 Previously, scripts executed via the `-s' option would run in the
253 `(guile)' module and the repl would run in the `(guile-user)' module.
254 Now every user action takes place in the `(guile-user)' module by
255 default.
256
257 * Changes to Scheme functions and syntax
258
259 ** Previously deprecated Scheme functions have been removed:
260
261 tag - no replacement.
262 fseek - replaced by seek.
263 list* - replaced by cons*.
264
265 ** It's now possible to create modules with controlled environments
266
267 Example:
268
269 (use-modules (ice-9 safe))
270 (define m (make-safe-module))
271 ;;; m will now be a module containing only a safe subset of R5RS
272 (eval '(+ 1 2) m) --> 3
273 (eval 'load m) --> ERROR: Unbound variable: load
274
275 ** Evaluation of "()", the empty list, is now an error.
276
277 Previously, the expression "()" evaluated to the empty list. This has
278 been changed to signal a "missing expression" error. The correct way
279 to write the empty list as a literal constant is to use quote: "'()".
280
281 ** New concept of `Guile Extensions'.
282
283 A Guile Extension is just a ordinary shared library that can be linked
284 at run-time. We found it advantageous to give this simple concept a
285 dedicated name to distinguish the issues related to shared libraries
286 from the issues related to the module system.
287
288 *** New function: load-extension
289
290 Executing (load-extension lib init) is mostly equivalent to
291
292 (dynamic-call init (dynamic-link lib))
293
294 except when scm_register_extension has been called previously.
295 Whenever appropriate, you should use `load-extension' instead of
296 dynamic-link and dynamic-call.
297
298 *** New C function: scm_c_register_extension
299
300 This function registers a initialization function for use by
301 `load-extension'. Use it when you don't want specific extensions to
302 be loaded as shared libraries (for example on platforms that don't
303 support dynamic linking).
304
305 ** Auto-loading of compiled-code modules is deprecated.
306
307 Guile used to be able to automatically find and link a shared
308 library to satisfy requests for a module. For example, the module
309 `(foo bar)' could be implemented by placing a shared library named
310 "foo/libbar.so" (or with a different extension) in a directory on the
311 load path of Guile.
312
313 This has been found to be too tricky, and is no longer supported. The
314 shared libraries are now called "extensions". You should now write a
315 small Scheme file that calls `load-extension' to load the shared
316 library and initialize it explicitely.
317
318 The shared libraries themselves should be installed in the usual
319 places for shared libraries, with names like "libguile-foo-bar".
320
321 For example, place this into a file "foo/bar.scm"
322
323 (define-module (foo bar))
324
325 (load-extension "libguile-foo-bar" "foobar_init")
326
327 ** Backward incompatible change: eval EXP ENVIRONMENT-SPECIFIER
328
329 `eval' is now R5RS, that is it takes two arguments.
330 The second argument is an environment specifier, i.e. either
331
332 (scheme-report-environment 5)
333 (null-environment 5)
334 (interaction-environment)
335
336 or
337
338 any module.
339
340 ** The module system has been made more disciplined.
341
342 The function `eval' will save and restore the current module around
343 the evaluation of the specified expression. While this expression is
344 evaluated, `(current-module)' will now return the right module, which
345 is the module specified as the second argument to `eval'.
346
347 A consequence of this change is that `eval' is not particularly
348 useful when you want allow the evaluated code to change what module is
349 designated as the current module and have this change persist from one
350 call to `eval' to the next. The read-eval-print-loop is an example
351 where `eval' is now inadequate. To compensate, there is a new
352 function `primitive-eval' that does not take a module specifier and
353 that does not save/restore the current module. You should use this
354 function together with `set-current-module', `current-module', etc
355 when you want to have more control over the state that is carried from
356 one eval to the next.
357
358 Additionally, it has been made sure that forms that are evaluated at
359 the top level are always evaluated with respect to the current module.
360 Previously, subforms of top-level forms such as `begin', `case',
361 etc. did not respect changes to the current module although these
362 subforms are at the top-level as well.
363
364 To prevent strange behavior, the forms `define-module',
365 `use-modules', `use-syntax', and `export' have been restricted to only
366 work on the top level. The forms `define-public' and
367 `defmacro-public' only export the new binding on the top level. They
368 behave just like `define' and `defmacro', respectively, when they are
369 used in a lexical environment.
370
371 Also, `export' will no longer silently re-export bindings imported
372 from a used module. It will emit a `deprecation' warning and will
373 cease to perform any re-export in the next version. If you actually
374 want to re-export bindings, use the new `re-export' in place of
375 `export'. The new `re-export' will not make copies of variables when
376 rexporting them, as `export' did wrongly.
377
378 ** The semantics of guardians have changed.
379
380 The changes are for the most part compatible. An important criterion
381 was to keep the typical usage of guardians as simple as before, but to
382 make the semantics safer and (as a result) more useful.
383
384 *** All objects returned from guardians are now properly alive.
385
386 It is now guaranteed that any object referenced by an object returned
387 from a guardian is alive. It's now impossible for a guardian to
388 return a "contained" object before its "containing" object.
389
390 One incompatible (but probably not very important) change resulting
391 from this is that it is no longer possible to guard objects that
392 indirectly reference themselves (i.e. are parts of cycles). If you do
393 so accidentally, you'll get a warning.
394
395 *** There are now two types of guardians: greedy and sharing.
396
397 If you call (make-guardian #t) or just (make-guardian), you'll get a
398 greedy guardian, and for (make-guardian #f) a sharing guardian.
399
400 Greedy guardians are the default because they are more "defensive".
401 You can only greedily guard an object once. If you guard an object
402 more than once, once in a greedy guardian and the rest of times in
403 sharing guardians, then it is guaranteed that the object won't be
404 returned from sharing guardians as long as it is greedily guarded
405 and/or alive.
406
407 Guardians returned by calls to `make-guardian' can now take one more
408 optional parameter, which says whether to throw an error in case an
409 attempt is made to greedily guard an object that is already greedily
410 guarded. The default is true, i.e. throw an error. If the parameter
411 is false, the guardian invocation returns #t if guarding was
412 successful and #f if it wasn't.
413
414 Also, since greedy guarding is, in effect, a side-effecting operation
415 on objects, a new function is introduced: `destroy-guardian!'.
416 Invoking this function on a guardian renders it unoperative and, if
417 the guardian is greedy, clears the "greedily guarded" property of the
418 objects that were guarded by it, thus undoing the side effect.
419
420 Note that all this hair is hardly very important, since guardian
421 objects are usually permanent.
422
423 ** Continuations created by call-with-current-continuation now accept
424 any number of arguments, as required by R5RS.
425
426 ** New function `issue-deprecation-warning'
427
428 This function is used to display the deprecation messages that are
429 controlled by GUILE_WARN_DEPRECATION as explained in the README.
430
431 (define (id x)
432 (issue-deprecation-warning "`id' is deprecated. Use `identity' instead.")
433 (identity x))
434
435 guile> (id 1)
436 ;; `id' is deprecated. Use `identity' instead.
437 1
438 guile> (id 1)
439 1
440
441 ** New syntax `begin-deprecated'
442
443 When deprecated features are included (as determined by the configure
444 option --enable-deprecated), `begin-deprecated' is identical to
445 `begin'. When deprecated features are excluded, it always evaluates
446 to `#f', ignoring the body forms.
447
448 ** New function `make-object-property'
449
450 This function returns a new `procedure with setter' P that can be used
451 to attach a property to objects. When calling P as
452
453 (set! (P obj) val)
454
455 where `obj' is any kind of object, it attaches `val' to `obj' in such
456 a way that it can be retrieved by calling P as
457
458 (P obj)
459
460 This function will replace procedure properties, symbol properties and
461 source properties eventually.
462
463 ** Module (ice-9 optargs) now uses keywords instead of `#&'.
464
465 Instead of #&optional, #&key, etc you should now use #:optional,
466 #:key, etc. Since #:optional is a keyword, you can write it as just
467 :optional when (read-set! keywords 'prefix) is active.
468
469 The old reader syntax `#&' is still supported, but deprecated. It
470 will be removed in the next release.
471
472 ** New define-module option: pure
473
474 Tells the module system not to include any bindings from the root
475 module.
476
477 Example:
478
479 (define-module (totally-empty-module)
480 :pure)
481
482 ** New define-module option: export NAME1 ...
483
484 Export names NAME1 ...
485
486 This option is required if you want to be able to export bindings from
487 a module which doesn't import one of `define-public' or `export'.
488
489 Example:
490
491 (define-module (foo)
492 :pure
493 :use-module (ice-9 r5rs)
494 :export (bar))
495
496 ;;; Note that we're pure R5RS below this point!
497
498 (define (bar)
499 ...)
500
501 ** New function: object->string OBJ
502
503 Return a Scheme string obtained by printing a given object.
504
505 ** New function: port? X
506
507 Returns a boolean indicating whether X is a port. Equivalent to
508 `(or (input-port? X) (output-port? X))'.
509
510 ** New function: file-port?
511
512 Determines whether a given object is a port that is related to a file.
513
514 ** New function: port-for-each proc
515
516 Apply PROC to each port in the Guile port table in turn. The return
517 value is unspecified. More specifically, PROC is applied exactly once
518 to every port that exists in the system at the time PORT-FOR-EACH is
519 invoked. Changes to the port table while PORT-FOR-EACH is running
520 have no effect as far as PORT-FOR-EACH is concerned.
521
522 ** New function: dup2 oldfd newfd
523
524 A simple wrapper for the `dup2' system call. Copies the file
525 descriptor OLDFD to descriptor number NEWFD, replacing the
526 previous meaning of NEWFD. Both OLDFD and NEWFD must be integers.
527 Unlike for dup->fdes or primitive-move->fdes, no attempt is made
528 to move away ports which are using NEWFD. The return value is
529 unspecified.
530
531 ** New function: close-fdes fd
532
533 A simple wrapper for the `close' system call. Close file
534 descriptor FD, which must be an integer. Unlike close (*note
535 close: Ports and File Descriptors.), the file descriptor will be
536 closed even if a port is using it. The return value is
537 unspecified.
538
539 ** New function: crypt password salt
540
541 Encrypts `password' using the standard unix password encryption
542 algorithm.
543
544 ** New function: chroot path
545
546 Change the root directory of the running process to `path'.
547
548 ** New functions: getlogin, cuserid
549
550 Return the login name or the user name of the current effective user
551 id, respectively.
552
553 ** New functions: getpriority which who, setpriority which who prio
554
555 Get or set the priority of the running process.
556
557 ** New function: getpass prompt
558
559 Read a password from the terminal, first displaying `prompt' and
560 disabling echoing.
561
562 ** New function: flock file operation
563
564 Set/remove an advisory shared or exclusive lock on `file'.
565
566 ** New functions: sethostname name, gethostname
567
568 Set or get the hostname of the machine the current process is running
569 on.
570
571 ** New function: mkstemp! tmpl
572
573 mkstemp creates a new unique file in the file system and returns a
574 new buffered port open for reading and writing to the file. TMPL
575 is a string specifying where the file should be created: it must
576 end with `XXXXXX' and will be changed in place to return the name
577 of the temporary file.
578
579 ** New function: open-input-string string
580
581 Return an input string port which delivers the characters from
582 `string'. This procedure, together with `open-output-string' and
583 `get-output-string' implements SRFI-6.
584
585 ** New function: open-output-string
586
587 Return an output string port which collects all data written to it.
588 The data can then be retrieved by `get-output-string'.
589
590 ** New function: get-output-string
591
592 Return the contents of an output string port.
593
594 ** New function: identity
595
596 Return the argument.
597
598 ** socket, connect, accept etc., now have support for IPv6. IPv6 addresses
599 are represented in Scheme as integers with normal host byte ordering.
600
601 ** New function: inet-pton family address
602
603 Convert a printable string network address into an integer. Note that
604 unlike the C version of this function, the result is an integer with
605 normal host byte ordering. FAMILY can be `AF_INET' or `AF_INET6'.
606 e.g.,
607
608 (inet-pton AF_INET "127.0.0.1") => 2130706433
609 (inet-pton AF_INET6 "::1") => 1
610
611 ** New function: inet-ntop family address
612
613 Convert an integer network address into a printable string. Note that
614 unlike the C version of this function, the input is an integer with
615 normal host byte ordering. FAMILY can be `AF_INET' or `AF_INET6'.
616 e.g.,
617
618 (inet-ntop AF_INET 2130706433) => "127.0.0.1"
619 (inet-ntop AF_INET6 (- (expt 2 128) 1)) =>
620 ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
621
622 ** Deprecated: id
623
624 Use `identity' instead.
625
626 ** Deprecated: -1+
627
628 Use `1-' instead.
629
630 ** Deprecated: return-it
631
632 Do without it.
633
634 ** Deprecated: string-character-length
635
636 Use `string-length' instead.
637
638 ** Deprecated: flags
639
640 Use `logior' instead.
641
642 ** Deprecated: close-all-ports-except.
643
644 This was intended for closing ports in a child process after a fork,
645 but it has the undesirable side effect of flushing buffers.
646 port-for-each is more flexible.
647
648 ** The (ice-9 popen) module now attempts to set up file descriptors in
649 the child process from the current Scheme ports, instead of using the
650 current values of file descriptors 0, 1, and 2 in the parent process.
651
652 ** Removed function: builtin-weak-bindings
653
654 There is no such concept as a weak binding any more.
655
656 ** Removed constants: bignum-radix, scm-line-incrementors
657
658 ** define-method: New syntax mandatory.
659
660 The new method syntax is now mandatory:
661
662 (define-method (NAME ARG-SPEC ...) BODY ...)
663 (define-method (NAME ARG-SPEC ... . REST-ARG) BODY ...)
664
665 ARG-SPEC ::= ARG-NAME | (ARG-NAME TYPE)
666 REST-ARG ::= ARG-NAME
667
668 If you have old code using the old syntax, import
669 (oop goops old-define-method) before (oop goops) as in:
670
671 (use-modules (oop goops old-define-method) (oop goops))
672
673 ** Deprecated function: builtin-variable
674 Removed function: builtin-bindings
675
676 There is no longer a distinction between builtin or other variables.
677 Use module system operations for all variables.
678
679 ** Lazy-catch handlers are no longer allowed to return.
680
681 That is, a call to `throw', `error', etc is now guaranteed to not
682 return.
683
684 ** Bugfix for (ice-9 getopt-long)
685
686 Parsing for options that are specified to have `optional' args now checks if
687 the next element is an option instead of unconditionally taking it as the
688 option arg.
689
690 Also, this module is now tested using test-suite/tests/getopt-long.test.
691
692 * Changes to the C interface
693
694 ** Types have been renamed from scm_*_t to scm_t_*.
695
696 This has been done for POSIX sake. It reserves identifiers ending
697 with "_t". What a concept.
698
699 The old names are still available with status `deprecated'.
700
701 ** scm_t_bits (former scm_bits_t) is now a unsigned type.
702
703 ** Deprecated features have been removed.
704
705 *** Macros removed
706
707 SCM_INPORTP, SCM_OUTPORTP SCM_ICHRP, SCM_ICHR, SCM_MAKICHR
708 SCM_SETJMPBUF SCM_NSTRINGP SCM_NRWSTRINGP SCM_NVECTORP SCM_DOUBLE_CELLP
709
710 *** C Functions removed
711
712 scm_sysmissing scm_tag scm_tc16_flo scm_tc_flo
713 scm_fseek - replaced by scm_seek.
714 gc-thunk - replaced by after-gc-hook.
715 gh_int2scmb - replaced by gh_bool2scm.
716 scm_tc_dblr - replaced by scm_tc16_real.
717 scm_tc_dblc - replaced by scm_tc16_complex.
718 scm_list_star - replaced by scm_cons_star.
719
720 ** Deprecated: scm_makfromstr
721
722 Use scm_mem2string instead.
723
724 ** Deprecated: scm_make_shared_substring
725
726 Explicit shared substrings will disappear from Guile.
727
728 Instead, "normal" strings will be implemented using sharing
729 internally, combined with a copy-on-write strategy.
730
731 ** Deprecated: scm_read_only_string_p
732
733 The concept of read-only strings will disappear in next release of
734 Guile.
735
736 ** Deprecated: scm_sloppy_memq, scm_sloppy_memv, scm_sloppy_member
737
738 Instead, use scm_c_memq or scm_memq, scm_memv, scm_member.
739
740 ** New functions: scm_call_0, scm_call_1, scm_call_2, scm_call_3
741
742 Call a procedure with the indicated number of arguments.
743
744 Example:
745
746 scm_call_1 (proc, arg1);
747
748 ** New functions: scm_apply_0, scm_apply_1, scm_apply_2, scm_apply_3
749
750 Call a procedure with the indicated number of arguments and a list
751 of arguments.
752
753 Example:
754
755 scm_apply_1 (proc, arg1, args);
756
757 ** New functions: scm_list_1, scm_list_2, scm_list_3, scm_list_4, scm_list_5
758
759 Create a list of the given number of elements.
760
761 ** Renamed function: scm_listify has been replaced by scm_list_n.
762
763 ** Deprecated macros: SCM_LIST0, SCM_LIST1, SCM_LIST2, SCM_LIST3, SCM_LIST4,
764 SCM_LIST5, SCM_LIST6, SCM_LIST7, SCM_LIST8, SCM_LIST9.
765
766 Use functions scm_list_N instead.
767
768 ** New function: scm_c_read (SCM port, void *buffer, scm_sizet size)
769
770 Used by an application to read arbitrary number of bytes from a port.
771 Same semantics as libc read, except that scm_c_read only returns less
772 than SIZE bytes if at end-of-file.
773
774 Warning: Doesn't update port line and column counts!
775
776 ** New function: scm_c_write (SCM port, const void *ptr, scm_sizet size)
777
778 Used by an application to write arbitrary number of bytes to an SCM
779 port. Similar semantics as libc write. However, unlike libc
780 write, scm_c_write writes the requested number of bytes and has no
781 return value.
782
783 Warning: Doesn't update port line and column counts!
784
785 ** New function: scm_init_guile ()
786
787 In contrast to scm_boot_guile, scm_init_guile will return normally
788 after initializing Guile. It is not available on all systems, tho.
789
790 ** New functions: scm_str2symbol, scm_mem2symbol
791
792 The function scm_str2symbol takes a const char* pointing to a zero-terminated
793 field of characters and creates a scheme symbol object from that C string.
794 The function scm_mem2symbol takes a const char* and a number of characters and
795 creates a symbol from the characters in that memory area.
796
797 ** New functions: scm_primitive_make_property
798 scm_primitive_property_ref
799 scm_primitive_property_set_x
800 scm_primitive_property_del_x
801
802 These functions implement a new way to deal with object properties.
803 See libguile/properties.c for their documentation.
804
805 ** New function: scm_done_free (long size)
806
807 This function is the inverse of scm_done_malloc. Use it to report the
808 amount of smob memory you free. The previous method, which involved
809 calling scm_done_malloc with negative argument, was somewhat
810 unintuitive (and is still available, of course).
811
812 ** New function: scm_c_memq (SCM obj, SCM list)
813
814 This function provides a fast C level alternative for scm_memq for the case
815 that the list parameter is known to be a proper list. The function is a
816 replacement for scm_sloppy_memq, but is stricter in its requirements on its
817 list input parameter, since for anything else but a proper list the function's
818 behaviour is undefined - it may even crash or loop endlessly. Further, for
819 the case that the object is not found in the list, scm_c_memq returns #f which
820 is similar to scm_memq, but different from scm_sloppy_memq's behaviour.
821
822 ** New functions: scm_remember_upto_here_1, scm_remember_upto_here_2,
823 scm_remember_upto_here
824
825 These functions replace the function scm_remember.
826
827 ** Deprecated function: scm_remember
828
829 Use one of the new functions scm_remember_upto_here_1,
830 scm_remember_upto_here_2 or scm_remember_upto_here instead.
831
832 ** New function: scm_allocate_string
833
834 This function replaces the function scm_makstr.
835
836 ** Deprecated function: scm_makstr
837
838 Use the new function scm_allocate_string instead.
839
840 ** New global variable scm_gc_running_p introduced.
841
842 Use this variable to find out if garbage collection is being executed. Up to
843 now applications have used scm_gc_heap_lock to test if garbage collection was
844 running, which also works because of the fact that up to know only the garbage
845 collector has set this variable. But, this is an implementation detail that
846 may change. Further, scm_gc_heap_lock is not set throughout gc, thus the use
847 of this variable is (and has been) not fully safe anyway.
848
849 ** New macros: SCM_BITVECTOR_MAX_LENGTH, SCM_UVECTOR_MAX_LENGTH
850
851 Use these instead of SCM_LENGTH_MAX.
852
853 ** New macros: SCM_CONTINUATION_LENGTH, SCM_CCLO_LENGTH, SCM_STACK_LENGTH,
854 SCM_STRING_LENGTH, SCM_SYMBOL_LENGTH, SCM_UVECTOR_LENGTH,
855 SCM_BITVECTOR_LENGTH, SCM_VECTOR_LENGTH.
856
857 Use these instead of SCM_LENGTH.
858
859 ** New macros: SCM_SET_CONTINUATION_LENGTH, SCM_SET_STRING_LENGTH,
860 SCM_SET_SYMBOL_LENGTH, SCM_SET_VECTOR_LENGTH, SCM_SET_UVECTOR_LENGTH,
861 SCM_SET_BITVECTOR_LENGTH
862
863 Use these instead of SCM_SETLENGTH
864
865 ** New macros: SCM_STRING_CHARS, SCM_SYMBOL_CHARS, SCM_CCLO_BASE,
866 SCM_VECTOR_BASE, SCM_UVECTOR_BASE, SCM_BITVECTOR_BASE, SCM_COMPLEX_MEM,
867 SCM_ARRAY_MEM
868
869 Use these instead of SCM_CHARS, SCM_UCHARS, SCM_ROCHARS, SCM_ROUCHARS or
870 SCM_VELTS.
871
872 ** New macros: SCM_SET_BIGNUM_BASE, SCM_SET_STRING_CHARS,
873 SCM_SET_SYMBOL_CHARS, SCM_SET_UVECTOR_BASE, SCM_SET_BITVECTOR_BASE,
874 SCM_SET_VECTOR_BASE
875
876 Use these instead of SCM_SETCHARS.
877
878 ** New macro: SCM_BITVECTOR_P
879
880 ** New macro: SCM_STRING_COERCE_0TERMINATION_X
881
882 Use instead of SCM_COERCE_SUBSTR.
883
884 ** New macros: SCM_DIR_OPEN_P, SCM_DIR_FLAG_OPEN
885
886 For directory objects, use these instead of SCM_OPDIRP and SCM_OPN.
887
888 ** Deprecated macros: SCM_OUTOFRANGE, SCM_NALLOC, SCM_HUP_SIGNAL,
889 SCM_INT_SIGNAL, SCM_FPE_SIGNAL, SCM_BUS_SIGNAL, SCM_SEGV_SIGNAL,
890 SCM_ALRM_SIGNAL, SCM_GC_SIGNAL, SCM_TICK_SIGNAL, SCM_SIG_ORD,
891 SCM_ORD_SIG, SCM_NUM_SIGS, SCM_SYMBOL_SLOTS, SCM_SLOTS, SCM_SLOPPY_STRINGP,
892 SCM_VALIDATE_STRINGORSUBSTR, SCM_FREEP, SCM_NFREEP, SCM_CHARS, SCM_UCHARS,
893 SCM_VALIDATE_ROSTRING, SCM_VALIDATE_ROSTRING_COPY,
894 SCM_VALIDATE_NULLORROSTRING_COPY, SCM_ROLENGTH, SCM_LENGTH, SCM_HUGE_LENGTH,
895 SCM_SUBSTRP, SCM_SUBSTR_STR, SCM_SUBSTR_OFFSET, SCM_COERCE_SUBSTR,
896 SCM_ROSTRINGP, SCM_RWSTRINGP, SCM_VALIDATE_RWSTRING, SCM_ROCHARS,
897 SCM_ROUCHARS, SCM_SETLENGTH, SCM_SETCHARS, SCM_LENGTH_MAX, SCM_GC8MARKP,
898 SCM_SETGC8MARK, SCM_CLRGC8MARK, SCM_GCTYP16, SCM_GCCDR, SCM_SUBR_DOC,
899 SCM_OPDIRP, SCM_VALIDATE_OPDIR, SCM_WTA, RETURN_SCM_WTA, SCM_CONST_LONG,
900 SCM_WNA, SCM_FUNC_NAME, SCM_VALIDATE_NUMBER_COPY,
901 SCM_VALIDATE_NUMBER_DEF_COPY, SCM_SLOPPY_CONSP, SCM_SLOPPY_NCONSP,
902 SCM_SETAND_CDR, SCM_SETOR_CDR, SCM_SETAND_CAR, SCM_SETOR_CAR
903
904 Use SCM_ASSERT_RANGE or SCM_VALIDATE_XXX_RANGE instead of SCM_OUTOFRANGE.
905 Use scm_memory_error instead of SCM_NALLOC.
906 Use SCM_STRINGP instead of SCM_SLOPPY_STRINGP.
907 Use SCM_VALIDATE_STRING instead of SCM_VALIDATE_STRINGORSUBSTR.
908 Use SCM_FREE_CELL_P instead of SCM_FREEP/SCM_NFREEP
909 Use a type specific accessor macro instead of SCM_CHARS/SCM_UCHARS.
910 Use a type specific accessor instead of SCM(_|_RO|_HUGE_)LENGTH.
911 Use SCM_VALIDATE_(SYMBOL|STRING) instead of SCM_VALIDATE_ROSTRING.
912 Use SCM_STRING_COERCE_0TERMINATION_X instead of SCM_COERCE_SUBSTR.
913 Use SCM_STRINGP or SCM_SYMBOLP instead of SCM_ROSTRINGP.
914 Use SCM_STRINGP instead of SCM_RWSTRINGP.
915 Use SCM_VALIDATE_STRING instead of SCM_VALIDATE_RWSTRING.
916 Use SCM_STRING_CHARS instead of SCM_ROCHARS.
917 Use SCM_STRING_UCHARS instead of SCM_ROUCHARS.
918 Use a type specific setter macro instead of SCM_SETLENGTH.
919 Use a type specific setter macro instead of SCM_SETCHARS.
920 Use a type specific length macro instead of SCM_LENGTH_MAX.
921 Use SCM_GCMARKP instead of SCM_GC8MARKP.
922 Use SCM_SETGCMARK instead of SCM_SETGC8MARK.
923 Use SCM_CLRGCMARK instead of SCM_CLRGC8MARK.
924 Use SCM_TYP16 instead of SCM_GCTYP16.
925 Use SCM_CDR instead of SCM_GCCDR.
926 Use SCM_DIR_OPEN_P instead of SCM_OPDIRP.
927 Use SCM_MISC_ERROR or SCM_WRONG_TYPE_ARG instead of SCM_WTA.
928 Use SCM_MISC_ERROR or SCM_WRONG_TYPE_ARG instead of RETURN_SCM_WTA.
929 Use SCM_VCELL_INIT instead of SCM_CONST_LONG.
930 Use SCM_WRONG_NUM_ARGS instead of SCM_WNA.
931 Use SCM_CONSP instead of SCM_SLOPPY_CONSP.
932 Use !SCM_CONSP instead of SCM_SLOPPY_NCONSP.
933
934 ** Removed function: scm_struct_init
935
936 ** Removed variable: scm_symhash_dim
937
938 ** Renamed function: scm_make_cont has been replaced by
939 scm_make_continuation, which has a different interface.
940
941 ** Deprecated function: scm_call_catching_errors
942
943 Use scm_catch or scm_lazy_catch from throw.[ch] instead.
944
945 ** Deprecated function: scm_strhash
946
947 Use scm_string_hash instead.
948
949 ** Deprecated function: scm_vector_set_length_x
950
951 Instead, create a fresh vector of the desired size and copy the contents.
952
953 ** scm_gensym has changed prototype
954
955 scm_gensym now only takes one argument.
956
957 ** Deprecated type tags: scm_tc7_ssymbol, scm_tc7_msymbol, scm_tcs_symbols,
958 scm_tc7_lvector
959
960 There is now only a single symbol type scm_tc7_symbol.
961 The tag scm_tc7_lvector was not used anyway.
962
963 ** Deprecated function: scm_make_smob_type_mfpe, scm_set_smob_mfpe.
964
965 Use scm_make_smob_type and scm_set_smob_XXX instead.
966
967 ** New function scm_set_smob_apply.
968
969 This can be used to set an apply function to a smob type.
970
971 ** Deprecated function: scm_strprint_obj
972
973 Use scm_object_to_string instead.
974
975 ** Deprecated function: scm_wta
976
977 Use scm_wrong_type_arg, or another appropriate error signalling function
978 instead.
979
980 ** Explicit support for obarrays has been deprecated.
981
982 Use `scm_str2symbol' and the generic hashtable functions instead.
983
984 ** The concept of `vcells' has been deprecated.
985
986 The data type `variable' is now used exclusively. `Vcells' have been
987 a low-level concept so you are likely not affected by this change.
988
989 *** Deprecated functions: scm_sym2vcell, scm_sysintern,
990 scm_sysintern0, scm_symbol_value0, scm_intern, scm_intern0.
991
992 Use scm_c_define or scm_c_lookup instead, as appropriate.
993
994 *** New functions: scm_c_module_lookup, scm_c_lookup,
995 scm_c_module_define, scm_c_define, scm_module_lookup, scm_lookup,
996 scm_module_define, scm_define.
997
998 These functions work with variables instead of with vcells.
999
1000 ** New functions for creating and defining `subr's and `gsubr's.
1001
1002 The new functions more clearly distinguish between creating a subr (or
1003 gsubr) object and adding it to the current module.
1004
1005 These new functions are available: scm_c_make_subr, scm_c_define_subr,
1006 scm_c_make_subr_with_generic, scm_c_define_subr_with_generic,
1007 scm_c_make_gsubr, scm_c_define_gsubr, scm_c_make_gsubr_with_generic,
1008 scm_c_define_gsubr_with_generic.
1009
1010 ** Deprecated functions: scm_make_subr, scm_make_subr_opt,
1011 scm_make_subr_with_generic, scm_make_gsubr,
1012 scm_make_gsubr_with_generic.
1013
1014 Use the new ones from above instead.
1015
1016 ** C interface to the module system has changed.
1017
1018 While we suggest that you avoid as many explicit module system
1019 operations from C as possible for the time being, the C interface has
1020 been made more similar to the high-level Scheme module system.
1021
1022 *** New functions: scm_c_define_module, scm_c_use_module,
1023 scm_c_export, scm_c_resolve_module.
1024
1025 They mostly work like their Scheme namesakes. scm_c_define_module
1026 takes a function that is called a context where the new module is
1027 current.
1028
1029 *** Deprecated functions: scm_the_root_module, scm_make_module,
1030 scm_ensure_user_module, scm_load_scheme_module.
1031
1032 Use the new functions instead.
1033
1034 ** Renamed function: scm_internal_with_fluids becomes
1035 scm_c_with_fluids.
1036
1037 scm_internal_with_fluids is available as a deprecated function.
1038
1039 ** New function: scm_c_with_fluid.
1040
1041 Just like scm_c_with_fluids, but takes one fluid and one value instead
1042 of lists of same.
1043
1044 ** Deprecated typedefs: long_long, ulong_long.
1045
1046 They are of questionable utility and they pollute the global
1047 namespace.
1048
1049 ** Deprecated typedef: scm_sizet
1050
1051 It is of questionable utility now that Guile requires ANSI C, and is
1052 oddly named.
1053
1054 ** Deprecated typedefs: scm_port_rw_active, scm_port,
1055 scm_ptob_descriptor, scm_debug_info, scm_debug_frame, scm_fport,
1056 scm_option, scm_rstate, scm_rng, scm_array, scm_array_dim.
1057
1058 Made more compliant with the naming policy by adding a _t at the end.
1059
1060 ** Deprecated functions: scm_mkbig, scm_big2num, scm_adjbig,
1061 scm_normbig, scm_copybig, scm_2ulong2big, scm_dbl2big, scm_big2dbl
1062
1063 With the exception of the mysterious scm_2ulong2big, they are still
1064 available under new names (scm_i_mkbig etc). These functions are not
1065 intended to be used in user code. You should avoid dealing with
1066 bignums directly, and should deal with numbers in general (which can
1067 be bignums).
1068
1069 ** New functions: scm_short2num, scm_ushort2num, scm_int2num,
1070 scm_uint2num, scm_size2num, scm_ptrdiff2num, scm_num2short,
1071 scm_num2ushort, scm_num2int, scm_num2uint, scm_num2ptrdiff,
1072 scm_num2size.
1073
1074 These are conversion functions between the various ANSI C integral
1075 types and Scheme numbers.
1076
1077 ** New number validation macros:
1078 SCM_NUM2{SIZE,PTRDIFF,SHORT,USHORT,INT,UINT}[_DEF]
1079
1080 See above.
1081
1082 ** New functions: scm_gc_protect_object, scm_gc_unprotect_object
1083
1084 These are just nicer-named old scm_protect_object and
1085 scm_unprotect_object.
1086
1087 ** Deprecated functions: scm_protect_object, scm_unprotect_object
1088
1089 ** New functions: scm_gc_[un]register_root, scm_gc_[un]register_roots
1090
1091 These functions can be used to register pointers to locations that
1092 hold SCM values.
1093
1094 ** Deprecated function: scm_create_hook.
1095
1096 Its sins are: misleading name, non-modularity and lack of general
1097 usefulness.
1098
1099 \f
1100 Changes since Guile 1.3.4:
1101
1102 * Changes to the distribution
1103
1104 ** Trees from nightly snapshots and CVS now require you to run autogen.sh.
1105
1106 We've changed the way we handle generated files in the Guile source
1107 repository. As a result, the procedure for building trees obtained
1108 from the nightly FTP snapshots or via CVS has changed:
1109 - You must have appropriate versions of autoconf, automake, and
1110 libtool installed on your system. See README for info on how to
1111 obtain these programs.
1112 - Before configuring the tree, you must first run the script
1113 `autogen.sh' at the top of the source tree.
1114
1115 The Guile repository used to contain not only source files, written by
1116 humans, but also some generated files, like configure scripts and
1117 Makefile.in files. Even though the contents of these files could be
1118 derived mechanically from other files present, we thought it would
1119 make the tree easier to build if we checked them into CVS.
1120
1121 However, this approach means that minor differences between
1122 developer's installed tools and habits affected the whole team.
1123 So we have removed the generated files from the repository, and
1124 added the autogen.sh script, which will reconstruct them
1125 appropriately.
1126
1127
1128 ** configure now has experimental options to remove support for certain
1129 features:
1130
1131 --disable-arrays omit array and uniform array support
1132 --disable-posix omit posix interfaces
1133 --disable-networking omit networking interfaces
1134 --disable-regex omit regular expression interfaces
1135
1136 These are likely to become separate modules some day.
1137
1138 ** New configure option --enable-debug-freelist
1139
1140 This enables a debugging version of SCM_NEWCELL(), and also registers
1141 an extra primitive, the setter `gc-set-debug-check-freelist!'.
1142
1143 Configure with the --enable-debug-freelist option to enable
1144 the gc-set-debug-check-freelist! primitive, and then use:
1145
1146 (gc-set-debug-check-freelist! #t) # turn on checking of the freelist
1147 (gc-set-debug-check-freelist! #f) # turn off checking
1148
1149 Checking of the freelist forces a traversal of the freelist and
1150 a garbage collection before each allocation of a cell. This can
1151 slow down the interpreter dramatically, so the setter should be used to
1152 turn on this extra processing only when necessary.
1153
1154 ** New configure option --enable-debug-malloc
1155
1156 Include code for debugging of calls to scm_must_malloc/realloc/free.
1157
1158 Checks that
1159
1160 1. objects freed by scm_must_free has been mallocated by scm_must_malloc
1161 2. objects reallocated by scm_must_realloc has been allocated by
1162 scm_must_malloc
1163 3. reallocated objects are reallocated with the same what string
1164
1165 But, most importantly, it records the number of allocated objects of
1166 each kind. This is useful when searching for memory leaks.
1167
1168 A Guile compiled with this option provides the primitive
1169 `malloc-stats' which returns an alist with pairs of kind and the
1170 number of objects of that kind.
1171
1172 ** All includes are now referenced relative to the root directory
1173
1174 Since some users have had problems with mixups between Guile and
1175 system headers, we have decided to always refer to Guile headers via
1176 their parent directories. This essentially creates a "private name
1177 space" for Guile headers. This means that the compiler only is given
1178 -I options for the root build and root source directory.
1179
1180 ** Header files kw.h and genio.h have been removed.
1181
1182 ** The module (ice-9 getopt-gnu-style) has been removed.
1183
1184 ** New module (ice-9 documentation)
1185
1186 Implements the interface to documentation strings associated with
1187 objects.
1188
1189 ** New module (ice-9 time)
1190
1191 Provides a macro `time', which displays execution time of a given form.
1192
1193 ** New module (ice-9 history)
1194
1195 Loading this module enables value history in the repl.
1196
1197 * Changes to the stand-alone interpreter
1198
1199 ** New command line option --debug
1200
1201 Start Guile with debugging evaluator and backtraces enabled.
1202
1203 This is useful when debugging your .guile init file or scripts.
1204
1205 ** New help facility
1206
1207 Usage: (help NAME) gives documentation about objects named NAME (a symbol)
1208 (help REGEXP) ditto for objects with names matching REGEXP (a string)
1209 (help 'NAME) gives documentation for NAME, even if it is not an object
1210 (help ,EXPR) gives documentation for object returned by EXPR
1211 (help (my module)) gives module commentary for `(my module)'
1212 (help) gives this text
1213
1214 `help' searches among bindings exported from loaded modules, while
1215 `apropos' searches among bindings visible from the "current" module.
1216
1217 Examples: (help help)
1218 (help cons)
1219 (help "output-string")
1220
1221 ** `help' and `apropos' now prints full module names
1222
1223 ** Dynamic linking now uses libltdl from the libtool package.
1224
1225 The old system dependent code for doing dynamic linking has been
1226 replaced with calls to the libltdl functions which do all the hairy
1227 details for us.
1228
1229 The major improvement is that you can now directly pass libtool
1230 library names like "libfoo.la" to `dynamic-link' and `dynamic-link'
1231 will be able to do the best shared library job you can get, via
1232 libltdl.
1233
1234 The way dynamic libraries are found has changed and is not really
1235 portable across platforms, probably. It is therefore recommended to
1236 use absolute filenames when possible.
1237
1238 If you pass a filename without an extension to `dynamic-link', it will
1239 try a few appropriate ones. Thus, the most platform ignorant way is
1240 to specify a name like "libfoo", without any directories and
1241 extensions.
1242
1243 ** Guile COOP threads are now compatible with LinuxThreads
1244
1245 Previously, COOP threading wasn't possible in applications linked with
1246 Linux POSIX threads due to their use of the stack pointer to find the
1247 thread context. This has now been fixed with a workaround which uses
1248 the pthreads to allocate the stack.
1249
1250 ** New primitives: `pkgdata-dir', `site-dir', `library-dir'
1251
1252 ** Positions of erring expression in scripts
1253
1254 With version 1.3.4, the location of the erring expression in Guile
1255 scipts is no longer automatically reported. (This should have been
1256 documented before the 1.3.4 release.)
1257
1258 You can get this information by enabling recording of positions of
1259 source expressions and running the debugging evaluator. Put this at
1260 the top of your script (or in your "site" file):
1261
1262 (read-enable 'positions)
1263 (debug-enable 'debug)
1264
1265 ** Backtraces in scripts
1266
1267 It is now possible to get backtraces in scripts.
1268
1269 Put
1270
1271 (debug-enable 'debug 'backtrace)
1272
1273 at the top of the script.
1274
1275 (The first options enables the debugging evaluator.
1276 The second enables backtraces.)
1277
1278 ** Part of module system symbol lookup now implemented in C
1279
1280 The eval closure of most modules is now implemented in C. Since this
1281 was one of the bottlenecks for loading speed, Guile now loads code
1282 substantially faster than before.
1283
1284 ** Attempting to get the value of an unbound variable now produces
1285 an exception with a key of 'unbound-variable instead of 'misc-error.
1286
1287 ** The initial default output port is now unbuffered if it's using a
1288 tty device. Previously in this situation it was line-buffered.
1289
1290 ** New hook: after-gc-hook
1291
1292 after-gc-hook takes over the role of gc-thunk. This hook is run at
1293 the first SCM_TICK after a GC. (Thus, the code is run at the same
1294 point during evaluation as signal handlers.)
1295
1296 Note that this hook should be used only for diagnostic and debugging
1297 purposes. It is not certain that it will continue to be well-defined
1298 when this hook is run in the future.
1299
1300 C programmers: Note the new C level hooks scm_before_gc_c_hook,
1301 scm_before_sweep_c_hook, scm_after_gc_c_hook.
1302
1303 ** Improvements to garbage collector
1304
1305 Guile 1.4 has a new policy for triggering heap allocation and
1306 determining the sizes of heap segments. It fixes a number of problems
1307 in the old GC.
1308
1309 1. The new policy can handle two separate pools of cells
1310 (2-word/4-word) better. (The old policy would run wild, allocating
1311 more and more memory for certain programs.)
1312
1313 2. The old code would sometimes allocate far too much heap so that the
1314 Guile process became gigantic. The new code avoids this.
1315
1316 3. The old code would sometimes allocate too little so that few cells
1317 were freed at GC so that, in turn, too much time was spent in GC.
1318
1319 4. The old code would often trigger heap allocation several times in a
1320 row. (The new scheme predicts how large the segments needs to be
1321 in order not to need further allocation.)
1322
1323 All in all, the new GC policy will make larger applications more
1324 efficient.
1325
1326 The new GC scheme also is prepared for POSIX threading. Threads can
1327 allocate private pools of cells ("clusters") with just a single
1328 function call. Allocation of single cells from such a cluster can
1329 then proceed without any need of inter-thread synchronization.
1330
1331 ** New environment variables controlling GC parameters
1332
1333 GUILE_MAX_SEGMENT_SIZE Maximal segment size
1334 (default = 2097000)
1335
1336 Allocation of 2-word cell heaps:
1337
1338 GUILE_INIT_SEGMENT_SIZE_1 Size of initial heap segment in bytes
1339 (default = 360000)
1340
1341 GUILE_MIN_YIELD_1 Minimum number of freed cells at each
1342 GC in percent of total heap size
1343 (default = 40)
1344
1345 Allocation of 4-word cell heaps
1346 (used for real numbers and misc other objects):
1347
1348 GUILE_INIT_SEGMENT_SIZE_2, GUILE_MIN_YIELD_2
1349
1350 (See entry "Way for application to customize GC parameters" under
1351 section "Changes to the scm_ interface" below.)
1352
1353 ** Guile now implements reals using 4-word cells
1354
1355 This speeds up computation with reals. (They were earlier allocated
1356 with `malloc'.) There is still some room for optimizations, however.
1357
1358 ** Some further steps toward POSIX thread support have been taken
1359
1360 *** Guile's critical sections (SCM_DEFER/ALLOW_INTS)
1361 don't have much effect any longer, and many of them will be removed in
1362 next release.
1363
1364 *** Signals
1365 are only handled at the top of the evaluator loop, immediately after
1366 I/O, and in scm_equalp.
1367
1368 *** The GC can allocate thread private pools of pairs.
1369
1370 * Changes to Scheme functions and syntax
1371
1372 ** close-input-port and close-output-port are now R5RS
1373
1374 These procedures have been turned into primitives and have R5RS behaviour.
1375
1376 ** New procedure: simple-format PORT MESSAGE ARG1 ...
1377
1378 (ice-9 boot) makes `format' an alias for `simple-format' until possibly
1379 extended by the more sophisticated version in (ice-9 format)
1380
1381 (simple-format port message . args)
1382 Write MESSAGE to DESTINATION, defaulting to `current-output-port'.
1383 MESSAGE can contain ~A (was %s) and ~S (was %S) escapes. When printed,
1384 the escapes are replaced with corresponding members of ARGS:
1385 ~A formats using `display' and ~S formats using `write'.
1386 If DESTINATION is #t, then use the `current-output-port',
1387 if DESTINATION is #f, then return a string containing the formatted text.
1388 Does not add a trailing newline."
1389
1390 ** string-ref: the second argument is no longer optional.
1391
1392 ** string, list->string: no longer accept strings in their arguments,
1393 only characters, for compatibility with R5RS.
1394
1395 ** New procedure: port-closed? PORT
1396 Returns #t if PORT is closed or #f if it is open.
1397
1398 ** Deprecated: list*
1399
1400 The list* functionality is now provided by cons* (SRFI-1 compliant)
1401
1402 ** New procedure: cons* ARG1 ARG2 ... ARGn
1403
1404 Like `list', but the last arg provides the tail of the constructed list,
1405 returning (cons ARG1 (cons ARG2 (cons ... ARGn))).
1406
1407 Requires at least one argument. If given one argument, that argument
1408 is returned as result.
1409
1410 This function is called `list*' in some other Schemes and in Common LISP.
1411
1412 ** Removed deprecated: serial-map, serial-array-copy!, serial-array-map!
1413
1414 ** New procedure: object-documentation OBJECT
1415
1416 Returns the documentation string associated with OBJECT. The
1417 procedure uses a caching mechanism so that subsequent lookups are
1418 faster.
1419
1420 Exported by (ice-9 documentation).
1421
1422 ** module-name now returns full names of modules
1423
1424 Previously, only the last part of the name was returned (`session' for
1425 `(ice-9 session)'). Ex: `(ice-9 session)'.
1426
1427 * Changes to the gh_ interface
1428
1429 ** Deprecated: gh_int2scmb
1430
1431 Use gh_bool2scm instead.
1432
1433 * Changes to the scm_ interface
1434
1435 ** Guile primitives now carry docstrings!
1436
1437 Thanks to Greg Badros!
1438
1439 ** Guile primitives are defined in a new way: SCM_DEFINE/SCM_DEFINE1/SCM_PROC
1440
1441 Now Guile primitives are defined using the SCM_DEFINE/SCM_DEFINE1/SCM_PROC
1442 macros and must contain a docstring that is extracted into foo.doc using a new
1443 guile-doc-snarf script (that uses guile-doc-snarf.awk).
1444
1445 However, a major overhaul of these macros is scheduled for the next release of
1446 guile.
1447
1448 ** Guile primitives use a new technique for validation of arguments
1449
1450 SCM_VALIDATE_* macros are defined to ease the redundancy and improve
1451 the readability of argument checking.
1452
1453 ** All (nearly?) K&R prototypes for functions replaced with ANSI C equivalents.
1454
1455 ** New macros: SCM_PACK, SCM_UNPACK
1456
1457 Compose/decompose an SCM value.
1458
1459 The SCM type is now treated as an abstract data type and may be defined as a
1460 long, a void* or as a struct, depending on the architecture and compile time
1461 options. This makes it easier to find several types of bugs, for example when
1462 SCM values are treated as integers without conversion. Values of the SCM type
1463 should be treated as "atomic" values. These macros are used when
1464 composing/decomposing an SCM value, either because you want to access
1465 individual bits, or because you want to treat it as an integer value.
1466
1467 E.g., in order to set bit 7 in an SCM value x, use the expression
1468
1469 SCM_PACK (SCM_UNPACK (x) | 0x80)
1470
1471 ** The name property of hooks is deprecated.
1472 Thus, the use of SCM_HOOK_NAME and scm_make_hook_with_name is deprecated.
1473
1474 You can emulate this feature by using object properties.
1475
1476 ** Deprecated macros: SCM_INPORTP, SCM_OUTPORTP, SCM_CRDY, SCM_ICHRP,
1477 SCM_ICHR, SCM_MAKICHR, SCM_SETJMPBUF, SCM_NSTRINGP, SCM_NRWSTRINGP,
1478 SCM_NVECTORP
1479
1480 These macros will be removed in a future release of Guile.
1481
1482 ** The following types, functions and macros from numbers.h are deprecated:
1483 scm_dblproc, SCM_UNEGFIXABLE, SCM_FLOBUFLEN, SCM_INEXP, SCM_CPLXP, SCM_REAL,
1484 SCM_IMAG, SCM_REALPART, scm_makdbl, SCM_SINGP, SCM_NUM2DBL, SCM_NO_BIGDIG
1485
1486 Further, it is recommended not to rely on implementation details for guile's
1487 current implementation of bignums. It is planned to replace this
1488 implementation with gmp in the future.
1489
1490 ** Port internals: the rw_random variable in the scm_port structure
1491 must be set to non-zero in any random access port. In recent Guile
1492 releases it was only set for bidirectional random-access ports.
1493
1494 ** Port internals: the seek ptob procedure is now responsible for
1495 resetting the buffers if required. The change was made so that in the
1496 special case of reading the current position (i.e., seek p 0 SEEK_CUR)
1497 the fport and strport ptobs can avoid resetting the buffers,
1498 in particular to avoid discarding unread chars. An existing port
1499 type can be fixed by adding something like the following to the
1500 beginning of the ptob seek procedure:
1501
1502 if (pt->rw_active == SCM_PORT_READ)
1503 scm_end_input (object);
1504 else if (pt->rw_active == SCM_PORT_WRITE)
1505 ptob->flush (object);
1506
1507 although to actually avoid resetting the buffers and discard unread
1508 chars requires further hacking that depends on the characteristics
1509 of the ptob.
1510
1511 ** Deprecated functions: scm_fseek, scm_tag
1512
1513 These functions are no longer used and will be removed in a future version.
1514
1515 ** The scm_sysmissing procedure is no longer used in libguile.
1516 Unless it turns out to be unexpectedly useful to somebody, it will be
1517 removed in a future version.
1518
1519 ** The format of error message strings has changed
1520
1521 The two C procedures: scm_display_error and scm_error, as well as the
1522 primitive `scm-error', now use scm_simple_format to do their work.
1523 This means that the message strings of all code must be updated to use
1524 ~A where %s was used before, and ~S where %S was used before.
1525
1526 During the period when there still are a lot of old Guiles out there,
1527 you might want to support both old and new versions of Guile.
1528
1529 There are basically two methods to achieve this. Both methods use
1530 autoconf. Put
1531
1532 AC_CHECK_FUNCS(scm_simple_format)
1533
1534 in your configure.in.
1535
1536 Method 1: Use the string concatenation features of ANSI C's
1537 preprocessor.
1538
1539 In C:
1540
1541 #ifdef HAVE_SCM_SIMPLE_FORMAT
1542 #define FMT_S "~S"
1543 #else
1544 #define FMT_S "%S"
1545 #endif
1546
1547 Then represent each of your error messages using a preprocessor macro:
1548
1549 #define E_SPIDER_ERROR "There's a spider in your " ## FMT_S ## "!!!"
1550
1551 In Scheme:
1552
1553 (define fmt-s (if (defined? 'simple-format) "~S" "%S"))
1554 (define make-message string-append)
1555
1556 (define e-spider-error (make-message "There's a spider in your " fmt-s "!!!"))
1557
1558 Method 2: Use the oldfmt function found in doc/oldfmt.c.
1559
1560 In C:
1561
1562 scm_misc_error ("picnic", scm_c_oldfmt0 ("There's a spider in your ~S!!!"),
1563 ...);
1564
1565 In Scheme:
1566
1567 (scm-error 'misc-error "picnic" (oldfmt "There's a spider in your ~S!!!")
1568 ...)
1569
1570
1571 ** Deprecated: coop_mutex_init, coop_condition_variable_init
1572
1573 Don't use the functions coop_mutex_init and
1574 coop_condition_variable_init. They will change.
1575
1576 Use scm_mutex_init and scm_cond_init instead.
1577
1578 ** New function: int scm_cond_timedwait (scm_cond_t *COND, scm_mutex_t *MUTEX, const struct timespec *ABSTIME)
1579 `scm_cond_timedwait' atomically unlocks MUTEX and waits on
1580 COND, as `scm_cond_wait' does, but it also bounds the duration
1581 of the wait. If COND has not been signaled before time ABSTIME,
1582 the mutex MUTEX is re-acquired and `scm_cond_timedwait'
1583 returns the error code `ETIMEDOUT'.
1584
1585 The ABSTIME parameter specifies an absolute time, with the same
1586 origin as `time' and `gettimeofday': an ABSTIME of 0 corresponds
1587 to 00:00:00 GMT, January 1, 1970.
1588
1589 ** New function: scm_cond_broadcast (scm_cond_t *COND)
1590 `scm_cond_broadcast' restarts all the threads that are waiting
1591 on the condition variable COND. Nothing happens if no threads are
1592 waiting on COND.
1593
1594 ** New function: scm_key_create (scm_key_t *KEY, void (*destr_function) (void *))
1595 `scm_key_create' allocates a new TSD key. The key is stored in
1596 the location pointed to by KEY. There is no limit on the number
1597 of keys allocated at a given time. The value initially associated
1598 with the returned key is `NULL' in all currently executing threads.
1599
1600 The DESTR_FUNCTION argument, if not `NULL', specifies a destructor
1601 function associated with the key. When a thread terminates,
1602 DESTR_FUNCTION is called on the value associated with the key in
1603 that thread. The DESTR_FUNCTION is not called if a key is deleted
1604 with `scm_key_delete' or a value is changed with
1605 `scm_setspecific'. The order in which destructor functions are
1606 called at thread termination time is unspecified.
1607
1608 Destructors are not yet implemented.
1609
1610 ** New function: scm_setspecific (scm_key_t KEY, const void *POINTER)
1611 `scm_setspecific' changes the value associated with KEY in the
1612 calling thread, storing the given POINTER instead.
1613
1614 ** New function: scm_getspecific (scm_key_t KEY)
1615 `scm_getspecific' returns the value currently associated with
1616 KEY in the calling thread.
1617
1618 ** New function: scm_key_delete (scm_key_t KEY)
1619 `scm_key_delete' deallocates a TSD key. It does not check
1620 whether non-`NULL' values are associated with that key in the
1621 currently executing threads, nor call the destructor function
1622 associated with the key.
1623
1624 ** New function: scm_c_hook_init (scm_c_hook_t *HOOK, void *HOOK_DATA, scm_c_hook_type_t TYPE)
1625
1626 Initialize a C level hook HOOK with associated HOOK_DATA and type
1627 TYPE. (See scm_c_hook_run ().)
1628
1629 ** New function: scm_c_hook_add (scm_c_hook_t *HOOK, scm_c_hook_function_t FUNC, void *FUNC_DATA, int APPENDP)
1630
1631 Add hook function FUNC with associated FUNC_DATA to HOOK. If APPENDP
1632 is true, add it last, otherwise first. The same FUNC can be added
1633 multiple times if FUNC_DATA differ and vice versa.
1634
1635 ** New function: scm_c_hook_remove (scm_c_hook_t *HOOK, scm_c_hook_function_t FUNC, void *FUNC_DATA)
1636
1637 Remove hook function FUNC with associated FUNC_DATA from HOOK. A
1638 function is only removed if both FUNC and FUNC_DATA matches.
1639
1640 ** New function: void *scm_c_hook_run (scm_c_hook_t *HOOK, void *DATA)
1641
1642 Run hook HOOK passing DATA to the hook functions.
1643
1644 If TYPE is SCM_C_HOOK_NORMAL, all hook functions are run. The value
1645 returned is undefined.
1646
1647 If TYPE is SCM_C_HOOK_OR, hook functions are run until a function
1648 returns a non-NULL value. This value is returned as the result of
1649 scm_c_hook_run. If all functions return NULL, NULL is returned.
1650
1651 If TYPE is SCM_C_HOOK_AND, hook functions are run until a function
1652 returns a NULL value, and NULL is returned. If all functions returns
1653 a non-NULL value, the last value is returned.
1654
1655 ** New C level GC hooks
1656
1657 Five new C level hooks has been added to the garbage collector.
1658
1659 scm_before_gc_c_hook
1660 scm_after_gc_c_hook
1661
1662 are run before locking and after unlocking the heap. The system is
1663 thus in a mode where evaluation can take place. (Except that
1664 scm_before_gc_c_hook must not allocate new cells.)
1665
1666 scm_before_mark_c_hook
1667 scm_before_sweep_c_hook
1668 scm_after_sweep_c_hook
1669
1670 are run when the heap is locked. These are intended for extension of
1671 the GC in a modular fashion. Examples are the weaks and guardians
1672 modules.
1673
1674 ** Way for application to customize GC parameters
1675
1676 The application can set up other default values for the GC heap
1677 allocation parameters
1678
1679 GUILE_INIT_HEAP_SIZE_1, GUILE_MIN_YIELD_1,
1680 GUILE_INIT_HEAP_SIZE_2, GUILE_MIN_YIELD_2,
1681 GUILE_MAX_SEGMENT_SIZE,
1682
1683 by setting
1684
1685 scm_default_init_heap_size_1, scm_default_min_yield_1,
1686 scm_default_init_heap_size_2, scm_default_min_yield_2,
1687 scm_default_max_segment_size
1688
1689 respectively before callong scm_boot_guile.
1690
1691 (See entry "New environment variables ..." in section
1692 "Changes to the stand-alone interpreter" above.)
1693
1694 ** scm_protect_object/scm_unprotect_object now nest
1695
1696 This means that you can call scm_protect_object multiple times on an
1697 object and count on the object being protected until
1698 scm_unprotect_object has been call the same number of times.
1699
1700 The functions also have better time complexity.
1701
1702 Still, it is usually possible to structure the application in a way
1703 that you don't need to use these functions. For example, if you use a
1704 protected standard Guile list to keep track of live objects rather
1705 than some custom data type, objects will die a natural death when they
1706 are no longer needed.
1707
1708 ** Deprecated type tags: scm_tc16_flo, scm_tc_flo, scm_tc_dblr, scm_tc_dblc
1709
1710 Guile does not provide the float representation for inexact real numbers any
1711 more. Now, only doubles are used to represent inexact real numbers. Further,
1712 the tag names scm_tc_dblr and scm_tc_dblc have been changed to scm_tc16_real
1713 and scm_tc16_complex, respectively.
1714
1715 ** Removed deprecated type scm_smobfuns
1716
1717 ** Removed deprecated function scm_newsmob
1718
1719 ** Warning: scm_make_smob_type_mfpe might become deprecated in a future release
1720
1721 There is an ongoing discussion among the developers whether to
1722 deprecate `scm_make_smob_type_mfpe' or not. Please use the current
1723 standard interface (scm_make_smob_type, scm_set_smob_XXX) in new code
1724 until this issue has been settled.
1725
1726 ** Removed deprecated type tag scm_tc16_kw
1727
1728 ** Added type tag scm_tc16_keyword
1729
1730 (This was introduced already in release 1.3.4 but was not documented
1731 until now.)
1732
1733 ** gdb_print now prints "*** Guile not initialized ***" until Guile initialized
1734
1735 * Changes to system call interfaces:
1736
1737 ** The "select" procedure now tests port buffers for the ability to
1738 provide input or accept output. Previously only the underlying file
1739 descriptors were checked.
1740
1741 ** New variable PIPE_BUF: the maximum number of bytes that can be
1742 atomically written to a pipe.
1743
1744 ** If a facility is not available on the system when Guile is
1745 compiled, the corresponding primitive procedure will not be defined.
1746 Previously it would have been defined but would throw a system-error
1747 exception if called. Exception handlers which catch this case may
1748 need minor modification: an error will be thrown with key
1749 'unbound-variable instead of 'system-error. Alternatively it's
1750 now possible to use `defined?' to check whether the facility is
1751 available.
1752
1753 ** Procedures which depend on the timezone should now give the correct
1754 result on systems which cache the TZ environment variable, even if TZ
1755 is changed without calling tzset.
1756
1757 * Changes to the networking interfaces:
1758
1759 ** New functions: htons, ntohs, htonl, ntohl: for converting short and
1760 long integers between network and host format. For now, it's not
1761 particularly convenient to do this kind of thing, but consider:
1762
1763 (define write-network-long
1764 (lambda (value port)
1765 (let ((v (make-uniform-vector 1 1 0)))
1766 (uniform-vector-set! v 0 (htonl value))
1767 (uniform-vector-write v port))))
1768
1769 (define read-network-long
1770 (lambda (port)
1771 (let ((v (make-uniform-vector 1 1 0)))
1772 (uniform-vector-read! v port)
1773 (ntohl (uniform-vector-ref v 0)))))
1774
1775 ** If inet-aton fails, it now throws an error with key 'misc-error
1776 instead of 'system-error, since errno is not relevant.
1777
1778 ** Certain gethostbyname/gethostbyaddr failures now throw errors with
1779 specific keys instead of 'system-error. The latter is inappropriate
1780 since errno will not have been set. The keys are:
1781 'host-not-found, 'try-again, 'no-recovery and 'no-data.
1782
1783 ** sethostent, setnetent, setprotoent, setservent: now take an
1784 optional argument STAYOPEN, which specifies whether the database
1785 remains open after a database entry is accessed randomly (e.g., using
1786 gethostbyname for the hosts database.) The default is #f. Previously
1787 #t was always used.
1788
1789 \f
1790 Changes since Guile 1.3.2:
1791
1792 * Changes to the stand-alone interpreter
1793
1794 ** Debugger
1795
1796 An initial version of the Guile debugger written by Chris Hanson has
1797 been added. The debugger is still under development but is included
1798 in the distribution anyway since it is already quite useful.
1799
1800 Type
1801
1802 (debug)
1803
1804 after an error to enter the debugger. Type `help' inside the debugger
1805 for a description of available commands.
1806
1807 If you prefer to have stack frames numbered and printed in
1808 anti-chronological order and prefer up in the stack to be down on the
1809 screen as is the case in gdb, you can put
1810
1811 (debug-enable 'backwards)
1812
1813 in your .guile startup file. (However, this means that Guile can't
1814 use indentation to indicate stack level.)
1815
1816 The debugger is autoloaded into Guile at the first use.
1817
1818 ** Further enhancements to backtraces
1819
1820 There is a new debug option `width' which controls the maximum width
1821 on the screen of printed stack frames. Fancy printing parameters
1822 ("level" and "length" as in Common LISP) are adaptively adjusted for
1823 each stack frame to give maximum information while still fitting
1824 within the bounds. If the stack frame can't be made to fit by
1825 adjusting parameters, it is simply cut off at the end. This is marked
1826 with a `$'.
1827
1828 ** Some modules are now only loaded when the repl is started
1829
1830 The modules (ice-9 debug), (ice-9 session), (ice-9 threads) and (ice-9
1831 regex) are now loaded into (guile-user) only if the repl has been
1832 started. The effect is that the startup time for scripts has been
1833 reduced to 30% of what it was previously.
1834
1835 Correctly written scripts load the modules they require at the top of
1836 the file and should not be affected by this change.
1837
1838 ** Hooks are now represented as smobs
1839
1840 * Changes to Scheme functions and syntax
1841
1842 ** Readline support has changed again.
1843
1844 The old (readline-activator) module is gone. Use (ice-9 readline)
1845 instead, which now contains all readline functionality. So the code
1846 to activate readline is now
1847
1848 (use-modules (ice-9 readline))
1849 (activate-readline)
1850
1851 This should work at any time, including from the guile prompt.
1852
1853 To avoid confusion about the terms of Guile's license, please only
1854 enable readline for your personal use; please don't make it the
1855 default for others. Here is why we make this rather odd-sounding
1856 request:
1857
1858 Guile is normally licensed under a weakened form of the GNU General
1859 Public License, which allows you to link code with Guile without
1860 placing that code under the GPL. This exception is important to some
1861 people.
1862
1863 However, since readline is distributed under the GNU General Public
1864 License, when you link Guile with readline, either statically or
1865 dynamically, you effectively change Guile's license to the strict GPL.
1866 Whenever you link any strictly GPL'd code into Guile, uses of Guile
1867 which are normally permitted become forbidden. This is a rather
1868 non-obvious consequence of the licensing terms.
1869
1870 So, to make sure things remain clear, please let people choose for
1871 themselves whether to link GPL'd libraries like readline with Guile.
1872
1873 ** regexp-substitute/global has changed slightly, but incompatibly.
1874
1875 If you include a function in the item list, the string of the match
1876 object it receives is the same string passed to
1877 regexp-substitute/global, not some suffix of that string.
1878 Correspondingly, the match's positions are relative to the entire
1879 string, not the suffix.
1880
1881 If the regexp can match the empty string, the way matches are chosen
1882 from the string has changed. regexp-substitute/global recognizes the
1883 same set of matches that list-matches does; see below.
1884
1885 ** New function: list-matches REGEXP STRING [FLAGS]
1886
1887 Return a list of match objects, one for every non-overlapping, maximal
1888 match of REGEXP in STRING. The matches appear in left-to-right order.
1889 list-matches only reports matches of the empty string if there are no
1890 other matches which begin on, end at, or include the empty match's
1891 position.
1892
1893 If present, FLAGS is passed as the FLAGS argument to regexp-exec.
1894
1895 ** New function: fold-matches REGEXP STRING INIT PROC [FLAGS]
1896
1897 For each match of REGEXP in STRING, apply PROC to the match object,
1898 and the last value PROC returned, or INIT for the first call. Return
1899 the last value returned by PROC. We apply PROC to the matches as they
1900 appear from left to right.
1901
1902 This function recognizes matches according to the same criteria as
1903 list-matches.
1904
1905 Thus, you could define list-matches like this:
1906
1907 (define (list-matches regexp string . flags)
1908 (reverse! (apply fold-matches regexp string '() cons flags)))
1909
1910 If present, FLAGS is passed as the FLAGS argument to regexp-exec.
1911
1912 ** Hooks
1913
1914 *** New function: hook? OBJ
1915
1916 Return #t if OBJ is a hook, otherwise #f.
1917
1918 *** New function: make-hook-with-name NAME [ARITY]
1919
1920 Return a hook with name NAME and arity ARITY. The default value for
1921 ARITY is 0. The only effect of NAME is that it will appear when the
1922 hook object is printed to ease debugging.
1923
1924 *** New function: hook-empty? HOOK
1925
1926 Return #t if HOOK doesn't contain any procedures, otherwise #f.
1927
1928 *** New function: hook->list HOOK
1929
1930 Return a list of the procedures that are called when run-hook is
1931 applied to HOOK.
1932
1933 ** `map' signals an error if its argument lists are not all the same length.
1934
1935 This is the behavior required by R5RS, so this change is really a bug
1936 fix. But it seems to affect a lot of people's code, so we're
1937 mentioning it here anyway.
1938
1939 ** Print-state handling has been made more transparent
1940
1941 Under certain circumstances, ports are represented as a port with an
1942 associated print state. Earlier, this pair was represented as a pair
1943 (see "Some magic has been added to the printer" below). It is now
1944 indistinguishable (almost; see `get-print-state') from a port on the
1945 user level.
1946
1947 *** New function: port-with-print-state OUTPUT-PORT PRINT-STATE
1948
1949 Return a new port with the associated print state PRINT-STATE.
1950
1951 *** New function: get-print-state OUTPUT-PORT
1952
1953 Return the print state associated with this port if it exists,
1954 otherwise return #f.
1955
1956 *** New function: directory-stream? OBJECT
1957
1958 Returns true iff OBJECT is a directory stream --- the sort of object
1959 returned by `opendir'.
1960
1961 ** New function: using-readline?
1962
1963 Return #t if readline is in use in the current repl.
1964
1965 ** structs will be removed in 1.4
1966
1967 Structs will be replaced in Guile 1.4. We will merge GOOPS into Guile
1968 and use GOOPS objects as the fundamental record type.
1969
1970 * Changes to the scm_ interface
1971
1972 ** structs will be removed in 1.4
1973
1974 The entire current struct interface (struct.c, struct.h) will be
1975 replaced in Guile 1.4. We will merge GOOPS into libguile and use
1976 GOOPS objects as the fundamental record type.
1977
1978 ** The internal representation of subr's has changed
1979
1980 Instead of giving a hint to the subr name, the CAR field of the subr
1981 now contains an index to a subr entry in scm_subr_table.
1982
1983 *** New variable: scm_subr_table
1984
1985 An array of subr entries. A subr entry contains the name, properties
1986 and documentation associated with the subr. The properties and
1987 documentation slots are not yet used.
1988
1989 ** A new scheme for "forwarding" calls to a builtin to a generic function
1990
1991 It is now possible to extend the functionality of some Guile
1992 primitives by letting them defer a call to a GOOPS generic function on
1993 argument mismatch. This means that there is no loss of efficiency in
1994 normal evaluation.
1995
1996 Example:
1997
1998 (use-modules (oop goops)) ; Must be GOOPS version 0.2.
1999 (define-method + ((x <string>) (y <string>))
2000 (string-append x y))
2001
2002 + will still be as efficient as usual in numerical calculations, but
2003 can also be used for concatenating strings.
2004
2005 Who will be the first one to extend Guile's numerical tower to
2006 rationals? :) [OK, there a few other things to fix before this can
2007 be made in a clean way.]
2008
2009 *** New snarf macros for defining primitives: SCM_GPROC, SCM_GPROC1
2010
2011 New macro: SCM_GPROC (CNAME, SNAME, REQ, OPT, VAR, CFUNC, GENERIC)
2012
2013 New macro: SCM_GPROC1 (CNAME, SNAME, TYPE, CFUNC, GENERIC)
2014
2015 These do the same job as SCM_PROC and SCM_PROC1, but they also define
2016 a variable GENERIC which can be used by the dispatch macros below.
2017
2018 [This is experimental code which may change soon.]
2019
2020 *** New macros for forwarding control to a generic on arg type error
2021
2022 New macro: SCM_WTA_DISPATCH_1 (GENERIC, ARG1, POS, SUBR)
2023
2024 New macro: SCM_WTA_DISPATCH_2 (GENERIC, ARG1, ARG2, POS, SUBR)
2025
2026 These correspond to the scm_wta function call, and have the same
2027 behaviour until the user has called the GOOPS primitive
2028 `enable-primitive-generic!'. After that, these macros will apply the
2029 generic function GENERIC to the argument(s) instead of calling
2030 scm_wta.
2031
2032 [This is experimental code which may change soon.]
2033
2034 *** New macros for argument testing with generic dispatch
2035
2036 New macro: SCM_GASSERT1 (COND, GENERIC, ARG1, POS, SUBR)
2037
2038 New macro: SCM_GASSERT2 (COND, GENERIC, ARG1, ARG2, POS, SUBR)
2039
2040 These correspond to the SCM_ASSERT macro, but will defer control to
2041 GENERIC on error after `enable-primitive-generic!' has been called.
2042
2043 [This is experimental code which may change soon.]
2044
2045 ** New function: SCM scm_eval_body (SCM body, SCM env)
2046
2047 Evaluates the body of a special form.
2048
2049 ** The internal representation of struct's has changed
2050
2051 Previously, four slots were allocated for the procedure(s) of entities
2052 and operators. The motivation for this representation had to do with
2053 the structure of the evaluator, the wish to support tail-recursive
2054 generic functions, and efficiency. Since the generic function
2055 dispatch mechanism has changed, there is no longer a need for such an
2056 expensive representation, and the representation has been simplified.
2057
2058 This should not make any difference for most users.
2059
2060 ** GOOPS support has been cleaned up.
2061
2062 Some code has been moved from eval.c to objects.c and code in both of
2063 these compilation units has been cleaned up and better structured.
2064
2065 *** New functions for applying generic functions
2066
2067 New function: SCM scm_apply_generic (GENERIC, ARGS)
2068 New function: SCM scm_call_generic_0 (GENERIC)
2069 New function: SCM scm_call_generic_1 (GENERIC, ARG1)
2070 New function: SCM scm_call_generic_2 (GENERIC, ARG1, ARG2)
2071 New function: SCM scm_call_generic_3 (GENERIC, ARG1, ARG2, ARG3)
2072
2073 ** Deprecated function: scm_make_named_hook
2074
2075 It is now replaced by:
2076
2077 ** New function: SCM scm_create_hook (const char *name, int arity)
2078
2079 Creates a hook in the same way as make-hook above but also
2080 binds a variable named NAME to it.
2081
2082 This is the typical way of creating a hook from C code.
2083
2084 Currently, the variable is created in the "current" module.
2085 This might change when we get the new module system.
2086
2087 [The behaviour is identical to scm_make_named_hook.]
2088
2089
2090 \f
2091 Changes since Guile 1.3:
2092
2093 * Changes to mailing lists
2094
2095 ** Some of the Guile mailing lists have moved to sourceware.cygnus.com.
2096
2097 See the README file to find current addresses for all the Guile
2098 mailing lists.
2099
2100 * Changes to the distribution
2101
2102 ** Readline support is no longer included with Guile by default.
2103
2104 Based on the different license terms of Guile and Readline, we
2105 concluded that Guile should not *by default* cause the linking of
2106 Readline into an application program. Readline support is now offered
2107 as a separate module, which is linked into an application only when
2108 you explicitly specify it.
2109
2110 Although Guile is GNU software, its distribution terms add a special
2111 exception to the usual GNU General Public License (GPL). Guile's
2112 license includes a clause that allows you to link Guile with non-free
2113 programs. We add this exception so as not to put Guile at a
2114 disadvantage vis-a-vis other extensibility packages that support other
2115 languages.
2116
2117 In contrast, the GNU Readline library is distributed under the GNU
2118 General Public License pure and simple. This means that you may not
2119 link Readline, even dynamically, into an application unless it is
2120 distributed under a free software license that is compatible the GPL.
2121
2122 Because of this difference in distribution terms, an application that
2123 can use Guile may not be able to use Readline. Now users will be
2124 explicitly offered two independent decisions about the use of these
2125 two packages.
2126
2127 You can activate the readline support by issuing
2128
2129 (use-modules (readline-activator))
2130 (activate-readline)
2131
2132 from your ".guile" file, for example.
2133
2134 * Changes to the stand-alone interpreter
2135
2136 ** All builtins now print as primitives.
2137 Previously builtin procedures not belonging to the fundamental subr
2138 types printed as #<compiled closure #<primitive-procedure gsubr-apply>>.
2139 Now, they print as #<primitive-procedure NAME>.
2140
2141 ** Backtraces slightly more intelligible.
2142 gsubr-apply and macro transformer application frames no longer appear
2143 in backtraces.
2144
2145 * Changes to Scheme functions and syntax
2146
2147 ** Guile now correctly handles internal defines by rewriting them into
2148 their equivalent letrec. Previously, internal defines would
2149 incrementally add to the innermost environment, without checking
2150 whether the restrictions specified in RnRS were met. This lead to the
2151 correct behaviour when these restriction actually were met, but didn't
2152 catch all illegal uses. Such an illegal use could lead to crashes of
2153 the Guile interpreter or or other unwanted results. An example of
2154 incorrect internal defines that made Guile behave erratically:
2155
2156 (let ()
2157 (define a 1)
2158 (define (b) a)
2159 (define c (1+ (b)))
2160 (define d 3)
2161
2162 (b))
2163
2164 => 2
2165
2166 The problem with this example is that the definition of `c' uses the
2167 value of `b' directly. This confuses the meoization machine of Guile
2168 so that the second call of `b' (this time in a larger environment that
2169 also contains bindings for `c' and `d') refers to the binding of `c'
2170 instead of `a'. You could also make Guile crash with a variation on
2171 this theme:
2172
2173 (define (foo flag)
2174 (define a 1)
2175 (define (b flag) (if flag a 1))
2176 (define c (1+ (b flag)))
2177 (define d 3)
2178
2179 (b #t))
2180
2181 (foo #f)
2182 (foo #t)
2183
2184 From now on, Guile will issue an `Unbound variable: b' error message
2185 for both examples.
2186
2187 ** Hooks
2188
2189 A hook contains a list of functions which should be called on
2190 particular occasions in an existing program. Hooks are used for
2191 customization.
2192
2193 A window manager might have a hook before-window-map-hook. The window
2194 manager uses the function run-hooks to call all functions stored in
2195 before-window-map-hook each time a window is mapped. The user can
2196 store functions in the hook using add-hook!.
2197
2198 In Guile, hooks are first class objects.
2199
2200 *** New function: make-hook [N_ARGS]
2201
2202 Return a hook for hook functions which can take N_ARGS arguments.
2203 The default value for N_ARGS is 0.
2204
2205 (See also scm_make_named_hook below.)
2206
2207 *** New function: add-hook! HOOK PROC [APPEND_P]
2208
2209 Put PROC at the beginning of the list of functions stored in HOOK.
2210 If APPEND_P is supplied, and non-false, put PROC at the end instead.
2211
2212 PROC must be able to take the number of arguments specified when the
2213 hook was created.
2214
2215 If PROC already exists in HOOK, then remove it first.
2216
2217 *** New function: remove-hook! HOOK PROC
2218
2219 Remove PROC from the list of functions in HOOK.
2220
2221 *** New function: reset-hook! HOOK
2222
2223 Clear the list of hook functions stored in HOOK.
2224
2225 *** New function: run-hook HOOK ARG1 ...
2226
2227 Run all hook functions stored in HOOK with arguments ARG1 ... .
2228 The number of arguments supplied must correspond to the number given
2229 when the hook was created.
2230
2231 ** The function `dynamic-link' now takes optional keyword arguments.
2232 The only keyword argument that is currently defined is `:global
2233 BOOL'. With it, you can control whether the shared library will be
2234 linked in global mode or not. In global mode, the symbols from the
2235 linked library can be used to resolve references from other
2236 dynamically linked libraries. In non-global mode, the linked
2237 library is essentially invisible and can only be accessed via
2238 `dynamic-func', etc. The default is now to link in global mode.
2239 Previously, the default has been non-global mode.
2240
2241 The `#:global' keyword is only effective on platforms that support
2242 the dlopen family of functions.
2243
2244 ** New function `provided?'
2245
2246 - Function: provided? FEATURE
2247 Return true iff FEATURE is supported by this installation of
2248 Guile. FEATURE must be a symbol naming a feature; the global
2249 variable `*features*' is a list of available features.
2250
2251 ** Changes to the module (ice-9 expect):
2252
2253 *** The expect-strings macro now matches `$' in a regular expression
2254 only at a line-break or end-of-file by default. Previously it would
2255 match the end of the string accumulated so far. The old behaviour
2256 can be obtained by setting the variable `expect-strings-exec-flags'
2257 to 0.
2258
2259 *** The expect-strings macro now uses a variable `expect-strings-exec-flags'
2260 for the regexp-exec flags. If `regexp/noteol' is included, then `$'
2261 in a regular expression will still match before a line-break or
2262 end-of-file. The default is `regexp/noteol'.
2263
2264 *** The expect-strings macro now uses a variable
2265 `expect-strings-compile-flags' for the flags to be supplied to
2266 `make-regexp'. The default is `regexp/newline', which was previously
2267 hard-coded.
2268
2269 *** The expect macro now supplies two arguments to a match procedure:
2270 the current accumulated string and a flag to indicate whether
2271 end-of-file has been reached. Previously only the string was supplied.
2272 If end-of-file is reached, the match procedure will be called an
2273 additional time with the same accumulated string as the previous call
2274 but with the flag set.
2275
2276 ** New module (ice-9 format), implementing the Common Lisp `format' function.
2277
2278 This code, and the documentation for it that appears here, was
2279 borrowed from SLIB, with minor adaptations for Guile.
2280
2281 - Function: format DESTINATION FORMAT-STRING . ARGUMENTS
2282 An almost complete implementation of Common LISP format description
2283 according to the CL reference book `Common LISP' from Guy L.
2284 Steele, Digital Press. Backward compatible to most of the
2285 available Scheme format implementations.
2286
2287 Returns `#t', `#f' or a string; has side effect of printing
2288 according to FORMAT-STRING. If DESTINATION is `#t', the output is
2289 to the current output port and `#t' is returned. If DESTINATION
2290 is `#f', a formatted string is returned as the result of the call.
2291 NEW: If DESTINATION is a string, DESTINATION is regarded as the
2292 format string; FORMAT-STRING is then the first argument and the
2293 output is returned as a string. If DESTINATION is a number, the
2294 output is to the current error port if available by the
2295 implementation. Otherwise DESTINATION must be an output port and
2296 `#t' is returned.
2297
2298 FORMAT-STRING must be a string. In case of a formatting error
2299 format returns `#f' and prints a message on the current output or
2300 error port. Characters are output as if the string were output by
2301 the `display' function with the exception of those prefixed by a
2302 tilde (~). For a detailed description of the FORMAT-STRING syntax
2303 please consult a Common LISP format reference manual. For a test
2304 suite to verify this format implementation load `formatst.scm'.
2305 Please send bug reports to `lutzeb@cs.tu-berlin.de'.
2306
2307 Note: `format' is not reentrant, i.e. only one `format'-call may
2308 be executed at a time.
2309
2310
2311 *** Format Specification (Format version 3.0)
2312
2313 Please consult a Common LISP format reference manual for a detailed
2314 description of the format string syntax. For a demonstration of the
2315 implemented directives see `formatst.scm'.
2316
2317 This implementation supports directive parameters and modifiers (`:'
2318 and `@' characters). Multiple parameters must be separated by a comma
2319 (`,'). Parameters can be numerical parameters (positive or negative),
2320 character parameters (prefixed by a quote character (`''), variable
2321 parameters (`v'), number of rest arguments parameter (`#'), empty and
2322 default parameters. Directive characters are case independent. The
2323 general form of a directive is:
2324
2325 DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER
2326
2327 DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ]
2328
2329 *** Implemented CL Format Control Directives
2330
2331 Documentation syntax: Uppercase characters represent the
2332 corresponding control directive characters. Lowercase characters
2333 represent control directive parameter descriptions.
2334
2335 `~A'
2336 Any (print as `display' does).
2337 `~@A'
2338 left pad.
2339
2340 `~MINCOL,COLINC,MINPAD,PADCHARA'
2341 full padding.
2342
2343 `~S'
2344 S-expression (print as `write' does).
2345 `~@S'
2346 left pad.
2347
2348 `~MINCOL,COLINC,MINPAD,PADCHARS'
2349 full padding.
2350
2351 `~D'
2352 Decimal.
2353 `~@D'
2354 print number sign always.
2355
2356 `~:D'
2357 print comma separated.
2358
2359 `~MINCOL,PADCHAR,COMMACHARD'
2360 padding.
2361
2362 `~X'
2363 Hexadecimal.
2364 `~@X'
2365 print number sign always.
2366
2367 `~:X'
2368 print comma separated.
2369
2370 `~MINCOL,PADCHAR,COMMACHARX'
2371 padding.
2372
2373 `~O'
2374 Octal.
2375 `~@O'
2376 print number sign always.
2377
2378 `~:O'
2379 print comma separated.
2380
2381 `~MINCOL,PADCHAR,COMMACHARO'
2382 padding.
2383
2384 `~B'
2385 Binary.
2386 `~@B'
2387 print number sign always.
2388
2389 `~:B'
2390 print comma separated.
2391
2392 `~MINCOL,PADCHAR,COMMACHARB'
2393 padding.
2394
2395 `~NR'
2396 Radix N.
2397 `~N,MINCOL,PADCHAR,COMMACHARR'
2398 padding.
2399
2400 `~@R'
2401 print a number as a Roman numeral.
2402
2403 `~:@R'
2404 print a number as an "old fashioned" Roman numeral.
2405
2406 `~:R'
2407 print a number as an ordinal English number.
2408
2409 `~:@R'
2410 print a number as a cardinal English number.
2411
2412 `~P'
2413 Plural.
2414 `~@P'
2415 prints `y' and `ies'.
2416
2417 `~:P'
2418 as `~P but jumps 1 argument backward.'
2419
2420 `~:@P'
2421 as `~@P but jumps 1 argument backward.'
2422
2423 `~C'
2424 Character.
2425 `~@C'
2426 prints a character as the reader can understand it (i.e. `#\'
2427 prefixing).
2428
2429 `~:C'
2430 prints a character as emacs does (eg. `^C' for ASCII 03).
2431
2432 `~F'
2433 Fixed-format floating-point (prints a flonum like MMM.NNN).
2434 `~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF'
2435 `~@F'
2436 If the number is positive a plus sign is printed.
2437
2438 `~E'
2439 Exponential floating-point (prints a flonum like MMM.NNN`E'EE).
2440 `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE'
2441 `~@E'
2442 If the number is positive a plus sign is printed.
2443
2444 `~G'
2445 General floating-point (prints a flonum either fixed or
2446 exponential).
2447 `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG'
2448 `~@G'
2449 If the number is positive a plus sign is printed.
2450
2451 `~$'
2452 Dollars floating-point (prints a flonum in fixed with signs
2453 separated).
2454 `~DIGITS,SCALE,WIDTH,PADCHAR$'
2455 `~@$'
2456 If the number is positive a plus sign is printed.
2457
2458 `~:@$'
2459 A sign is always printed and appears before the padding.
2460
2461 `~:$'
2462 The sign appears before the padding.
2463
2464 `~%'
2465 Newline.
2466 `~N%'
2467 print N newlines.
2468
2469 `~&'
2470 print newline if not at the beginning of the output line.
2471 `~N&'
2472 prints `~&' and then N-1 newlines.
2473
2474 `~|'
2475 Page Separator.
2476 `~N|'
2477 print N page separators.
2478
2479 `~~'
2480 Tilde.
2481 `~N~'
2482 print N tildes.
2483
2484 `~'<newline>
2485 Continuation Line.
2486 `~:'<newline>
2487 newline is ignored, white space left.
2488
2489 `~@'<newline>
2490 newline is left, white space ignored.
2491
2492 `~T'
2493 Tabulation.
2494 `~@T'
2495 relative tabulation.
2496
2497 `~COLNUM,COLINCT'
2498 full tabulation.
2499
2500 `~?'
2501 Indirection (expects indirect arguments as a list).
2502 `~@?'
2503 extracts indirect arguments from format arguments.
2504
2505 `~(STR~)'
2506 Case conversion (converts by `string-downcase').
2507 `~:(STR~)'
2508 converts by `string-capitalize'.
2509
2510 `~@(STR~)'
2511 converts by `string-capitalize-first'.
2512
2513 `~:@(STR~)'
2514 converts by `string-upcase'.
2515
2516 `~*'
2517 Argument Jumping (jumps 1 argument forward).
2518 `~N*'
2519 jumps N arguments forward.
2520
2521 `~:*'
2522 jumps 1 argument backward.
2523
2524 `~N:*'
2525 jumps N arguments backward.
2526
2527 `~@*'
2528 jumps to the 0th argument.
2529
2530 `~N@*'
2531 jumps to the Nth argument (beginning from 0)
2532
2533 `~[STR0~;STR1~;...~;STRN~]'
2534 Conditional Expression (numerical clause conditional).
2535 `~N['
2536 take argument from N.
2537
2538 `~@['
2539 true test conditional.
2540
2541 `~:['
2542 if-else-then conditional.
2543
2544 `~;'
2545 clause separator.
2546
2547 `~:;'
2548 default clause follows.
2549
2550 `~{STR~}'
2551 Iteration (args come from the next argument (a list)).
2552 `~N{'
2553 at most N iterations.
2554
2555 `~:{'
2556 args from next arg (a list of lists).
2557
2558 `~@{'
2559 args from the rest of arguments.
2560
2561 `~:@{'
2562 args from the rest args (lists).
2563
2564 `~^'
2565 Up and out.
2566 `~N^'
2567 aborts if N = 0
2568
2569 `~N,M^'
2570 aborts if N = M
2571
2572 `~N,M,K^'
2573 aborts if N <= M <= K
2574
2575 *** Not Implemented CL Format Control Directives
2576
2577 `~:A'
2578 print `#f' as an empty list (see below).
2579
2580 `~:S'
2581 print `#f' as an empty list (see below).
2582
2583 `~<~>'
2584 Justification.
2585
2586 `~:^'
2587 (sorry I don't understand its semantics completely)
2588
2589 *** Extended, Replaced and Additional Control Directives
2590
2591 `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD'
2592 `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX'
2593 `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO'
2594 `~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB'
2595 `~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR'
2596 COMMAWIDTH is the number of characters between two comma
2597 characters.
2598
2599 `~I'
2600 print a R4RS complex number as `~F~@Fi' with passed parameters for
2601 `~F'.
2602
2603 `~Y'
2604 Pretty print formatting of an argument for scheme code lists.
2605
2606 `~K'
2607 Same as `~?.'
2608
2609 `~!'
2610 Flushes the output if format DESTINATION is a port.
2611
2612 `~_'
2613 Print a `#\space' character
2614 `~N_'
2615 print N `#\space' characters.
2616
2617 `~/'
2618 Print a `#\tab' character
2619 `~N/'
2620 print N `#\tab' characters.
2621
2622 `~NC'
2623 Takes N as an integer representation for a character. No arguments
2624 are consumed. N is converted to a character by `integer->char'. N
2625 must be a positive decimal number.
2626
2627 `~:S'
2628 Print out readproof. Prints out internal objects represented as
2629 `#<...>' as strings `"#<...>"' so that the format output can always
2630 be processed by `read'.
2631
2632 `~:A'
2633 Print out readproof. Prints out internal objects represented as
2634 `#<...>' as strings `"#<...>"' so that the format output can always
2635 be processed by `read'.
2636
2637 `~Q'
2638 Prints information and a copyright notice on the format
2639 implementation.
2640 `~:Q'
2641 prints format version.
2642
2643 `~F, ~E, ~G, ~$'
2644 may also print number strings, i.e. passing a number as a string
2645 and format it accordingly.
2646
2647 *** Configuration Variables
2648
2649 The format module exports some configuration variables to suit the
2650 systems and users needs. There should be no modification necessary for
2651 the configuration that comes with Guile. Format detects automatically
2652 if the running scheme system implements floating point numbers and
2653 complex numbers.
2654
2655 format:symbol-case-conv
2656 Symbols are converted by `symbol->string' so the case type of the
2657 printed symbols is implementation dependent.
2658 `format:symbol-case-conv' is a one arg closure which is either
2659 `#f' (no conversion), `string-upcase', `string-downcase' or
2660 `string-capitalize'. (default `#f')
2661
2662 format:iobj-case-conv
2663 As FORMAT:SYMBOL-CASE-CONV but applies for the representation of
2664 implementation internal objects. (default `#f')
2665
2666 format:expch
2667 The character prefixing the exponent value in `~E' printing.
2668 (default `#\E')
2669
2670 *** Compatibility With Other Format Implementations
2671
2672 SLIB format 2.x:
2673 See `format.doc'.
2674
2675 SLIB format 1.4:
2676 Downward compatible except for padding support and `~A', `~S',
2677 `~P', `~X' uppercase printing. SLIB format 1.4 uses C-style
2678 `printf' padding support which is completely replaced by the CL
2679 `format' padding style.
2680
2681 MIT C-Scheme 7.1:
2682 Downward compatible except for `~', which is not documented
2683 (ignores all characters inside the format string up to a newline
2684 character). (7.1 implements `~a', `~s', ~NEWLINE, `~~', `~%',
2685 numerical and variable parameters and `:/@' modifiers in the CL
2686 sense).
2687
2688 Elk 1.5/2.0:
2689 Downward compatible except for `~A' and `~S' which print in
2690 uppercase. (Elk implements `~a', `~s', `~~', and `~%' (no
2691 directive parameters or modifiers)).
2692
2693 Scheme->C 01nov91:
2694 Downward compatible except for an optional destination parameter:
2695 S2C accepts a format call without a destination which returns a
2696 formatted string. This is equivalent to a #f destination in S2C.
2697 (S2C implements `~a', `~s', `~c', `~%', and `~~' (no directive
2698 parameters or modifiers)).
2699
2700
2701 ** Changes to string-handling functions.
2702
2703 These functions were added to support the (ice-9 format) module, above.
2704
2705 *** New function: string-upcase STRING
2706 *** New function: string-downcase STRING
2707
2708 These are non-destructive versions of the existing string-upcase! and
2709 string-downcase! functions.
2710
2711 *** New function: string-capitalize! STRING
2712 *** New function: string-capitalize STRING
2713
2714 These functions convert the first letter of each word in the string to
2715 upper case. Thus:
2716
2717 (string-capitalize "howdy there")
2718 => "Howdy There"
2719
2720 As with the other functions, string-capitalize! modifies the string in
2721 place, while string-capitalize returns a modified copy of its argument.
2722
2723 *** New function: string-ci->symbol STRING
2724
2725 Return a symbol whose name is STRING, but having the same case as if
2726 the symbol had be read by `read'.
2727
2728 Guile can be configured to be sensitive or insensitive to case
2729 differences in Scheme identifiers. If Guile is case-insensitive, all
2730 symbols are converted to lower case on input. The `string-ci->symbol'
2731 function returns a symbol whose name in STRING, transformed as Guile
2732 would if STRING were input.
2733
2734 *** New function: substring-move! STRING1 START END STRING2 START
2735
2736 Copy the substring of STRING1 from START (inclusive) to END
2737 (exclusive) to STRING2 at START. STRING1 and STRING2 may be the same
2738 string, and the source and destination areas may overlap; in all
2739 cases, the function behaves as if all the characters were copied
2740 simultanously.
2741
2742 *** Extended functions: substring-move-left! substring-move-right!
2743
2744 These functions now correctly copy arbitrarily overlapping substrings;
2745 they are both synonyms for substring-move!.
2746
2747
2748 ** New module (ice-9 getopt-long), with the function `getopt-long'.
2749
2750 getopt-long is a function for parsing command-line arguments in a
2751 manner consistent with other GNU programs.
2752
2753 (getopt-long ARGS GRAMMAR)
2754 Parse the arguments ARGS according to the argument list grammar GRAMMAR.
2755
2756 ARGS should be a list of strings. Its first element should be the
2757 name of the program; subsequent elements should be the arguments
2758 that were passed to the program on the command line. The
2759 `program-arguments' procedure returns a list of this form.
2760
2761 GRAMMAR is a list of the form:
2762 ((OPTION (PROPERTY VALUE) ...) ...)
2763
2764 Each OPTION should be a symbol. `getopt-long' will accept a
2765 command-line option named `--OPTION'.
2766 Each option can have the following (PROPERTY VALUE) pairs:
2767
2768 (single-char CHAR) --- Accept `-CHAR' as a single-character
2769 equivalent to `--OPTION'. This is how to specify traditional
2770 Unix-style flags.
2771 (required? BOOL) --- If BOOL is true, the option is required.
2772 getopt-long will raise an error if it is not found in ARGS.
2773 (value BOOL) --- If BOOL is #t, the option accepts a value; if
2774 it is #f, it does not; and if it is the symbol
2775 `optional', the option may appear in ARGS with or
2776 without a value.
2777 (predicate FUNC) --- If the option accepts a value (i.e. you
2778 specified `(value #t)' for this option), then getopt
2779 will apply FUNC to the value, and throw an exception
2780 if it returns #f. FUNC should be a procedure which
2781 accepts a string and returns a boolean value; you may
2782 need to use quasiquotes to get it into GRAMMAR.
2783
2784 The (PROPERTY VALUE) pairs may occur in any order, but each
2785 property may occur only once. By default, options do not have
2786 single-character equivalents, are not required, and do not take
2787 values.
2788
2789 In ARGS, single-character options may be combined, in the usual
2790 Unix fashion: ("-x" "-y") is equivalent to ("-xy"). If an option
2791 accepts values, then it must be the last option in the
2792 combination; the value is the next argument. So, for example, using
2793 the following grammar:
2794 ((apples (single-char #\a))
2795 (blimps (single-char #\b) (value #t))
2796 (catalexis (single-char #\c) (value #t)))
2797 the following argument lists would be acceptable:
2798 ("-a" "-b" "bang" "-c" "couth") ("bang" and "couth" are the values
2799 for "blimps" and "catalexis")
2800 ("-ab" "bang" "-c" "couth") (same)
2801 ("-ac" "couth" "-b" "bang") (same)
2802 ("-abc" "couth" "bang") (an error, since `-b' is not the
2803 last option in its combination)
2804
2805 If an option's value is optional, then `getopt-long' decides
2806 whether it has a value by looking at what follows it in ARGS. If
2807 the next element is a string, and it does not appear to be an
2808 option itself, then that string is the option's value.
2809
2810 The value of a long option can appear as the next element in ARGS,
2811 or it can follow the option name, separated by an `=' character.
2812 Thus, using the same grammar as above, the following argument lists
2813 are equivalent:
2814 ("--apples" "Braeburn" "--blimps" "Goodyear")
2815 ("--apples=Braeburn" "--blimps" "Goodyear")
2816 ("--blimps" "Goodyear" "--apples=Braeburn")
2817
2818 If the option "--" appears in ARGS, argument parsing stops there;
2819 subsequent arguments are returned as ordinary arguments, even if
2820 they resemble options. So, in the argument list:
2821 ("--apples" "Granny Smith" "--" "--blimp" "Goodyear")
2822 `getopt-long' will recognize the `apples' option as having the
2823 value "Granny Smith", but it will not recognize the `blimp'
2824 option; it will return the strings "--blimp" and "Goodyear" as
2825 ordinary argument strings.
2826
2827 The `getopt-long' function returns the parsed argument list as an
2828 assocation list, mapping option names --- the symbols from GRAMMAR
2829 --- onto their values, or #t if the option does not accept a value.
2830 Unused options do not appear in the alist.
2831
2832 All arguments that are not the value of any option are returned
2833 as a list, associated with the empty list.
2834
2835 `getopt-long' throws an exception if:
2836 - it finds an unrecognized option in ARGS
2837 - a required option is omitted
2838 - an option that requires an argument doesn't get one
2839 - an option that doesn't accept an argument does get one (this can
2840 only happen using the long option `--opt=value' syntax)
2841 - an option predicate fails
2842
2843 So, for example:
2844
2845 (define grammar
2846 `((lockfile-dir (required? #t)
2847 (value #t)
2848 (single-char #\k)
2849 (predicate ,file-is-directory?))
2850 (verbose (required? #f)
2851 (single-char #\v)
2852 (value #f))
2853 (x-includes (single-char #\x))
2854 (rnet-server (single-char #\y)
2855 (predicate ,string?))))
2856
2857 (getopt-long '("my-prog" "-vk" "/tmp" "foo1" "--x-includes=/usr/include"
2858 "--rnet-server=lamprod" "--" "-fred" "foo2" "foo3")
2859 grammar)
2860 => ((() "foo1" "-fred" "foo2" "foo3")
2861 (rnet-server . "lamprod")
2862 (x-includes . "/usr/include")
2863 (lockfile-dir . "/tmp")
2864 (verbose . #t))
2865
2866 ** The (ice-9 getopt-gnu-style) module is obsolete; use (ice-9 getopt-long).
2867
2868 It will be removed in a few releases.
2869
2870 ** New syntax: lambda*
2871 ** New syntax: define*
2872 ** New syntax: define*-public
2873 ** New syntax: defmacro*
2874 ** New syntax: defmacro*-public
2875 Guile now supports optional arguments.
2876
2877 `lambda*', `define*', `define*-public', `defmacro*' and
2878 `defmacro*-public' are identical to the non-* versions except that
2879 they use an extended type of parameter list that has the following BNF
2880 syntax (parentheses are literal, square brackets indicate grouping,
2881 and `*', `+' and `?' have the usual meaning):
2882
2883 ext-param-list ::= ( [identifier]* [#&optional [ext-var-decl]+]?
2884 [#&key [ext-var-decl]+ [#&allow-other-keys]?]?
2885 [[#&rest identifier]|[. identifier]]? ) | [identifier]
2886
2887 ext-var-decl ::= identifier | ( identifier expression )
2888
2889 The semantics are best illustrated with the following documentation
2890 and examples for `lambda*':
2891
2892 lambda* args . body
2893 lambda extended for optional and keyword arguments
2894
2895 lambda* creates a procedure that takes optional arguments. These
2896 are specified by putting them inside brackets at the end of the
2897 paramater list, but before any dotted rest argument. For example,
2898 (lambda* (a b #&optional c d . e) '())
2899 creates a procedure with fixed arguments a and b, optional arguments c
2900 and d, and rest argument e. If the optional arguments are omitted
2901 in a call, the variables for them are unbound in the procedure. This
2902 can be checked with the bound? macro.
2903
2904 lambda* can also take keyword arguments. For example, a procedure
2905 defined like this:
2906 (lambda* (#&key xyzzy larch) '())
2907 can be called with any of the argument lists (#:xyzzy 11)
2908 (#:larch 13) (#:larch 42 #:xyzzy 19) (). Whichever arguments
2909 are given as keywords are bound to values.
2910
2911 Optional and keyword arguments can also be given default values
2912 which they take on when they are not present in a call, by giving a
2913 two-item list in place of an optional argument, for example in:
2914 (lambda* (foo #&optional (bar 42) #&key (baz 73)) (list foo bar baz))
2915 foo is a fixed argument, bar is an optional argument with default
2916 value 42, and baz is a keyword argument with default value 73.
2917 Default value expressions are not evaluated unless they are needed
2918 and until the procedure is called.
2919
2920 lambda* now supports two more special parameter list keywords.
2921
2922 lambda*-defined procedures now throw an error by default if a
2923 keyword other than one of those specified is found in the actual
2924 passed arguments. However, specifying #&allow-other-keys
2925 immediately after the kyword argument declarations restores the
2926 previous behavior of ignoring unknown keywords. lambda* also now
2927 guarantees that if the same keyword is passed more than once, the
2928 last one passed is the one that takes effect. For example,
2929 ((lambda* (#&key (heads 0) (tails 0)) (display (list heads tails)))
2930 #:heads 37 #:tails 42 #:heads 99)
2931 would result in (99 47) being displayed.
2932
2933 #&rest is also now provided as a synonym for the dotted syntax rest
2934 argument. The argument lists (a . b) and (a #&rest b) are equivalent in
2935 all respects to lambda*. This is provided for more similarity to DSSSL,
2936 MIT-Scheme and Kawa among others, as well as for refugees from other
2937 Lisp dialects.
2938
2939 Further documentation may be found in the optargs.scm file itself.
2940
2941 The optional argument module also exports the macros `let-optional',
2942 `let-optional*', `let-keywords', `let-keywords*' and `bound?'. These
2943 are not documented here because they may be removed in the future, but
2944 full documentation is still available in optargs.scm.
2945
2946 ** New syntax: and-let*
2947 Guile now supports the `and-let*' form, described in the draft SRFI-2.
2948
2949 Syntax: (land* (<clause> ...) <body> ...)
2950 Each <clause> should have one of the following forms:
2951 (<variable> <expression>)
2952 (<expression>)
2953 <bound-variable>
2954 Each <variable> or <bound-variable> should be an identifier. Each
2955 <expression> should be a valid expression. The <body> should be a
2956 possibly empty sequence of expressions, like the <body> of a
2957 lambda form.
2958
2959 Semantics: A LAND* expression is evaluated by evaluating the
2960 <expression> or <bound-variable> of each of the <clause>s from
2961 left to right. The value of the first <expression> or
2962 <bound-variable> that evaluates to a false value is returned; the
2963 remaining <expression>s and <bound-variable>s are not evaluated.
2964 The <body> forms are evaluated iff all the <expression>s and
2965 <bound-variable>s evaluate to true values.
2966
2967 The <expression>s and the <body> are evaluated in an environment
2968 binding each <variable> of the preceding (<variable> <expression>)
2969 clauses to the value of the <expression>. Later bindings
2970 shadow earlier bindings.
2971
2972 Guile's and-let* macro was contributed by Michael Livshin.
2973
2974 ** New sorting functions
2975
2976 *** New function: sorted? SEQUENCE LESS?
2977 Returns `#t' when the sequence argument is in non-decreasing order
2978 according to LESS? (that is, there is no adjacent pair `... x y
2979 ...' for which `(less? y x)').
2980
2981 Returns `#f' when the sequence contains at least one out-of-order
2982 pair. It is an error if the sequence is neither a list nor a
2983 vector.
2984
2985 *** New function: merge LIST1 LIST2 LESS?
2986 LIST1 and LIST2 are sorted lists.
2987 Returns the sorted list of all elements in LIST1 and LIST2.
2988
2989 Assume that the elements a and b1 in LIST1 and b2 in LIST2 are "equal"
2990 in the sense that (LESS? x y) --> #f for x, y in {a, b1, b2},
2991 and that a < b1 in LIST1. Then a < b1 < b2 in the result.
2992 (Here "<" should read "comes before".)
2993
2994 *** New procedure: merge! LIST1 LIST2 LESS?
2995 Merges two lists, re-using the pairs of LIST1 and LIST2 to build
2996 the result. If the code is compiled, and LESS? constructs no new
2997 pairs, no pairs at all will be allocated. The first pair of the
2998 result will be either the first pair of LIST1 or the first pair of
2999 LIST2.
3000
3001 *** New function: sort SEQUENCE LESS?
3002 Accepts either a list or a vector, and returns a new sequence
3003 which is sorted. The new sequence is the same type as the input.
3004 Always `(sorted? (sort sequence less?) less?)'. The original
3005 sequence is not altered in any way. The new sequence shares its
3006 elements with the old one; no elements are copied.
3007
3008 *** New procedure: sort! SEQUENCE LESS
3009 Returns its sorted result in the original boxes. No new storage is
3010 allocated at all. Proper usage: (set! slist (sort! slist <))
3011
3012 *** New function: stable-sort SEQUENCE LESS?
3013 Similar to `sort' but stable. That is, if "equal" elements are
3014 ordered a < b in the original sequence, they will have the same order
3015 in the result.
3016
3017 *** New function: stable-sort! SEQUENCE LESS?
3018 Similar to `sort!' but stable.
3019 Uses temporary storage when sorting vectors.
3020
3021 *** New functions: sort-list, sort-list!
3022 Added for compatibility with scsh.
3023
3024 ** New built-in random number support
3025
3026 *** New function: random N [STATE]
3027 Accepts a positive integer or real N and returns a number of the
3028 same type between zero (inclusive) and N (exclusive). The values
3029 returned have a uniform distribution.
3030
3031 The optional argument STATE must be of the type produced by
3032 `copy-random-state' or `seed->random-state'. It defaults to the value
3033 of the variable `*random-state*'. This object is used to maintain the
3034 state of the pseudo-random-number generator and is altered as a side
3035 effect of the `random' operation.
3036
3037 *** New variable: *random-state*
3038 Holds a data structure that encodes the internal state of the
3039 random-number generator that `random' uses by default. The nature
3040 of this data structure is implementation-dependent. It may be
3041 printed out and successfully read back in, but may or may not
3042 function correctly as a random-number state object in another
3043 implementation.
3044
3045 *** New function: copy-random-state [STATE]
3046 Returns a new object of type suitable for use as the value of the
3047 variable `*random-state*' and as a second argument to `random'.
3048 If argument STATE is given, a copy of it is returned. Otherwise a
3049 copy of `*random-state*' is returned.
3050
3051 *** New function: seed->random-state SEED
3052 Returns a new object of type suitable for use as the value of the
3053 variable `*random-state*' and as a second argument to `random'.
3054 SEED is a string or a number. A new state is generated and
3055 initialized using SEED.
3056
3057 *** New function: random:uniform [STATE]
3058 Returns an uniformly distributed inexact real random number in the
3059 range between 0 and 1.
3060
3061 *** New procedure: random:solid-sphere! VECT [STATE]
3062 Fills VECT with inexact real random numbers the sum of whose
3063 squares is less than 1.0. Thinking of VECT as coordinates in
3064 space of dimension N = `(vector-length VECT)', the coordinates are
3065 uniformly distributed within the unit N-shere. The sum of the
3066 squares of the numbers is returned. VECT can be either a vector
3067 or a uniform vector of doubles.
3068
3069 *** New procedure: random:hollow-sphere! VECT [STATE]
3070 Fills VECT with inexact real random numbers the sum of whose squares
3071 is equal to 1.0. Thinking of VECT as coordinates in space of
3072 dimension n = `(vector-length VECT)', the coordinates are uniformly
3073 distributed over the surface of the unit n-shere. VECT can be either
3074 a vector or a uniform vector of doubles.
3075
3076 *** New function: random:normal [STATE]
3077 Returns an inexact real in a normal distribution with mean 0 and
3078 standard deviation 1. For a normal distribution with mean M and
3079 standard deviation D use `(+ M (* D (random:normal)))'.
3080
3081 *** New procedure: random:normal-vector! VECT [STATE]
3082 Fills VECT with inexact real random numbers which are independent and
3083 standard normally distributed (i.e., with mean 0 and variance 1).
3084 VECT can be either a vector or a uniform vector of doubles.
3085
3086 *** New function: random:exp STATE
3087 Returns an inexact real in an exponential distribution with mean 1.
3088 For an exponential distribution with mean U use (* U (random:exp)).
3089
3090 ** The range of logand, logior, logxor, logtest, and logbit? have changed.
3091
3092 These functions now operate on numbers in the range of a C unsigned
3093 long.
3094
3095 These functions used to operate on numbers in the range of a C signed
3096 long; however, this seems inappropriate, because Guile integers don't
3097 overflow.
3098
3099 ** New function: make-guardian
3100 This is an implementation of guardians as described in
3101 R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in a
3102 Generation-Based Garbage Collector" ACM SIGPLAN Conference on
3103 Programming Language Design and Implementation, June 1993
3104 ftp://ftp.cs.indiana.edu/pub/scheme-repository/doc/pubs/guardians.ps.gz
3105
3106 ** New functions: delq1!, delv1!, delete1!
3107 These procedures behave similar to delq! and friends but delete only
3108 one object if at all.
3109
3110 ** New function: unread-string STRING PORT
3111 Unread STRING to PORT, that is, push it back onto the port so that
3112 next read operation will work on the pushed back characters.
3113
3114 ** unread-char can now be called multiple times
3115 If unread-char is called multiple times, the unread characters will be
3116 read again in last-in first-out order.
3117
3118 ** the procedures uniform-array-read! and uniform-array-write! now
3119 work on any kind of port, not just ports which are open on a file.
3120
3121 ** Now 'l' in a port mode requests line buffering.
3122
3123 ** The procedure truncate-file now works on string ports as well
3124 as file ports. If the size argument is omitted, the current
3125 file position is used.
3126
3127 ** new procedure: seek PORT/FDES OFFSET WHENCE
3128 The arguments are the same as for the old fseek procedure, but it
3129 works on string ports as well as random-access file ports.
3130
3131 ** the fseek procedure now works on string ports, since it has been
3132 redefined using seek.
3133
3134 ** the setvbuf procedure now uses a default size if mode is _IOFBF and
3135 size is not supplied.
3136
3137 ** the newline procedure no longer flushes the port if it's not
3138 line-buffered: previously it did if it was the current output port.
3139
3140 ** open-pipe and close-pipe are no longer primitive procedures, but
3141 an emulation can be obtained using `(use-modules (ice-9 popen))'.
3142
3143 ** the freopen procedure has been removed.
3144
3145 ** new procedure: drain-input PORT
3146 Drains PORT's read buffers (including any pushed-back characters)
3147 and returns the contents as a single string.
3148
3149 ** New function: map-in-order PROC LIST1 LIST2 ...
3150 Version of `map' which guarantees that the procedure is applied to the
3151 lists in serial order.
3152
3153 ** Renamed `serial-array-copy!' and `serial-array-map!' to
3154 `array-copy-in-order!' and `array-map-in-order!'. The old names are
3155 now obsolete and will go away in release 1.5.
3156
3157 ** New syntax: collect BODY1 ...
3158 Version of `begin' which returns a list of the results of the body
3159 forms instead of the result of the last body form. In contrast to
3160 `begin', `collect' allows an empty body.
3161
3162 ** New functions: read-history FILENAME, write-history FILENAME
3163 Read/write command line history from/to file. Returns #t on success
3164 and #f if an error occured.
3165
3166 ** `ls' and `lls' in module (ice-9 ls) now handle no arguments.
3167
3168 These procedures return a list of definitions available in the specified
3169 argument, a relative module reference. In the case of no argument,
3170 `(current-module)' is now consulted for definitions to return, instead
3171 of simply returning #f, the former behavior.
3172
3173 ** The #/ syntax for lists is no longer supported.
3174
3175 Earlier versions of Scheme accepted this syntax, but printed a
3176 warning.
3177
3178 ** Guile no longer consults the SCHEME_LOAD_PATH environment variable.
3179
3180 Instead, you should set GUILE_LOAD_PATH to tell Guile where to find
3181 modules.
3182
3183 * Changes to the gh_ interface
3184
3185 ** gh_scm2doubles
3186
3187 Now takes a second argument which is the result array. If this
3188 pointer is NULL, a new array is malloced (the old behaviour).
3189
3190 ** gh_chars2byvect, gh_shorts2svect, gh_floats2fvect, gh_scm2chars,
3191 gh_scm2shorts, gh_scm2longs, gh_scm2floats
3192
3193 New functions.
3194
3195 * Changes to the scm_ interface
3196
3197 ** Function: scm_make_named_hook (char* name, int n_args)
3198
3199 Creates a hook in the same way as make-hook above but also
3200 binds a variable named NAME to it.
3201
3202 This is the typical way of creating a hook from C code.
3203
3204 Currently, the variable is created in the "current" module. This
3205 might change when we get the new module system.
3206
3207 ** The smob interface
3208
3209 The interface for creating smobs has changed. For documentation, see
3210 data-rep.info (made from guile-core/doc/data-rep.texi).
3211
3212 *** Deprecated function: SCM scm_newsmob (scm_smobfuns *)
3213
3214 >>> This function will be removed in 1.3.4. <<<
3215
3216 It is replaced by:
3217
3218 *** Function: SCM scm_make_smob_type (const char *name, scm_sizet size)
3219 This function adds a new smob type, named NAME, with instance size
3220 SIZE to the system. The return value is a tag that is used in
3221 creating instances of the type. If SIZE is 0, then no memory will
3222 be allocated when instances of the smob are created, and nothing
3223 will be freed by the default free function.
3224
3225 *** Function: void scm_set_smob_mark (long tc, SCM (*mark) (SCM))
3226 This function sets the smob marking procedure for the smob type
3227 specified by the tag TC. TC is the tag returned by
3228 `scm_make_smob_type'.
3229
3230 *** Function: void scm_set_smob_free (long tc, SCM (*mark) (SCM))
3231 This function sets the smob freeing procedure for the smob type
3232 specified by the tag TC. TC is the tag returned by
3233 `scm_make_smob_type'.
3234
3235 *** Function: void scm_set_smob_print (tc, print)
3236
3237 - Function: void scm_set_smob_print (long tc,
3238 scm_sizet (*print) (SCM,
3239 SCM,
3240 scm_print_state *))
3241
3242 This function sets the smob printing procedure for the smob type
3243 specified by the tag TC. TC is the tag returned by
3244 `scm_make_smob_type'.
3245
3246 *** Function: void scm_set_smob_equalp (long tc, SCM (*equalp) (SCM, SCM))
3247 This function sets the smob equality-testing predicate for the
3248 smob type specified by the tag TC. TC is the tag returned by
3249 `scm_make_smob_type'.
3250
3251 *** Macro: void SCM_NEWSMOB (SCM var, long tc, void *data)
3252 Make VALUE contain a smob instance of the type with type code TC and
3253 smob data DATA. VALUE must be previously declared as C type `SCM'.
3254
3255 *** Macro: fn_returns SCM_RETURN_NEWSMOB (long tc, void *data)
3256 This macro expands to a block of code that creates a smob instance
3257 of the type with type code TC and smob data DATA, and returns that
3258 `SCM' value. It should be the last piece of code in a block.
3259
3260 ** The interfaces for using I/O ports and implementing port types
3261 (ptobs) have changed significantly. The new interface is based on
3262 shared access to buffers and a new set of ptob procedures.
3263
3264 *** scm_newptob has been removed
3265
3266 It is replaced by:
3267
3268 *** Function: SCM scm_make_port_type (type_name, fill_buffer, write_flush)
3269
3270 - Function: SCM scm_make_port_type (char *type_name,
3271 int (*fill_buffer) (SCM port),
3272 void (*write_flush) (SCM port));
3273
3274 Similarly to the new smob interface, there is a set of function
3275 setters by which the user can customize the behaviour of his port
3276 type. See ports.h (scm_set_port_XXX).
3277
3278 ** scm_strport_to_string: New function: creates a new string from
3279 a string port's buffer.
3280
3281 ** Plug in interface for random number generators
3282 The variable `scm_the_rng' in random.c contains a value and three
3283 function pointers which together define the current random number
3284 generator being used by the Scheme level interface and the random
3285 number library functions.
3286
3287 The user is free to replace the default generator with the generator
3288 of his own choice.
3289
3290 *** Variable: size_t scm_the_rng.rstate_size
3291 The size of the random state type used by the current RNG
3292 measured in chars.
3293
3294 *** Function: unsigned long scm_the_rng.random_bits (scm_rstate *STATE)
3295 Given the random STATE, return 32 random bits.
3296
3297 *** Function: void scm_the_rng.init_rstate (scm_rstate *STATE, chars *S, int N)
3298 Seed random state STATE using string S of length N.
3299
3300 *** Function: scm_rstate *scm_the_rng.copy_rstate (scm_rstate *STATE)
3301 Given random state STATE, return a malloced copy.
3302
3303 ** Default RNG
3304 The default RNG is the MWC (Multiply With Carry) random number
3305 generator described by George Marsaglia at the Department of
3306 Statistics and Supercomputer Computations Research Institute, The
3307 Florida State University (http://stat.fsu.edu/~geo).
3308
3309 It uses 64 bits, has a period of 4578426017172946943 (4.6e18), and
3310 passes all tests in the DIEHARD test suite
3311 (http://stat.fsu.edu/~geo/diehard.html). The generation of 32 bits
3312 costs one multiply and one add on platforms which either supports long
3313 longs (gcc does this on most systems) or have 64 bit longs. The cost
3314 is four multiply on other systems but this can be optimized by writing
3315 scm_i_uniform32 in assembler.
3316
3317 These functions are provided through the scm_the_rng interface for use
3318 by libguile and the application.
3319
3320 *** Function: unsigned long scm_i_uniform32 (scm_i_rstate *STATE)
3321 Given the random STATE, return 32 random bits.
3322 Don't use this function directly. Instead go through the plugin
3323 interface (see "Plug in interface" above).
3324
3325 *** Function: void scm_i_init_rstate (scm_i_rstate *STATE, char *SEED, int N)
3326 Initialize STATE using SEED of length N.
3327
3328 *** Function: scm_i_rstate *scm_i_copy_rstate (scm_i_rstate *STATE)
3329 Return a malloc:ed copy of STATE. This function can easily be re-used
3330 in the interfaces to other RNGs.
3331
3332 ** Random number library functions
3333 These functions use the current RNG through the scm_the_rng interface.
3334 It might be a good idea to use these functions from your C code so
3335 that only one random generator is used by all code in your program.
3336
3337 The default random state is stored in:
3338
3339 *** Variable: SCM scm_var_random_state
3340 Contains the vcell of the Scheme variable "*random-state*" which is
3341 used as default state by all random number functions in the Scheme
3342 level interface.
3343
3344 Example:
3345
3346 double x = scm_c_uniform01 (SCM_RSTATE (SCM_CDR (scm_var_random_state)));
3347
3348 *** Function: scm_rstate *scm_c_default_rstate (void)
3349 This is a convenience function which returns the value of
3350 scm_var_random_state. An error message is generated if this value
3351 isn't a random state.
3352
3353 *** Function: scm_rstate *scm_c_make_rstate (char *SEED, int LENGTH)
3354 Make a new random state from the string SEED of length LENGTH.
3355
3356 It is generally not a good idea to use multiple random states in a
3357 program. While subsequent random numbers generated from one random
3358 state are guaranteed to be reasonably independent, there is no such
3359 guarantee for numbers generated from different random states.
3360
3361 *** Macro: unsigned long scm_c_uniform32 (scm_rstate *STATE)
3362 Return 32 random bits.
3363
3364 *** Function: double scm_c_uniform01 (scm_rstate *STATE)
3365 Return a sample from the uniform(0,1) distribution.
3366
3367 *** Function: double scm_c_normal01 (scm_rstate *STATE)
3368 Return a sample from the normal(0,1) distribution.
3369
3370 *** Function: double scm_c_exp1 (scm_rstate *STATE)
3371 Return a sample from the exp(1) distribution.
3372
3373 *** Function: unsigned long scm_c_random (scm_rstate *STATE, unsigned long M)
3374 Return a sample from the discrete uniform(0,M) distribution.
3375
3376 *** Function: SCM scm_c_random_bignum (scm_rstate *STATE, SCM M)
3377 Return a sample from the discrete uniform(0,M) distribution.
3378 M must be a bignum object. The returned value may be an INUM.
3379
3380
3381 \f
3382 Changes in Guile 1.3 (released Monday, October 19, 1998):
3383
3384 * Changes to the distribution
3385
3386 ** We renamed the SCHEME_LOAD_PATH environment variable to GUILE_LOAD_PATH.
3387 To avoid conflicts, programs should name environment variables after
3388 themselves, except when there's a common practice establishing some
3389 other convention.
3390
3391 For now, Guile supports both GUILE_LOAD_PATH and SCHEME_LOAD_PATH,
3392 giving the former precedence, and printing a warning message if the
3393 latter is set. Guile 1.4 will not recognize SCHEME_LOAD_PATH at all.
3394
3395 ** The header files related to multi-byte characters have been removed.
3396 They were: libguile/extchrs.h and libguile/mbstrings.h. Any C code
3397 which referred to these explicitly will probably need to be rewritten,
3398 since the support for the variant string types has been removed; see
3399 below.
3400
3401 ** The header files append.h and sequences.h have been removed. These
3402 files implemented non-R4RS operations which would encourage
3403 non-portable programming style and less easy-to-read code.
3404
3405 * Changes to the stand-alone interpreter
3406
3407 ** New procedures have been added to implement a "batch mode":
3408
3409 *** Function: batch-mode?
3410
3411 Returns a boolean indicating whether the interpreter is in batch
3412 mode.
3413
3414 *** Function: set-batch-mode?! ARG
3415
3416 If ARG is true, switches the interpreter to batch mode. The `#f'
3417 case has not been implemented.
3418
3419 ** Guile now provides full command-line editing, when run interactively.
3420 To use this feature, you must have the readline library installed.
3421 The Guile build process will notice it, and automatically include
3422 support for it.
3423
3424 The readline library is available via anonymous FTP from any GNU
3425 mirror site; the canonical location is "ftp://prep.ai.mit.edu/pub/gnu".
3426
3427 ** the-last-stack is now a fluid.
3428
3429 * Changes to the procedure for linking libguile with your programs
3430
3431 ** You can now use the `guile-config' utility to build programs that use Guile.
3432
3433 Guile now includes a command-line utility called `guile-config', which
3434 can provide information about how to compile and link programs that
3435 use Guile.
3436
3437 *** `guile-config compile' prints any C compiler flags needed to use Guile.
3438 You should include this command's output on the command line you use
3439 to compile C or C++ code that #includes the Guile header files. It's
3440 usually just a `-I' flag to help the compiler find the Guile headers.
3441
3442
3443 *** `guile-config link' prints any linker flags necessary to link with Guile.
3444
3445 This command writes to its standard output a list of flags which you
3446 must pass to the linker to link your code against the Guile library.
3447 The flags include '-lguile' itself, any other libraries the Guile
3448 library depends upon, and any `-L' flags needed to help the linker
3449 find those libraries.
3450
3451 For example, here is a Makefile rule that builds a program named 'foo'
3452 from the object files ${FOO_OBJECTS}, and links them against Guile:
3453
3454 foo: ${FOO_OBJECTS}
3455 ${CC} ${CFLAGS} ${FOO_OBJECTS} `guile-config link` -o foo
3456
3457 Previous Guile releases recommended that you use autoconf to detect
3458 which of a predefined set of libraries were present on your system.
3459 It is more robust to use `guile-config', since it records exactly which
3460 libraries the installed Guile library requires.
3461
3462 This was originally called `build-guile', but was renamed to
3463 `guile-config' before Guile 1.3 was released, to be consistent with
3464 the analogous script for the GTK+ GUI toolkit, which is called
3465 `gtk-config'.
3466
3467
3468 ** Use the GUILE_FLAGS macro in your configure.in file to find Guile.
3469
3470 If you are using the GNU autoconf package to configure your program,
3471 you can use the GUILE_FLAGS autoconf macro to call `guile-config'
3472 (described above) and gather the necessary values for use in your
3473 Makefiles.
3474
3475 The GUILE_FLAGS macro expands to configure script code which runs the
3476 `guile-config' script, to find out where Guile's header files and
3477 libraries are installed. It sets two variables, marked for
3478 substitution, as by AC_SUBST.
3479
3480 GUILE_CFLAGS --- flags to pass to a C or C++ compiler to build
3481 code that uses Guile header files. This is almost always just a
3482 -I flag.
3483
3484 GUILE_LDFLAGS --- flags to pass to the linker to link a
3485 program against Guile. This includes `-lguile' for the Guile
3486 library itself, any libraries that Guile itself requires (like
3487 -lqthreads), and so on. It may also include a -L flag to tell the
3488 compiler where to find the libraries.
3489
3490 GUILE_FLAGS is defined in the file guile.m4, in the top-level
3491 directory of the Guile distribution. You can copy it into your
3492 package's aclocal.m4 file, and then use it in your configure.in file.
3493
3494 If you are using the `aclocal' program, distributed with GNU automake,
3495 to maintain your aclocal.m4 file, the Guile installation process
3496 installs guile.m4 where aclocal will find it. All you need to do is
3497 use GUILE_FLAGS in your configure.in file, and then run `aclocal';
3498 this will copy the definition of GUILE_FLAGS into your aclocal.m4
3499 file.
3500
3501
3502 * Changes to Scheme functions and syntax
3503
3504 ** Multi-byte strings have been removed, as have multi-byte and wide
3505 ports. We felt that these were the wrong approach to
3506 internationalization support.
3507
3508 ** New function: readline [PROMPT]
3509 Read a line from the terminal, and allow the user to edit it,
3510 prompting with PROMPT. READLINE provides a large set of Emacs-like
3511 editing commands, lets the user recall previously typed lines, and
3512 works on almost every kind of terminal, including dumb terminals.
3513
3514 READLINE assumes that the cursor is at the beginning of the line when
3515 it is invoked. Thus, you can't print a prompt yourself, and then call
3516 READLINE; you need to package up your prompt as a string, pass it to
3517 the function, and let READLINE print the prompt itself. This is
3518 because READLINE needs to know the prompt's screen width.
3519
3520 For Guile to provide this function, you must have the readline
3521 library, version 2.1 or later, installed on your system. Readline is
3522 available via anonymous FTP from prep.ai.mit.edu in pub/gnu, or from
3523 any GNU mirror site.
3524
3525 See also ADD-HISTORY function.
3526
3527 ** New function: add-history STRING
3528 Add STRING as the most recent line in the history used by the READLINE
3529 command. READLINE does not add lines to the history itself; you must
3530 call ADD-HISTORY to make previous input available to the user.
3531
3532 ** The behavior of the read-line function has changed.
3533
3534 This function now uses standard C library functions to read the line,
3535 for speed. This means that it doesn not respect the value of
3536 scm-line-incrementors; it assumes that lines are delimited with
3537 #\newline.
3538
3539 (Note that this is read-line, the function that reads a line of text
3540 from a port, not readline, the function that reads a line from a
3541 terminal, providing full editing capabilities.)
3542
3543 ** New module (ice-9 getopt-gnu-style): Parse command-line arguments.
3544
3545 This module provides some simple argument parsing. It exports one
3546 function:
3547
3548 Function: getopt-gnu-style ARG-LS
3549 Parse a list of program arguments into an alist of option
3550 descriptions.
3551
3552 Each item in the list of program arguments is examined to see if
3553 it meets the syntax of a GNU long-named option. An argument like
3554 `--MUMBLE' produces an element of the form (MUMBLE . #t) in the
3555 returned alist, where MUMBLE is a keyword object with the same
3556 name as the argument. An argument like `--MUMBLE=FROB' produces
3557 an element of the form (MUMBLE . FROB), where FROB is a string.
3558
3559 As a special case, the returned alist also contains a pair whose
3560 car is the symbol `rest'. The cdr of this pair is a list
3561 containing all the items in the argument list that are not options
3562 of the form mentioned above.
3563
3564 The argument `--' is treated specially: all items in the argument
3565 list appearing after such an argument are not examined, and are
3566 returned in the special `rest' list.
3567
3568 This function does not parse normal single-character switches.
3569 You will need to parse them out of the `rest' list yourself.
3570
3571 ** The read syntax for byte vectors and short vectors has changed.
3572
3573 Instead of #bytes(...), write #y(...).
3574
3575 Instead of #short(...), write #h(...).
3576
3577 This may seem nutty, but, like the other uniform vectors, byte vectors
3578 and short vectors want to have the same print and read syntax (and,
3579 more basic, want to have read syntax!). Changing the read syntax to
3580 use multiple characters after the hash sign breaks with the
3581 conventions used in R5RS and the conventions used for the other
3582 uniform vectors. It also introduces complexity in the current reader,
3583 both on the C and Scheme levels. (The Right solution is probably to
3584 change the syntax and prototypes for uniform vectors entirely.)
3585
3586
3587 ** The new module (ice-9 session) provides useful interactive functions.
3588
3589 *** New procedure: (apropos REGEXP OPTION ...)
3590
3591 Display a list of top-level variables whose names match REGEXP, and
3592 the modules they are imported from. Each OPTION should be one of the
3593 following symbols:
3594
3595 value --- Show the value of each matching variable.
3596 shadow --- Show bindings shadowed by subsequently imported modules.
3597 full --- Same as both `shadow' and `value'.
3598
3599 For example:
3600
3601 guile> (apropos "trace" 'full)
3602 debug: trace #<procedure trace args>
3603 debug: untrace #<procedure untrace args>
3604 the-scm-module: display-backtrace #<compiled-closure #<primitive-procedure gsubr-apply>>
3605 the-scm-module: before-backtrace-hook ()
3606 the-scm-module: backtrace #<primitive-procedure backtrace>
3607 the-scm-module: after-backtrace-hook ()
3608 the-scm-module: has-shown-backtrace-hint? #f
3609 guile>
3610
3611 ** There are new functions and syntax for working with macros.
3612
3613 Guile implements macros as a special object type. Any variable whose
3614 top-level binding is a macro object acts as a macro. The macro object
3615 specifies how the expression should be transformed before evaluation.
3616
3617 *** Macro objects now print in a reasonable way, resembling procedures.
3618
3619 *** New function: (macro? OBJ)
3620 True iff OBJ is a macro object.
3621
3622 *** New function: (primitive-macro? OBJ)
3623 Like (macro? OBJ), but true only if OBJ is one of the Guile primitive
3624 macro transformers, implemented in eval.c rather than Scheme code.
3625
3626 Why do we have this function?
3627 - For symmetry with procedure? and primitive-procedure?,
3628 - to allow custom print procedures to tell whether a macro is
3629 primitive, and display it differently, and
3630 - to allow compilers and user-written evaluators to distinguish
3631 builtin special forms from user-defined ones, which could be
3632 compiled.
3633
3634 *** New function: (macro-type OBJ)
3635 Return a value indicating what kind of macro OBJ is. Possible return
3636 values are:
3637
3638 The symbol `syntax' --- a macro created by procedure->syntax.
3639 The symbol `macro' --- a macro created by procedure->macro.
3640 The symbol `macro!' --- a macro created by procedure->memoizing-macro.
3641 The boolean #f --- if OBJ is not a macro object.
3642
3643 *** New function: (macro-name MACRO)
3644 Return the name of the macro object MACRO's procedure, as returned by
3645 procedure-name.
3646
3647 *** New function: (macro-transformer MACRO)
3648 Return the transformer procedure for MACRO.
3649
3650 *** New syntax: (use-syntax MODULE ... TRANSFORMER)
3651
3652 Specify a new macro expander to use in the current module. Each
3653 MODULE is a module name, with the same meaning as in the `use-modules'
3654 form; each named module's exported bindings are added to the current
3655 top-level environment. TRANSFORMER is an expression evaluated in the
3656 resulting environment which must yield a procedure to use as the
3657 module's eval transformer: every expression evaluated in this module
3658 is passed to this function, and the result passed to the Guile
3659 interpreter.
3660
3661 *** macro-eval! is removed. Use local-eval instead.
3662
3663 ** Some magic has been added to the printer to better handle user
3664 written printing routines (like record printers, closure printers).
3665
3666 The problem is that these user written routines must have access to
3667 the current `print-state' to be able to handle fancy things like
3668 detection of circular references. These print-states have to be
3669 passed to the builtin printing routines (display, write, etc) to
3670 properly continue the print chain.
3671
3672 We didn't want to change all existing print code so that it
3673 explicitly passes thru a print state in addition to a port. Instead,
3674 we extented the possible values that the builtin printing routines
3675 accept as a `port'. In addition to a normal port, they now also take
3676 a pair of a normal port and a print-state. Printing will go to the
3677 port and the print-state will be used to control the detection of
3678 circular references, etc. If the builtin function does not care for a
3679 print-state, it is simply ignored.
3680
3681 User written callbacks are now called with such a pair as their
3682 `port', but because every function now accepts this pair as a PORT
3683 argument, you don't have to worry about that. In fact, it is probably
3684 safest to not check for these pairs.
3685
3686 However, it is sometimes necessary to continue a print chain on a
3687 different port, for example to get a intermediate string
3688 representation of the printed value, mangle that string somehow, and
3689 then to finally print the mangled string. Use the new function
3690
3691 inherit-print-state OLD-PORT NEW-PORT
3692
3693 for this. It constructs a new `port' that prints to NEW-PORT but
3694 inherits the print-state of OLD-PORT.
3695
3696 ** struct-vtable-offset renamed to vtable-offset-user
3697
3698 ** New constants: vtable-index-layout, vtable-index-vtable, vtable-index-printer
3699
3700 ** There is now a third optional argument to make-vtable-vtable
3701 (and fourth to make-struct) when constructing new types (vtables).
3702 This argument initializes field vtable-index-printer of the vtable.
3703
3704 ** The detection of circular references has been extended to structs.
3705 That is, a structure that -- in the process of being printed -- prints
3706 itself does not lead to infinite recursion.
3707
3708 ** There is now some basic support for fluids. Please read
3709 "libguile/fluid.h" to find out more. It is accessible from Scheme with
3710 the following functions and macros:
3711
3712 Function: make-fluid
3713
3714 Create a new fluid object. Fluids are not special variables or
3715 some other extension to the semantics of Scheme, but rather
3716 ordinary Scheme objects. You can store them into variables (that
3717 are still lexically scoped, of course) or into any other place you
3718 like. Every fluid has a initial value of `#f'.
3719
3720 Function: fluid? OBJ
3721
3722 Test whether OBJ is a fluid.
3723
3724 Function: fluid-ref FLUID
3725 Function: fluid-set! FLUID VAL
3726
3727 Access/modify the fluid FLUID. Modifications are only visible
3728 within the current dynamic root (that includes threads).
3729
3730 Function: with-fluids* FLUIDS VALUES THUNK
3731
3732 FLUIDS is a list of fluids and VALUES a corresponding list of
3733 values for these fluids. Before THUNK gets called the values are
3734 installed in the fluids and the old values of the fluids are
3735 saved in the VALUES list. When the flow of control leaves THUNK
3736 or reenters it, the values get swapped again. You might think of
3737 this as a `safe-fluid-excursion'. Note that the VALUES list is
3738 modified by `with-fluids*'.
3739
3740 Macro: with-fluids ((FLUID VALUE) ...) FORM ...
3741
3742 The same as `with-fluids*' but with a different syntax. It looks
3743 just like `let', but both FLUID and VALUE are evaluated. Remember,
3744 fluids are not special variables but ordinary objects. FLUID
3745 should evaluate to a fluid.
3746
3747 ** Changes to system call interfaces:
3748
3749 *** close-port, close-input-port and close-output-port now return a
3750 boolean instead of an `unspecified' object. #t means that the port
3751 was successfully closed, while #f means it was already closed. It is
3752 also now possible for these procedures to raise an exception if an
3753 error occurs (some errors from write can be delayed until close.)
3754
3755 *** the first argument to chmod, fcntl, ftell and fseek can now be a
3756 file descriptor.
3757
3758 *** the third argument to fcntl is now optional.
3759
3760 *** the first argument to chown can now be a file descriptor or a port.
3761
3762 *** the argument to stat can now be a port.
3763
3764 *** The following new procedures have been added (most use scsh
3765 interfaces):
3766
3767 *** procedure: close PORT/FD
3768 Similar to close-port (*note close-port: Closing Ports.), but also
3769 works on file descriptors. A side effect of closing a file
3770 descriptor is that any ports using that file descriptor are moved
3771 to a different file descriptor and have their revealed counts set
3772 to zero.
3773
3774 *** procedure: port->fdes PORT
3775 Returns the integer file descriptor underlying PORT. As a side
3776 effect the revealed count of PORT is incremented.
3777
3778 *** procedure: fdes->ports FDES
3779 Returns a list of existing ports which have FDES as an underlying
3780 file descriptor, without changing their revealed counts.
3781
3782 *** procedure: fdes->inport FDES
3783 Returns an existing input port which has FDES as its underlying
3784 file descriptor, if one exists, and increments its revealed count.
3785 Otherwise, returns a new input port with a revealed count of 1.
3786
3787 *** procedure: fdes->outport FDES
3788 Returns an existing output port which has FDES as its underlying
3789 file descriptor, if one exists, and increments its revealed count.
3790 Otherwise, returns a new output port with a revealed count of 1.
3791
3792 The next group of procedures perform a `dup2' system call, if NEWFD
3793 (an integer) is supplied, otherwise a `dup'. The file descriptor to be
3794 duplicated can be supplied as an integer or contained in a port. The
3795 type of value returned varies depending on which procedure is used.
3796
3797 All procedures also have the side effect when performing `dup2' that
3798 any ports using NEWFD are moved to a different file descriptor and have
3799 their revealed counts set to zero.
3800
3801 *** procedure: dup->fdes PORT/FD [NEWFD]
3802 Returns an integer file descriptor.
3803
3804 *** procedure: dup->inport PORT/FD [NEWFD]
3805 Returns a new input port using the new file descriptor.
3806
3807 *** procedure: dup->outport PORT/FD [NEWFD]
3808 Returns a new output port using the new file descriptor.
3809
3810 *** procedure: dup PORT/FD [NEWFD]
3811 Returns a new port if PORT/FD is a port, with the same mode as the
3812 supplied port, otherwise returns an integer file descriptor.
3813
3814 *** procedure: dup->port PORT/FD MODE [NEWFD]
3815 Returns a new port using the new file descriptor. MODE supplies a
3816 mode string for the port (*note open-file: File Ports.).
3817
3818 *** procedure: setenv NAME VALUE
3819 Modifies the environment of the current process, which is also the
3820 default environment inherited by child processes.
3821
3822 If VALUE is `#f', then NAME is removed from the environment.
3823 Otherwise, the string NAME=VALUE is added to the environment,
3824 replacing any existing string with name matching NAME.
3825
3826 The return value is unspecified.
3827
3828 *** procedure: truncate-file OBJ SIZE
3829 Truncates the file referred to by OBJ to at most SIZE bytes. OBJ
3830 can be a string containing a file name or an integer file
3831 descriptor or port open for output on the file. The underlying
3832 system calls are `truncate' and `ftruncate'.
3833
3834 The return value is unspecified.
3835
3836 *** procedure: setvbuf PORT MODE [SIZE]
3837 Set the buffering mode for PORT. MODE can be:
3838 `_IONBF'
3839 non-buffered
3840
3841 `_IOLBF'
3842 line buffered
3843
3844 `_IOFBF'
3845 block buffered, using a newly allocated buffer of SIZE bytes.
3846 However if SIZE is zero or unspecified, the port will be made
3847 non-buffered.
3848
3849 This procedure should not be used after I/O has been performed with
3850 the port.
3851
3852 Ports are usually block buffered by default, with a default buffer
3853 size. Procedures e.g., *Note open-file: File Ports, which accept a
3854 mode string allow `0' to be added to request an unbuffered port.
3855
3856 *** procedure: fsync PORT/FD
3857 Copies any unwritten data for the specified output file descriptor
3858 to disk. If PORT/FD is a port, its buffer is flushed before the
3859 underlying file descriptor is fsync'd. The return value is
3860 unspecified.
3861
3862 *** procedure: open-fdes PATH FLAGS [MODES]
3863 Similar to `open' but returns a file descriptor instead of a port.
3864
3865 *** procedure: execle PATH ENV [ARG] ...
3866 Similar to `execl', but the environment of the new process is
3867 specified by ENV, which must be a list of strings as returned by
3868 the `environ' procedure.
3869
3870 This procedure is currently implemented using the `execve' system
3871 call, but we call it `execle' because of its Scheme calling
3872 interface.
3873
3874 *** procedure: strerror ERRNO
3875 Returns the Unix error message corresponding to ERRNO, an integer.
3876
3877 *** procedure: primitive-exit [STATUS]
3878 Terminate the current process without unwinding the Scheme stack.
3879 This is would typically be useful after a fork. The exit status
3880 is STATUS if supplied, otherwise zero.
3881
3882 *** procedure: times
3883 Returns an object with information about real and processor time.
3884 The following procedures accept such an object as an argument and
3885 return a selected component:
3886
3887 `tms:clock'
3888 The current real time, expressed as time units relative to an
3889 arbitrary base.
3890
3891 `tms:utime'
3892 The CPU time units used by the calling process.
3893
3894 `tms:stime'
3895 The CPU time units used by the system on behalf of the
3896 calling process.
3897
3898 `tms:cutime'
3899 The CPU time units used by terminated child processes of the
3900 calling process, whose status has been collected (e.g., using
3901 `waitpid').
3902
3903 `tms:cstime'
3904 Similarly, the CPU times units used by the system on behalf of
3905 terminated child processes.
3906
3907 ** Removed: list-length
3908 ** Removed: list-append, list-append!
3909 ** Removed: list-reverse, list-reverse!
3910
3911 ** array-map renamed to array-map!
3912
3913 ** serial-array-map renamed to serial-array-map!
3914
3915 ** catch doesn't take #f as first argument any longer
3916
3917 Previously, it was possible to pass #f instead of a key to `catch'.
3918 That would cause `catch' to pass a jump buffer object to the procedure
3919 passed as second argument. The procedure could then use this jump
3920 buffer objekt as an argument to throw.
3921
3922 This mechanism has been removed since its utility doesn't motivate the
3923 extra complexity it introduces.
3924
3925 ** The `#/' notation for lists now provokes a warning message from Guile.
3926 This syntax will be removed from Guile in the near future.
3927
3928 To disable the warning message, set the GUILE_HUSH environment
3929 variable to any non-empty value.
3930
3931 ** The newline character now prints as `#\newline', following the
3932 normal Scheme notation, not `#\nl'.
3933
3934 * Changes to the gh_ interface
3935
3936 ** The gh_enter function now takes care of loading the Guile startup files.
3937 gh_enter works by calling scm_boot_guile; see the remarks below.
3938
3939 ** Function: void gh_write (SCM x)
3940
3941 Write the printed representation of the scheme object x to the current
3942 output port. Corresponds to the scheme level `write'.
3943
3944 ** gh_list_length renamed to gh_length.
3945
3946 ** vector handling routines
3947
3948 Several major changes. In particular, gh_vector() now resembles
3949 (vector ...) (with a caveat -- see manual), and gh_make_vector() now
3950 exists and behaves like (make-vector ...). gh_vset() and gh_vref()
3951 have been renamed gh_vector_set_x() and gh_vector_ref(). Some missing
3952 vector-related gh_ functions have been implemented.
3953
3954 ** pair and list routines
3955
3956 Implemented several of the R4RS pair and list functions that were
3957 missing.
3958
3959 ** gh_scm2doubles, gh_doubles2scm, gh_doubles2dvect
3960
3961 New function. Converts double arrays back and forth between Scheme
3962 and C.
3963
3964 * Changes to the scm_ interface
3965
3966 ** The function scm_boot_guile now takes care of loading the startup files.
3967
3968 Guile's primary initialization function, scm_boot_guile, now takes
3969 care of loading `boot-9.scm', in the `ice-9' module, to initialize
3970 Guile, define the module system, and put together some standard
3971 bindings. It also loads `init.scm', which is intended to hold
3972 site-specific initialization code.
3973
3974 Since Guile cannot operate properly until boot-9.scm is loaded, there
3975 is no reason to separate loading boot-9.scm from Guile's other
3976 initialization processes.
3977
3978 This job used to be done by scm_compile_shell_switches, which didn't
3979 make much sense; in particular, it meant that people using Guile for
3980 non-shell-like applications had to jump through hoops to get Guile
3981 initialized properly.
3982
3983 ** The function scm_compile_shell_switches no longer loads the startup files.
3984 Now, Guile always loads the startup files, whenever it is initialized;
3985 see the notes above for scm_boot_guile and scm_load_startup_files.
3986
3987 ** Function: scm_load_startup_files
3988 This new function takes care of loading Guile's initialization file
3989 (`boot-9.scm'), and the site initialization file, `init.scm'. Since
3990 this is always called by the Guile initialization process, it's
3991 probably not too useful to call this yourself, but it's there anyway.
3992
3993 ** The semantics of smob marking have changed slightly.
3994
3995 The smob marking function (the `mark' member of the scm_smobfuns
3996 structure) is no longer responsible for setting the mark bit on the
3997 smob. The generic smob handling code in the garbage collector will
3998 set this bit. The mark function need only ensure that any other
3999 objects the smob refers to get marked.
4000
4001 Note that this change means that the smob's GC8MARK bit is typically
4002 already set upon entry to the mark function. Thus, marking functions
4003 which look like this:
4004
4005 {
4006 if (SCM_GC8MARKP (ptr))
4007 return SCM_BOOL_F;
4008 SCM_SETGC8MARK (ptr);
4009 ... mark objects to which the smob refers ...
4010 }
4011
4012 are now incorrect, since they will return early, and fail to mark any
4013 other objects the smob refers to. Some code in the Guile library used
4014 to work this way.
4015
4016 ** The semantics of the I/O port functions in scm_ptobfuns have changed.
4017
4018 If you have implemented your own I/O port type, by writing the
4019 functions required by the scm_ptobfuns and then calling scm_newptob,
4020 you will need to change your functions slightly.
4021
4022 The functions in a scm_ptobfuns structure now expect the port itself
4023 as their argument; they used to expect the `stream' member of the
4024 port's scm_port_table structure. This allows functions in an
4025 scm_ptobfuns structure to easily access the port's cell (and any flags
4026 it its CAR), and the port's scm_port_table structure.
4027
4028 Guile now passes the I/O port itself as the `port' argument in the
4029 following scm_ptobfuns functions:
4030
4031 int (*free) (SCM port);
4032 int (*fputc) (int, SCM port);
4033 int (*fputs) (char *, SCM port);
4034 scm_sizet (*fwrite) SCM_P ((char *ptr,
4035 scm_sizet size,
4036 scm_sizet nitems,
4037 SCM port));
4038 int (*fflush) (SCM port);
4039 int (*fgetc) (SCM port);
4040 int (*fclose) (SCM port);
4041
4042 The interfaces to the `mark', `print', `equalp', and `fgets' methods
4043 are unchanged.
4044
4045 If you have existing code which defines its own port types, it is easy
4046 to convert your code to the new interface; simply apply SCM_STREAM to
4047 the port argument to yield the value you code used to expect.
4048
4049 Note that since both the port and the stream have the same type in the
4050 C code --- they are both SCM values --- the C compiler will not remind
4051 you if you forget to update your scm_ptobfuns functions.
4052
4053
4054 ** Function: int scm_internal_select (int fds,
4055 SELECT_TYPE *rfds,
4056 SELECT_TYPE *wfds,
4057 SELECT_TYPE *efds,
4058 struct timeval *timeout);
4059
4060 This is a replacement for the `select' function provided by the OS.
4061 It enables I/O blocking and sleeping to happen for one cooperative
4062 thread without blocking other threads. It also avoids busy-loops in
4063 these situations. It is intended that all I/O blocking and sleeping
4064 will finally go through this function. Currently, this function is
4065 only available on systems providing `gettimeofday' and `select'.
4066
4067 ** Function: SCM scm_internal_stack_catch (SCM tag,
4068 scm_catch_body_t body,
4069 void *body_data,
4070 scm_catch_handler_t handler,
4071 void *handler_data)
4072
4073 A new sibling to the other two C level `catch' functions
4074 scm_internal_catch and scm_internal_lazy_catch. Use it if you want
4075 the stack to be saved automatically into the variable `the-last-stack'
4076 (scm_the_last_stack_var) on error. This is necessary if you want to
4077 use advanced error reporting, such as calling scm_display_error and
4078 scm_display_backtrace. (They both take a stack object as argument.)
4079
4080 ** Function: SCM scm_spawn_thread (scm_catch_body_t body,
4081 void *body_data,
4082 scm_catch_handler_t handler,
4083 void *handler_data)
4084
4085 Spawns a new thread. It does a job similar to
4086 scm_call_with_new_thread but takes arguments more suitable when
4087 spawning threads from application C code.
4088
4089 ** The hook scm_error_callback has been removed. It was originally
4090 intended as a way for the user to install his own error handler. But
4091 that method works badly since it intervenes between throw and catch,
4092 thereby changing the semantics of expressions like (catch #t ...).
4093 The correct way to do it is to use one of the C level catch functions
4094 in throw.c: scm_internal_catch/lazy_catch/stack_catch.
4095
4096 ** Removed functions:
4097
4098 scm_obj_length, scm_list_length, scm_list_append, scm_list_append_x,
4099 scm_list_reverse, scm_list_reverse_x
4100
4101 ** New macros: SCM_LISTn where n is one of the integers 0-9.
4102
4103 These can be used for pretty list creation from C. The idea is taken
4104 from Erick Gallesio's STk.
4105
4106 ** scm_array_map renamed to scm_array_map_x
4107
4108 ** mbstrings are now removed
4109
4110 This means that the type codes scm_tc7_mb_string and
4111 scm_tc7_mb_substring has been removed.
4112
4113 ** scm_gen_putc, scm_gen_puts, scm_gen_write, and scm_gen_getc have changed.
4114
4115 Since we no longer support multi-byte strings, these I/O functions
4116 have been simplified, and renamed. Here are their old names, and
4117 their new names and arguments:
4118
4119 scm_gen_putc -> void scm_putc (int c, SCM port);
4120 scm_gen_puts -> void scm_puts (char *s, SCM port);
4121 scm_gen_write -> void scm_lfwrite (char *ptr, scm_sizet size, SCM port);
4122 scm_gen_getc -> void scm_getc (SCM port);
4123
4124
4125 ** The macros SCM_TYP7D and SCM_TYP7SD has been removed.
4126
4127 ** The macro SCM_TYP7S has taken the role of the old SCM_TYP7D
4128
4129 SCM_TYP7S now masks away the bit which distinguishes substrings from
4130 strings.
4131
4132 ** scm_catch_body_t: Backward incompatible change!
4133
4134 Body functions to scm_internal_catch and friends do not any longer
4135 take a second argument. This is because it is no longer possible to
4136 pass a #f arg to catch.
4137
4138 ** Calls to scm_protect_object and scm_unprotect now nest properly.
4139
4140 The function scm_protect_object protects its argument from being freed
4141 by the garbage collector. scm_unprotect_object removes that
4142 protection.
4143
4144 These functions now nest properly. That is, for every object O, there
4145 is a counter which scm_protect_object(O) increments and
4146 scm_unprotect_object(O) decrements, if the counter is greater than
4147 zero. Every object's counter is zero when it is first created. If an
4148 object's counter is greater than zero, the garbage collector will not
4149 reclaim its storage.
4150
4151 This allows you to use scm_protect_object in your code without
4152 worrying that some other function you call will call
4153 scm_unprotect_object, and allow it to be freed. Assuming that the
4154 functions you call are well-behaved, and unprotect only those objects
4155 they protect, you can follow the same rule and have confidence that
4156 objects will be freed only at appropriate times.
4157
4158 \f
4159 Changes in Guile 1.2 (released Tuesday, June 24 1997):
4160
4161 * Changes to the distribution
4162
4163 ** Nightly snapshots are now available from ftp.red-bean.com.
4164 The old server, ftp.cyclic.com, has been relinquished to its rightful
4165 owner.
4166
4167 Nightly snapshots of the Guile development sources are now available via
4168 anonymous FTP from ftp.red-bean.com, as /pub/guile/guile-snap.tar.gz.
4169
4170 Via the web, that's: ftp://ftp.red-bean.com/pub/guile/guile-snap.tar.gz
4171 For getit, that's: ftp.red-bean.com:/pub/guile/guile-snap.tar.gz
4172
4173 ** To run Guile without installing it, the procedure has changed a bit.
4174
4175 If you used a separate build directory to compile Guile, you'll need
4176 to include the build directory in SCHEME_LOAD_PATH, as well as the
4177 source directory. See the `INSTALL' file for examples.
4178
4179 * Changes to the procedure for linking libguile with your programs
4180
4181 ** The standard Guile load path for Scheme code now includes
4182 $(datadir)/guile (usually /usr/local/share/guile). This means that
4183 you can install your own Scheme files there, and Guile will find them.
4184 (Previous versions of Guile only checked a directory whose name
4185 contained the Guile version number, so you had to re-install or move
4186 your Scheme sources each time you installed a fresh version of Guile.)
4187
4188 The load path also includes $(datadir)/guile/site; we recommend
4189 putting individual Scheme files there. If you want to install a
4190 package with multiple source files, create a directory for them under
4191 $(datadir)/guile.
4192
4193 ** Guile 1.2 will now use the Rx regular expression library, if it is
4194 installed on your system. When you are linking libguile into your own
4195 programs, this means you will have to link against -lguile, -lqt (if
4196 you configured Guile with thread support), and -lrx.
4197
4198 If you are using autoconf to generate configuration scripts for your
4199 application, the following lines should suffice to add the appropriate
4200 libraries to your link command:
4201
4202 ### Find Rx, quickthreads and libguile.
4203 AC_CHECK_LIB(rx, main)
4204 AC_CHECK_LIB(qt, main)
4205 AC_CHECK_LIB(guile, scm_shell)
4206
4207 The Guile 1.2 distribution does not contain sources for the Rx
4208 library, as Guile 1.0 did. If you want to use Rx, you'll need to
4209 retrieve it from a GNU FTP site and install it separately.
4210
4211 * Changes to Scheme functions and syntax
4212
4213 ** The dynamic linking features of Guile are now enabled by default.
4214 You can disable them by giving the `--disable-dynamic-linking' option
4215 to configure.
4216
4217 (dynamic-link FILENAME)
4218
4219 Find the object file denoted by FILENAME (a string) and link it
4220 into the running Guile application. When everything works out,
4221 return a Scheme object suitable for representing the linked object
4222 file. Otherwise an error is thrown. How object files are
4223 searched is system dependent.
4224
4225 (dynamic-object? VAL)
4226
4227 Determine whether VAL represents a dynamically linked object file.
4228
4229 (dynamic-unlink DYNOBJ)
4230
4231 Unlink the indicated object file from the application. DYNOBJ
4232 should be one of the values returned by `dynamic-link'.
4233
4234 (dynamic-func FUNCTION DYNOBJ)
4235
4236 Search the C function indicated by FUNCTION (a string or symbol)
4237 in DYNOBJ and return some Scheme object that can later be used
4238 with `dynamic-call' to actually call this function. Right now,
4239 these Scheme objects are formed by casting the address of the
4240 function to `long' and converting this number to its Scheme
4241 representation.
4242
4243 (dynamic-call FUNCTION DYNOBJ)
4244
4245 Call the C function indicated by FUNCTION and DYNOBJ. The
4246 function is passed no arguments and its return value is ignored.
4247 When FUNCTION is something returned by `dynamic-func', call that
4248 function and ignore DYNOBJ. When FUNCTION is a string (or symbol,
4249 etc.), look it up in DYNOBJ; this is equivalent to
4250
4251 (dynamic-call (dynamic-func FUNCTION DYNOBJ) #f)
4252
4253 Interrupts are deferred while the C function is executing (with
4254 SCM_DEFER_INTS/SCM_ALLOW_INTS).
4255
4256 (dynamic-args-call FUNCTION DYNOBJ ARGS)
4257
4258 Call the C function indicated by FUNCTION and DYNOBJ, but pass it
4259 some arguments and return its return value. The C function is
4260 expected to take two arguments and return an `int', just like
4261 `main':
4262
4263 int c_func (int argc, char **argv);
4264
4265 ARGS must be a list of strings and is converted into an array of
4266 `char *'. The array is passed in ARGV and its size in ARGC. The
4267 return value is converted to a Scheme number and returned from the
4268 call to `dynamic-args-call'.
4269
4270 When dynamic linking is disabled or not supported on your system,
4271 the above functions throw errors, but they are still available.
4272
4273 Here is a small example that works on GNU/Linux:
4274
4275 (define libc-obj (dynamic-link "libc.so"))
4276 (dynamic-args-call 'rand libc-obj '())
4277
4278 See the file `libguile/DYNAMIC-LINKING' for additional comments.
4279
4280 ** The #/ syntax for module names is depreciated, and will be removed
4281 in a future version of Guile. Instead of
4282
4283 #/foo/bar/baz
4284
4285 instead write
4286
4287 (foo bar baz)
4288
4289 The latter syntax is more consistent with existing Lisp practice.
4290
4291 ** Guile now does fancier printing of structures. Structures are the
4292 underlying implementation for records, which in turn are used to
4293 implement modules, so all of these object now print differently and in
4294 a more informative way.
4295
4296 The Scheme printer will examine the builtin variable *struct-printer*
4297 whenever it needs to print a structure object. When this variable is
4298 not `#f' it is deemed to be a procedure and will be applied to the
4299 structure object and the output port. When *struct-printer* is `#f'
4300 or the procedure return `#f' the structure object will be printed in
4301 the boring #<struct 80458270> form.
4302
4303 This hook is used by some routines in ice-9/boot-9.scm to implement
4304 type specific printing routines. Please read the comments there about
4305 "printing structs".
4306
4307 One of the more specific uses of structs are records. The printing
4308 procedure that could be passed to MAKE-RECORD-TYPE is now actually
4309 called. It should behave like a *struct-printer* procedure (described
4310 above).
4311
4312 ** Guile now supports a new R4RS-compliant syntax for keywords. A
4313 token of the form #:NAME, where NAME has the same syntax as a Scheme
4314 symbol, is the external representation of the keyword named NAME.
4315 Keyword objects print using this syntax as well, so values containing
4316 keyword objects can be read back into Guile. When used in an
4317 expression, keywords are self-quoting objects.
4318
4319 Guile suports this read syntax, and uses this print syntax, regardless
4320 of the current setting of the `keyword' read option. The `keyword'
4321 read option only controls whether Guile recognizes the `:NAME' syntax,
4322 which is incompatible with R4RS. (R4RS says such token represent
4323 symbols.)
4324
4325 ** Guile has regular expression support again. Guile 1.0 included
4326 functions for matching regular expressions, based on the Rx library.
4327 In Guile 1.1, the Guile/Rx interface was removed to simplify the
4328 distribution, and thus Guile had no regular expression support. Guile
4329 1.2 again supports the most commonly used functions, and supports all
4330 of SCSH's regular expression functions.
4331
4332 If your system does not include a POSIX regular expression library,
4333 and you have not linked Guile with a third-party regexp library such as
4334 Rx, these functions will not be available. You can tell whether your
4335 Guile installation includes regular expression support by checking
4336 whether the `*features*' list includes the `regex' symbol.
4337
4338 *** regexp functions
4339
4340 By default, Guile supports POSIX extended regular expressions. That
4341 means that the characters `(', `)', `+' and `?' are special, and must
4342 be escaped if you wish to match the literal characters.
4343
4344 This regular expression interface was modeled after that implemented
4345 by SCSH, the Scheme Shell. It is intended to be upwardly compatible
4346 with SCSH regular expressions.
4347
4348 **** Function: string-match PATTERN STR [START]
4349 Compile the string PATTERN into a regular expression and compare
4350 it with STR. The optional numeric argument START specifies the
4351 position of STR at which to begin matching.
4352
4353 `string-match' returns a "match structure" which describes what,
4354 if anything, was matched by the regular expression. *Note Match
4355 Structures::. If STR does not match PATTERN at all,
4356 `string-match' returns `#f'.
4357
4358 Each time `string-match' is called, it must compile its PATTERN
4359 argument into a regular expression structure. This operation is
4360 expensive, which makes `string-match' inefficient if the same regular
4361 expression is used several times (for example, in a loop). For better
4362 performance, you can compile a regular expression in advance and then
4363 match strings against the compiled regexp.
4364
4365 **** Function: make-regexp STR [FLAGS]
4366 Compile the regular expression described by STR, and return the
4367 compiled regexp structure. If STR does not describe a legal
4368 regular expression, `make-regexp' throws a
4369 `regular-expression-syntax' error.
4370
4371 FLAGS may be the bitwise-or of one or more of the following:
4372
4373 **** Constant: regexp/extended
4374 Use POSIX Extended Regular Expression syntax when interpreting
4375 STR. If not set, POSIX Basic Regular Expression syntax is used.
4376 If the FLAGS argument is omitted, we assume regexp/extended.
4377
4378 **** Constant: regexp/icase
4379 Do not differentiate case. Subsequent searches using the
4380 returned regular expression will be case insensitive.
4381
4382 **** Constant: regexp/newline
4383 Match-any-character operators don't match a newline.
4384
4385 A non-matching list ([^...]) not containing a newline matches a
4386 newline.
4387
4388 Match-beginning-of-line operator (^) matches the empty string
4389 immediately after a newline, regardless of whether the FLAGS
4390 passed to regexp-exec contain regexp/notbol.
4391
4392 Match-end-of-line operator ($) matches the empty string
4393 immediately before a newline, regardless of whether the FLAGS
4394 passed to regexp-exec contain regexp/noteol.
4395
4396 **** Function: regexp-exec REGEXP STR [START [FLAGS]]
4397 Match the compiled regular expression REGEXP against `str'. If
4398 the optional integer START argument is provided, begin matching
4399 from that position in the string. Return a match structure
4400 describing the results of the match, or `#f' if no match could be
4401 found.
4402
4403 FLAGS may be the bitwise-or of one or more of the following:
4404
4405 **** Constant: regexp/notbol
4406 The match-beginning-of-line operator always fails to match (but
4407 see the compilation flag regexp/newline above) This flag may be
4408 used when different portions of a string are passed to
4409 regexp-exec and the beginning of the string should not be
4410 interpreted as the beginning of the line.
4411
4412 **** Constant: regexp/noteol
4413 The match-end-of-line operator always fails to match (but see the
4414 compilation flag regexp/newline above)
4415
4416 **** Function: regexp? OBJ
4417 Return `#t' if OBJ is a compiled regular expression, or `#f'
4418 otherwise.
4419
4420 Regular expressions are commonly used to find patterns in one string
4421 and replace them with the contents of another string.
4422
4423 **** Function: regexp-substitute PORT MATCH [ITEM...]
4424 Write to the output port PORT selected contents of the match
4425 structure MATCH. Each ITEM specifies what should be written, and
4426 may be one of the following arguments:
4427
4428 * A string. String arguments are written out verbatim.
4429
4430 * An integer. The submatch with that number is written.
4431
4432 * The symbol `pre'. The portion of the matched string preceding
4433 the regexp match is written.
4434
4435 * The symbol `post'. The portion of the matched string
4436 following the regexp match is written.
4437
4438 PORT may be `#f', in which case nothing is written; instead,
4439 `regexp-substitute' constructs a string from the specified ITEMs
4440 and returns that.
4441
4442 **** Function: regexp-substitute/global PORT REGEXP TARGET [ITEM...]
4443 Similar to `regexp-substitute', but can be used to perform global
4444 substitutions on STR. Instead of taking a match structure as an
4445 argument, `regexp-substitute/global' takes two string arguments: a
4446 REGEXP string describing a regular expression, and a TARGET string
4447 which should be matched against this regular expression.
4448
4449 Each ITEM behaves as in REGEXP-SUBSTITUTE, with the following
4450 exceptions:
4451
4452 * A function may be supplied. When this function is called, it
4453 will be passed one argument: a match structure for a given
4454 regular expression match. It should return a string to be
4455 written out to PORT.
4456
4457 * The `post' symbol causes `regexp-substitute/global' to recurse
4458 on the unmatched portion of STR. This *must* be supplied in
4459 order to perform global search-and-replace on STR; if it is
4460 not present among the ITEMs, then `regexp-substitute/global'
4461 will return after processing a single match.
4462
4463 *** Match Structures
4464
4465 A "match structure" is the object returned by `string-match' and
4466 `regexp-exec'. It describes which portion of a string, if any, matched
4467 the given regular expression. Match structures include: a reference to
4468 the string that was checked for matches; the starting and ending
4469 positions of the regexp match; and, if the regexp included any
4470 parenthesized subexpressions, the starting and ending positions of each
4471 submatch.
4472
4473 In each of the regexp match functions described below, the `match'
4474 argument must be a match structure returned by a previous call to
4475 `string-match' or `regexp-exec'. Most of these functions return some
4476 information about the original target string that was matched against a
4477 regular expression; we will call that string TARGET for easy reference.
4478
4479 **** Function: regexp-match? OBJ
4480 Return `#t' if OBJ is a match structure returned by a previous
4481 call to `regexp-exec', or `#f' otherwise.
4482
4483 **** Function: match:substring MATCH [N]
4484 Return the portion of TARGET matched by subexpression number N.
4485 Submatch 0 (the default) represents the entire regexp match. If
4486 the regular expression as a whole matched, but the subexpression
4487 number N did not match, return `#f'.
4488
4489 **** Function: match:start MATCH [N]
4490 Return the starting position of submatch number N.
4491
4492 **** Function: match:end MATCH [N]
4493 Return the ending position of submatch number N.
4494
4495 **** Function: match:prefix MATCH
4496 Return the unmatched portion of TARGET preceding the regexp match.
4497
4498 **** Function: match:suffix MATCH
4499 Return the unmatched portion of TARGET following the regexp match.
4500
4501 **** Function: match:count MATCH
4502 Return the number of parenthesized subexpressions from MATCH.
4503 Note that the entire regular expression match itself counts as a
4504 subexpression, and failed submatches are included in the count.
4505
4506 **** Function: match:string MATCH
4507 Return the original TARGET string.
4508
4509 *** Backslash Escapes
4510
4511 Sometimes you will want a regexp to match characters like `*' or `$'
4512 exactly. For example, to check whether a particular string represents
4513 a menu entry from an Info node, it would be useful to match it against
4514 a regexp like `^* [^:]*::'. However, this won't work; because the
4515 asterisk is a metacharacter, it won't match the `*' at the beginning of
4516 the string. In this case, we want to make the first asterisk un-magic.
4517
4518 You can do this by preceding the metacharacter with a backslash
4519 character `\'. (This is also called "quoting" the metacharacter, and
4520 is known as a "backslash escape".) When Guile sees a backslash in a
4521 regular expression, it considers the following glyph to be an ordinary
4522 character, no matter what special meaning it would ordinarily have.
4523 Therefore, we can make the above example work by changing the regexp to
4524 `^\* [^:]*::'. The `\*' sequence tells the regular expression engine
4525 to match only a single asterisk in the target string.
4526
4527 Since the backslash is itself a metacharacter, you may force a
4528 regexp to match a backslash in the target string by preceding the
4529 backslash with itself. For example, to find variable references in a
4530 TeX program, you might want to find occurrences of the string `\let\'
4531 followed by any number of alphabetic characters. The regular expression
4532 `\\let\\[A-Za-z]*' would do this: the double backslashes in the regexp
4533 each match a single backslash in the target string.
4534
4535 **** Function: regexp-quote STR
4536 Quote each special character found in STR with a backslash, and
4537 return the resulting string.
4538
4539 *Very important:* Using backslash escapes in Guile source code (as
4540 in Emacs Lisp or C) can be tricky, because the backslash character has
4541 special meaning for the Guile reader. For example, if Guile encounters
4542 the character sequence `\n' in the middle of a string while processing
4543 Scheme code, it replaces those characters with a newline character.
4544 Similarly, the character sequence `\t' is replaced by a horizontal tab.
4545 Several of these "escape sequences" are processed by the Guile reader
4546 before your code is executed. Unrecognized escape sequences are
4547 ignored: if the characters `\*' appear in a string, they will be
4548 translated to the single character `*'.
4549
4550 This translation is obviously undesirable for regular expressions,
4551 since we want to be able to include backslashes in a string in order to
4552 escape regexp metacharacters. Therefore, to make sure that a backslash
4553 is preserved in a string in your Guile program, you must use *two*
4554 consecutive backslashes:
4555
4556 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
4557
4558 The string in this example is preprocessed by the Guile reader before
4559 any code is executed. The resulting argument to `make-regexp' is the
4560 string `^\* [^:]*', which is what we really want.
4561
4562 This also means that in order to write a regular expression that
4563 matches a single backslash character, the regular expression string in
4564 the source code must include *four* backslashes. Each consecutive pair
4565 of backslashes gets translated by the Guile reader to a single
4566 backslash, and the resulting double-backslash is interpreted by the
4567 regexp engine as matching a single backslash character. Hence:
4568
4569 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
4570
4571 The reason for the unwieldiness of this syntax is historical. Both
4572 regular expression pattern matchers and Unix string processing systems
4573 have traditionally used backslashes with the special meanings described
4574 above. The POSIX regular expression specification and ANSI C standard
4575 both require these semantics. Attempting to abandon either convention
4576 would cause other kinds of compatibility problems, possibly more severe
4577 ones. Therefore, without extending the Scheme reader to support
4578 strings with different quoting conventions (an ungainly and confusing
4579 extension when implemented in other languages), we must adhere to this
4580 cumbersome escape syntax.
4581
4582 * Changes to the gh_ interface
4583
4584 * Changes to the scm_ interface
4585
4586 * Changes to system call interfaces:
4587
4588 ** The value returned by `raise' is now unspecified. It throws an exception
4589 if an error occurs.
4590
4591 *** A new procedure `sigaction' can be used to install signal handlers
4592
4593 (sigaction signum [action] [flags])
4594
4595 signum is the signal number, which can be specified using the value
4596 of SIGINT etc.
4597
4598 If action is omitted, sigaction returns a pair: the CAR is the current
4599 signal hander, which will be either an integer with the value SIG_DFL
4600 (default action) or SIG_IGN (ignore), or the Scheme procedure which
4601 handles the signal, or #f if a non-Scheme procedure handles the
4602 signal. The CDR contains the current sigaction flags for the handler.
4603
4604 If action is provided, it is installed as the new handler for signum.
4605 action can be a Scheme procedure taking one argument, or the value of
4606 SIG_DFL (default action) or SIG_IGN (ignore), or #f to restore
4607 whatever signal handler was installed before sigaction was first used.
4608 Flags can optionally be specified for the new handler (SA_RESTART is
4609 always used if the system provides it, so need not be specified.) The
4610 return value is a pair with information about the old handler as
4611 described above.
4612
4613 This interface does not provide access to the "signal blocking"
4614 facility. Maybe this is not needed, since the thread support may
4615 provide solutions to the problem of consistent access to data
4616 structures.
4617
4618 *** A new procedure `flush-all-ports' is equivalent to running
4619 `force-output' on every port open for output.
4620
4621 ** Guile now provides information on how it was built, via the new
4622 global variable, %guile-build-info. This variable records the values
4623 of the standard GNU makefile directory variables as an assocation
4624 list, mapping variable names (symbols) onto directory paths (strings).
4625 For example, to find out where the Guile link libraries were
4626 installed, you can say:
4627
4628 guile -c "(display (assq-ref %guile-build-info 'libdir)) (newline)"
4629
4630
4631 * Changes to the scm_ interface
4632
4633 ** The new function scm_handle_by_message_noexit is just like the
4634 existing scm_handle_by_message function, except that it doesn't call
4635 exit to terminate the process. Instead, it prints a message and just
4636 returns #f. This might be a more appropriate catch-all handler for
4637 new dynamic roots and threads.
4638
4639 \f
4640 Changes in Guile 1.1 (released Friday, May 16 1997):
4641
4642 * Changes to the distribution.
4643
4644 The Guile 1.0 distribution has been split up into several smaller
4645 pieces:
4646 guile-core --- the Guile interpreter itself.
4647 guile-tcltk --- the interface between the Guile interpreter and
4648 Tcl/Tk; Tcl is an interpreter for a stringy language, and Tk
4649 is a toolkit for building graphical user interfaces.
4650 guile-rgx-ctax --- the interface between Guile and the Rx regular
4651 expression matcher, and the translator for the Ctax
4652 programming language. These are packaged together because the
4653 Ctax translator uses Rx to parse Ctax source code.
4654
4655 This NEWS file describes the changes made to guile-core since the 1.0
4656 release.
4657
4658 We no longer distribute the documentation, since it was either out of
4659 date, or incomplete. As soon as we have current documentation, we
4660 will distribute it.
4661
4662
4663
4664 * Changes to the stand-alone interpreter
4665
4666 ** guile now accepts command-line arguments compatible with SCSH, Olin
4667 Shivers' Scheme Shell.
4668
4669 In general, arguments are evaluated from left to right, but there are
4670 exceptions. The following switches stop argument processing, and
4671 stash all remaining command-line arguments as the value returned by
4672 the (command-line) function.
4673 -s SCRIPT load Scheme source code from FILE, and exit
4674 -c EXPR evalute Scheme expression EXPR, and exit
4675 -- stop scanning arguments; run interactively
4676
4677 The switches below are processed as they are encountered.
4678 -l FILE load Scheme source code from FILE
4679 -e FUNCTION after reading script, apply FUNCTION to
4680 command line arguments
4681 -ds do -s script at this point
4682 --emacs enable Emacs protocol (experimental)
4683 -h, --help display this help and exit
4684 -v, --version display version information and exit
4685 \ read arguments from following script lines
4686
4687 So, for example, here is a Guile script named `ekko' (thanks, Olin)
4688 which re-implements the traditional "echo" command:
4689
4690 #!/usr/local/bin/guile -s
4691 !#
4692 (define (main args)
4693 (map (lambda (arg) (display arg) (display " "))
4694 (cdr args))
4695 (newline))
4696
4697 (main (command-line))
4698
4699 Suppose we invoke this script as follows:
4700
4701 ekko a speckled gecko
4702
4703 Through the magic of Unix script processing (triggered by the `#!'
4704 token at the top of the file), /usr/local/bin/guile receives the
4705 following list of command-line arguments:
4706
4707 ("-s" "./ekko" "a" "speckled" "gecko")
4708
4709 Unix inserts the name of the script after the argument specified on
4710 the first line of the file (in this case, "-s"), and then follows that
4711 with the arguments given to the script. Guile loads the script, which
4712 defines the `main' function, and then applies it to the list of
4713 remaining command-line arguments, ("a" "speckled" "gecko").
4714
4715 In Unix, the first line of a script file must take the following form:
4716
4717 #!INTERPRETER ARGUMENT
4718
4719 where INTERPRETER is the absolute filename of the interpreter
4720 executable, and ARGUMENT is a single command-line argument to pass to
4721 the interpreter.
4722
4723 You may only pass one argument to the interpreter, and its length is
4724 limited. These restrictions can be annoying to work around, so Guile
4725 provides a general mechanism (borrowed from, and compatible with,
4726 SCSH) for circumventing them.
4727
4728 If the ARGUMENT in a Guile script is a single backslash character,
4729 `\', Guile will open the script file, parse arguments from its second
4730 and subsequent lines, and replace the `\' with them. So, for example,
4731 here is another implementation of the `ekko' script:
4732
4733 #!/usr/local/bin/guile \
4734 -e main -s
4735 !#
4736 (define (main args)
4737 (for-each (lambda (arg) (display arg) (display " "))
4738 (cdr args))
4739 (newline))
4740
4741 If the user invokes this script as follows:
4742
4743 ekko a speckled gecko
4744
4745 Unix expands this into
4746
4747 /usr/local/bin/guile \ ekko a speckled gecko
4748
4749 When Guile sees the `\' argument, it replaces it with the arguments
4750 read from the second line of the script, producing:
4751
4752 /usr/local/bin/guile -e main -s ekko a speckled gecko
4753
4754 This tells Guile to load the `ekko' script, and apply the function
4755 `main' to the argument list ("a" "speckled" "gecko").
4756
4757 Here is how Guile parses the command-line arguments:
4758 - Each space character terminates an argument. This means that two
4759 spaces in a row introduce an empty-string argument.
4760 - The tab character is not permitted (unless you quote it with the
4761 backslash character, as described below), to avoid confusion.
4762 - The newline character terminates the sequence of arguments, and will
4763 also terminate a final non-empty argument. (However, a newline
4764 following a space will not introduce a final empty-string argument;
4765 it only terminates the argument list.)
4766 - The backslash character is the escape character. It escapes
4767 backslash, space, tab, and newline. The ANSI C escape sequences
4768 like \n and \t are also supported. These produce argument
4769 constituents; the two-character combination \n doesn't act like a
4770 terminating newline. The escape sequence \NNN for exactly three
4771 octal digits reads as the character whose ASCII code is NNN. As
4772 above, characters produced this way are argument constituents.
4773 Backslash followed by other characters is not allowed.
4774
4775 * Changes to the procedure for linking libguile with your programs
4776
4777 ** Guile now builds and installs a shared guile library, if your
4778 system support shared libraries. (It still builds a static library on
4779 all systems.) Guile automatically detects whether your system
4780 supports shared libraries. To prevent Guile from buildisg shared
4781 libraries, pass the `--disable-shared' flag to the configure script.
4782
4783 Guile takes longer to compile when it builds shared libraries, because
4784 it must compile every file twice --- once to produce position-
4785 independent object code, and once to produce normal object code.
4786
4787 ** The libthreads library has been merged into libguile.
4788
4789 To link a program against Guile, you now need only link against
4790 -lguile and -lqt; -lthreads is no longer needed. If you are using
4791 autoconf to generate configuration scripts for your application, the
4792 following lines should suffice to add the appropriate libraries to
4793 your link command:
4794
4795 ### Find quickthreads and libguile.
4796 AC_CHECK_LIB(qt, main)
4797 AC_CHECK_LIB(guile, scm_shell)
4798
4799 * Changes to Scheme functions
4800
4801 ** Guile Scheme's special syntax for keyword objects is now optional,
4802 and disabled by default.
4803
4804 The syntax variation from R4RS made it difficult to port some
4805 interesting packages to Guile. The routines which accepted keyword
4806 arguments (mostly in the module system) have been modified to also
4807 accept symbols whose names begin with `:'.
4808
4809 To change the keyword syntax, you must first import the (ice-9 debug)
4810 module:
4811 (use-modules (ice-9 debug))
4812
4813 Then you can enable the keyword syntax as follows:
4814 (read-set! keywords 'prefix)
4815
4816 To disable keyword syntax, do this:
4817 (read-set! keywords #f)
4818
4819 ** Many more primitive functions accept shared substrings as
4820 arguments. In the past, these functions required normal, mutable
4821 strings as arguments, although they never made use of this
4822 restriction.
4823
4824 ** The uniform array functions now operate on byte vectors. These
4825 functions are `array-fill!', `serial-array-copy!', `array-copy!',
4826 `serial-array-map', `array-map', `array-for-each', and
4827 `array-index-map!'.
4828
4829 ** The new functions `trace' and `untrace' implement simple debugging
4830 support for Scheme functions.
4831
4832 The `trace' function accepts any number of procedures as arguments,
4833 and tells the Guile interpreter to display each procedure's name and
4834 arguments each time the procedure is invoked. When invoked with no
4835 arguments, `trace' returns the list of procedures currently being
4836 traced.
4837
4838 The `untrace' function accepts any number of procedures as arguments,
4839 and tells the Guile interpreter not to trace them any more. When
4840 invoked with no arguments, `untrace' untraces all curretly traced
4841 procedures.
4842
4843 The tracing in Guile has an advantage over most other systems: we
4844 don't create new procedure objects, but mark the procedure objects
4845 themselves. This means that anonymous and internal procedures can be
4846 traced.
4847
4848 ** The function `assert-repl-prompt' has been renamed to
4849 `set-repl-prompt!'. It takes one argument, PROMPT.
4850 - If PROMPT is #f, the Guile read-eval-print loop will not prompt.
4851 - If PROMPT is a string, we use it as a prompt.
4852 - If PROMPT is a procedure accepting no arguments, we call it, and
4853 display the result as a prompt.
4854 - Otherwise, we display "> ".
4855
4856 ** The new function `eval-string' reads Scheme expressions from a
4857 string and evaluates them, returning the value of the last expression
4858 in the string. If the string contains no expressions, it returns an
4859 unspecified value.
4860
4861 ** The new function `thunk?' returns true iff its argument is a
4862 procedure of zero arguments.
4863
4864 ** `defined?' is now a builtin function, instead of syntax. This
4865 means that its argument should be quoted. It returns #t iff its
4866 argument is bound in the current module.
4867
4868 ** The new syntax `use-modules' allows you to add new modules to your
4869 environment without re-typing a complete `define-module' form. It
4870 accepts any number of module names as arguments, and imports their
4871 public bindings into the current module.
4872
4873 ** The new function (module-defined? NAME MODULE) returns true iff
4874 NAME, a symbol, is defined in MODULE, a module object.
4875
4876 ** The new function `builtin-bindings' creates and returns a hash
4877 table containing copies of all the root module's bindings.
4878
4879 ** The new function `builtin-weak-bindings' does the same as
4880 `builtin-bindings', but creates a doubly-weak hash table.
4881
4882 ** The `equal?' function now considers variable objects to be
4883 equivalent if they have the same name and the same value.
4884
4885 ** The new function `command-line' returns the command-line arguments
4886 given to Guile, as a list of strings.
4887
4888 When using guile as a script interpreter, `command-line' returns the
4889 script's arguments; those processed by the interpreter (like `-s' or
4890 `-c') are omitted. (In other words, you get the normal, expected
4891 behavior.) Any application that uses scm_shell to process its
4892 command-line arguments gets this behavior as well.
4893
4894 ** The new function `load-user-init' looks for a file called `.guile'
4895 in the user's home directory, and loads it if it exists. This is
4896 mostly for use by the code generated by scm_compile_shell_switches,
4897 but we thought it might also be useful in other circumstances.
4898
4899 ** The new function `log10' returns the base-10 logarithm of its
4900 argument.
4901
4902 ** Changes to I/O functions
4903
4904 *** The functions `read', `primitive-load', `read-and-eval!', and
4905 `primitive-load-path' no longer take optional arguments controlling
4906 case insensitivity and a `#' parser.
4907
4908 Case sensitivity is now controlled by a read option called
4909 `case-insensitive'. The user can add new `#' syntaxes with the
4910 `read-hash-extend' function (see below).
4911
4912 *** The new function `read-hash-extend' allows the user to change the
4913 syntax of Guile Scheme in a somewhat controlled way.
4914
4915 (read-hash-extend CHAR PROC)
4916 When parsing S-expressions, if we read a `#' character followed by
4917 the character CHAR, use PROC to parse an object from the stream.
4918 If PROC is #f, remove any parsing procedure registered for CHAR.
4919
4920 The reader applies PROC to two arguments: CHAR and an input port.
4921
4922 *** The new functions read-delimited and read-delimited! provide a
4923 general mechanism for doing delimited input on streams.
4924
4925 (read-delimited DELIMS [PORT HANDLE-DELIM])
4926 Read until we encounter one of the characters in DELIMS (a string),
4927 or end-of-file. PORT is the input port to read from; it defaults to
4928 the current input port. The HANDLE-DELIM parameter determines how
4929 the terminating character is handled; it should be one of the
4930 following symbols:
4931
4932 'trim omit delimiter from result
4933 'peek leave delimiter character in input stream
4934 'concat append delimiter character to returned value
4935 'split return a pair: (RESULT . TERMINATOR)
4936
4937 HANDLE-DELIM defaults to 'peek.
4938
4939 (read-delimited! DELIMS BUF [PORT HANDLE-DELIM START END])
4940 A side-effecting variant of `read-delimited'.
4941
4942 The data is written into the string BUF at the indices in the
4943 half-open interval [START, END); the default interval is the whole
4944 string: START = 0 and END = (string-length BUF). The values of
4945 START and END must specify a well-defined interval in BUF, i.e.
4946 0 <= START <= END <= (string-length BUF).
4947
4948 It returns NBYTES, the number of bytes read. If the buffer filled
4949 up without a delimiter character being found, it returns #f. If the
4950 port is at EOF when the read starts, it returns the EOF object.
4951
4952 If an integer is returned (i.e., the read is successfully terminated
4953 by reading a delimiter character), then the HANDLE-DELIM parameter
4954 determines how to handle the terminating character. It is described
4955 above, and defaults to 'peek.
4956
4957 (The descriptions of these functions were borrowed from the SCSH
4958 manual, by Olin Shivers and Brian Carlstrom.)
4959
4960 *** The `%read-delimited!' function is the primitive used to implement
4961 `read-delimited' and `read-delimited!'.
4962
4963 (%read-delimited! DELIMS BUF GOBBLE? [PORT START END])
4964
4965 This returns a pair of values: (TERMINATOR . NUM-READ).
4966 - TERMINATOR describes why the read was terminated. If it is a
4967 character or the eof object, then that is the value that terminated
4968 the read. If it is #f, the function filled the buffer without finding
4969 a delimiting character.
4970 - NUM-READ is the number of characters read into BUF.
4971
4972 If the read is successfully terminated by reading a delimiter
4973 character, then the gobble? parameter determines what to do with the
4974 terminating character. If true, the character is removed from the
4975 input stream; if false, the character is left in the input stream
4976 where a subsequent read operation will retrieve it. In either case,
4977 the character is also the first value returned by the procedure call.
4978
4979 (The descriptions of this function was borrowed from the SCSH manual,
4980 by Olin Shivers and Brian Carlstrom.)
4981
4982 *** The `read-line' and `read-line!' functions have changed; they now
4983 trim the terminator by default; previously they appended it to the
4984 returned string. For the old behavior, use (read-line PORT 'concat).
4985
4986 *** The functions `uniform-array-read!' and `uniform-array-write!' now
4987 take new optional START and END arguments, specifying the region of
4988 the array to read and write.
4989
4990 *** The `ungetc-char-ready?' function has been removed. We feel it's
4991 inappropriate for an interface to expose implementation details this
4992 way.
4993
4994 ** Changes to the Unix library and system call interface
4995
4996 *** The new fcntl function provides access to the Unix `fcntl' system
4997 call.
4998
4999 (fcntl PORT COMMAND VALUE)
5000 Apply COMMAND to PORT's file descriptor, with VALUE as an argument.
5001 Values for COMMAND are:
5002
5003 F_DUPFD duplicate a file descriptor
5004 F_GETFD read the descriptor's close-on-exec flag
5005 F_SETFD set the descriptor's close-on-exec flag to VALUE
5006 F_GETFL read the descriptor's flags, as set on open
5007 F_SETFL set the descriptor's flags, as set on open to VALUE
5008 F_GETOWN return the process ID of a socket's owner, for SIGIO
5009 F_SETOWN set the process that owns a socket to VALUE, for SIGIO
5010 FD_CLOEXEC not sure what this is
5011
5012 For details, see the documentation for the fcntl system call.
5013
5014 *** The arguments to `select' have changed, for compatibility with
5015 SCSH. The TIMEOUT parameter may now be non-integral, yielding the
5016 expected behavior. The MILLISECONDS parameter has been changed to
5017 MICROSECONDS, to more closely resemble the underlying system call.
5018 The RVEC, WVEC, and EVEC arguments can now be vectors; the type of the
5019 corresponding return set will be the same.
5020
5021 *** The arguments to the `mknod' system call have changed. They are
5022 now:
5023
5024 (mknod PATH TYPE PERMS DEV)
5025 Create a new file (`node') in the file system. PATH is the name of
5026 the file to create. TYPE is the kind of file to create; it should
5027 be 'fifo, 'block-special, or 'char-special. PERMS specifies the
5028 permission bits to give the newly created file. If TYPE is
5029 'block-special or 'char-special, DEV specifies which device the
5030 special file refers to; its interpretation depends on the kind of
5031 special file being created.
5032
5033 *** The `fork' function has been renamed to `primitive-fork', to avoid
5034 clashing with various SCSH forks.
5035
5036 *** The `recv' and `recvfrom' functions have been renamed to `recv!'
5037 and `recvfrom!'. They no longer accept a size for a second argument;
5038 you must pass a string to hold the received value. They no longer
5039 return the buffer. Instead, `recv' returns the length of the message
5040 received, and `recvfrom' returns a pair containing the packet's length
5041 and originating address.
5042
5043 *** The file descriptor datatype has been removed, as have the
5044 `read-fd', `write-fd', `close', `lseek', and `dup' functions.
5045 We plan to replace these functions with a SCSH-compatible interface.
5046
5047 *** The `create' function has been removed; it's just a special case
5048 of `open'.
5049
5050 *** There are new functions to break down process termination status
5051 values. In the descriptions below, STATUS is a value returned by
5052 `waitpid'.
5053
5054 (status:exit-val STATUS)
5055 If the child process exited normally, this function returns the exit
5056 code for the child process (i.e., the value passed to exit, or
5057 returned from main). If the child process did not exit normally,
5058 this function returns #f.
5059
5060 (status:stop-sig STATUS)
5061 If the child process was suspended by a signal, this function
5062 returns the signal that suspended the child. Otherwise, it returns
5063 #f.
5064
5065 (status:term-sig STATUS)
5066 If the child process terminated abnormally, this function returns
5067 the signal that terminated the child. Otherwise, this function
5068 returns false.
5069
5070 POSIX promises that exactly one of these functions will return true on
5071 a valid STATUS value.
5072
5073 These functions are compatible with SCSH.
5074
5075 *** There are new accessors and setters for the broken-out time vectors
5076 returned by `localtime', `gmtime', and that ilk. They are:
5077
5078 Component Accessor Setter
5079 ========================= ============ ============
5080 seconds tm:sec set-tm:sec
5081 minutes tm:min set-tm:min
5082 hours tm:hour set-tm:hour
5083 day of the month tm:mday set-tm:mday
5084 month tm:mon set-tm:mon
5085 year tm:year set-tm:year
5086 day of the week tm:wday set-tm:wday
5087 day in the year tm:yday set-tm:yday
5088 daylight saving time tm:isdst set-tm:isdst
5089 GMT offset, seconds tm:gmtoff set-tm:gmtoff
5090 name of time zone tm:zone set-tm:zone
5091
5092 *** There are new accessors for the vectors returned by `uname',
5093 describing the host system:
5094
5095 Component Accessor
5096 ============================================== ================
5097 name of the operating system implementation utsname:sysname
5098 network name of this machine utsname:nodename
5099 release level of the operating system utsname:release
5100 version level of the operating system utsname:version
5101 machine hardware platform utsname:machine
5102
5103 *** There are new accessors for the vectors returned by `getpw',
5104 `getpwnam', `getpwuid', and `getpwent', describing entries from the
5105 system's user database:
5106
5107 Component Accessor
5108 ====================== =================
5109 user name passwd:name
5110 user password passwd:passwd
5111 user id passwd:uid
5112 group id passwd:gid
5113 real name passwd:gecos
5114 home directory passwd:dir
5115 shell program passwd:shell
5116
5117 *** There are new accessors for the vectors returned by `getgr',
5118 `getgrnam', `getgrgid', and `getgrent', describing entries from the
5119 system's group database:
5120
5121 Component Accessor
5122 ======================= ============
5123 group name group:name
5124 group password group:passwd
5125 group id group:gid
5126 group members group:mem
5127
5128 *** There are new accessors for the vectors returned by `gethost',
5129 `gethostbyaddr', `gethostbyname', and `gethostent', describing
5130 internet hosts:
5131
5132 Component Accessor
5133 ========================= ===============
5134 official name of host hostent:name
5135 alias list hostent:aliases
5136 host address type hostent:addrtype
5137 length of address hostent:length
5138 list of addresses hostent:addr-list
5139
5140 *** There are new accessors for the vectors returned by `getnet',
5141 `getnetbyaddr', `getnetbyname', and `getnetent', describing internet
5142 networks:
5143
5144 Component Accessor
5145 ========================= ===============
5146 official name of net netent:name
5147 alias list netent:aliases
5148 net number type netent:addrtype
5149 net number netent:net
5150
5151 *** There are new accessors for the vectors returned by `getproto',
5152 `getprotobyname', `getprotobynumber', and `getprotoent', describing
5153 internet protocols:
5154
5155 Component Accessor
5156 ========================= ===============
5157 official protocol name protoent:name
5158 alias list protoent:aliases
5159 protocol number protoent:proto
5160
5161 *** There are new accessors for the vectors returned by `getserv',
5162 `getservbyname', `getservbyport', and `getservent', describing
5163 internet protocols:
5164
5165 Component Accessor
5166 ========================= ===============
5167 official service name servent:name
5168 alias list servent:aliases
5169 port number servent:port
5170 protocol to use servent:proto
5171
5172 *** There are new accessors for the sockaddr structures returned by
5173 `accept', `getsockname', `getpeername', `recvfrom!':
5174
5175 Component Accessor
5176 ======================================== ===============
5177 address format (`family') sockaddr:fam
5178 path, for file domain addresses sockaddr:path
5179 address, for internet domain addresses sockaddr:addr
5180 TCP or UDP port, for internet sockaddr:port
5181
5182 *** The `getpwent', `getgrent', `gethostent', `getnetent',
5183 `getprotoent', and `getservent' functions now return #f at the end of
5184 the user database. (They used to throw an exception.)
5185
5186 Note that calling MUMBLEent function is equivalent to calling the
5187 corresponding MUMBLE function with no arguments.
5188
5189 *** The `setpwent', `setgrent', `sethostent', `setnetent',
5190 `setprotoent', and `setservent' routines now take no arguments.
5191
5192 *** The `gethost', `getproto', `getnet', and `getserv' functions now
5193 provide more useful information when they throw an exception.
5194
5195 *** The `lnaof' function has been renamed to `inet-lnaof'.
5196
5197 *** Guile now claims to have the `current-time' feature.
5198
5199 *** The `mktime' function now takes an optional second argument ZONE,
5200 giving the time zone to use for the conversion. ZONE should be a
5201 string, in the same format as expected for the "TZ" environment variable.
5202
5203 *** The `strptime' function now returns a pair (TIME . COUNT), where
5204 TIME is the parsed time as a vector, and COUNT is the number of
5205 characters from the string left unparsed. This function used to
5206 return the remaining characters as a string.
5207
5208 *** The `gettimeofday' function has replaced the old `time+ticks' function.
5209 The return value is now (SECONDS . MICROSECONDS); the fractional
5210 component is no longer expressed in "ticks".
5211
5212 *** The `ticks/sec' constant has been removed, in light of the above change.
5213
5214 * Changes to the gh_ interface
5215
5216 ** gh_eval_str() now returns an SCM object which is the result of the
5217 evaluation
5218
5219 ** gh_scm2str() now copies the Scheme data to a caller-provided C
5220 array
5221
5222 ** gh_scm2newstr() now makes a C array, copies the Scheme data to it,
5223 and returns the array
5224
5225 ** gh_scm2str0() is gone: there is no need to distinguish
5226 null-terminated from non-null-terminated, since gh_scm2newstr() allows
5227 the user to interpret the data both ways.
5228
5229 * Changes to the scm_ interface
5230
5231 ** The new function scm_symbol_value0 provides an easy way to get a
5232 symbol's value from C code:
5233
5234 SCM scm_symbol_value0 (char *NAME)
5235 Return the value of the symbol named by the null-terminated string
5236 NAME in the current module. If the symbol named NAME is unbound in
5237 the current module, return SCM_UNDEFINED.
5238
5239 ** The new function scm_sysintern0 creates new top-level variables,
5240 without assigning them a value.
5241
5242 SCM scm_sysintern0 (char *NAME)
5243 Create a new Scheme top-level variable named NAME. NAME is a
5244 null-terminated string. Return the variable's value cell.
5245
5246 ** The function scm_internal_catch is the guts of catch. It handles
5247 all the mechanics of setting up a catch target, invoking the catch
5248 body, and perhaps invoking the handler if the body does a throw.
5249
5250 The function is designed to be usable from C code, but is general
5251 enough to implement all the semantics Guile Scheme expects from throw.
5252
5253 TAG is the catch tag. Typically, this is a symbol, but this function
5254 doesn't actually care about that.
5255
5256 BODY is a pointer to a C function which runs the body of the catch;
5257 this is the code you can throw from. We call it like this:
5258 BODY (BODY_DATA, JMPBUF)
5259 where:
5260 BODY_DATA is just the BODY_DATA argument we received; we pass it
5261 through to BODY as its first argument. The caller can make
5262 BODY_DATA point to anything useful that BODY might need.
5263 JMPBUF is the Scheme jmpbuf object corresponding to this catch,
5264 which we have just created and initialized.
5265
5266 HANDLER is a pointer to a C function to deal with a throw to TAG,
5267 should one occur. We call it like this:
5268 HANDLER (HANDLER_DATA, THROWN_TAG, THROW_ARGS)
5269 where
5270 HANDLER_DATA is the HANDLER_DATA argument we recevied; it's the
5271 same idea as BODY_DATA above.
5272 THROWN_TAG is the tag that the user threw to; usually this is
5273 TAG, but it could be something else if TAG was #t (i.e., a
5274 catch-all), or the user threw to a jmpbuf.
5275 THROW_ARGS is the list of arguments the user passed to the THROW
5276 function.
5277
5278 BODY_DATA is just a pointer we pass through to BODY. HANDLER_DATA
5279 is just a pointer we pass through to HANDLER. We don't actually
5280 use either of those pointers otherwise ourselves. The idea is
5281 that, if our caller wants to communicate something to BODY or
5282 HANDLER, it can pass a pointer to it as MUMBLE_DATA, which BODY and
5283 HANDLER can then use. Think of it as a way to make BODY and
5284 HANDLER closures, not just functions; MUMBLE_DATA points to the
5285 enclosed variables.
5286
5287 Of course, it's up to the caller to make sure that any data a
5288 MUMBLE_DATA needs is protected from GC. A common way to do this is
5289 to make MUMBLE_DATA a pointer to data stored in an automatic
5290 structure variable; since the collector must scan the stack for
5291 references anyway, this assures that any references in MUMBLE_DATA
5292 will be found.
5293
5294 ** The new function scm_internal_lazy_catch is exactly like
5295 scm_internal_catch, except:
5296
5297 - It does not unwind the stack (this is the major difference).
5298 - If handler returns, its value is returned from the throw.
5299 - BODY always receives #f as its JMPBUF argument (since there's no
5300 jmpbuf associated with a lazy catch, because we don't unwind the
5301 stack.)
5302
5303 ** scm_body_thunk is a new body function you can pass to
5304 scm_internal_catch if you want the body to be like Scheme's `catch'
5305 --- a thunk, or a function of one argument if the tag is #f.
5306
5307 BODY_DATA is a pointer to a scm_body_thunk_data structure, which
5308 contains the Scheme procedure to invoke as the body, and the tag
5309 we're catching. If the tag is #f, then we pass JMPBUF (created by
5310 scm_internal_catch) to the body procedure; otherwise, the body gets
5311 no arguments.
5312
5313 ** scm_handle_by_proc is a new handler function you can pass to
5314 scm_internal_catch if you want the handler to act like Scheme's catch
5315 --- call a procedure with the tag and the throw arguments.
5316
5317 If the user does a throw to this catch, this function runs a handler
5318 procedure written in Scheme. HANDLER_DATA is a pointer to an SCM
5319 variable holding the Scheme procedure object to invoke. It ought to
5320 be a pointer to an automatic variable (i.e., one living on the stack),
5321 or the procedure object should be otherwise protected from GC.
5322
5323 ** scm_handle_by_message is a new handler function to use with
5324 `scm_internal_catch' if you want Guile to print a message and die.
5325 It's useful for dealing with throws to uncaught keys at the top level.
5326
5327 HANDLER_DATA, if non-zero, is assumed to be a char * pointing to a
5328 message header to print; if zero, we use "guile" instead. That
5329 text is followed by a colon, then the message described by ARGS.
5330
5331 ** The return type of scm_boot_guile is now void; the function does
5332 not return a value, and indeed, never returns at all.
5333
5334 ** The new function scm_shell makes it easy for user applications to
5335 process command-line arguments in a way that is compatible with the
5336 stand-alone guile interpreter (which is in turn compatible with SCSH,
5337 the Scheme shell).
5338
5339 To use the scm_shell function, first initialize any guile modules
5340 linked into your application, and then call scm_shell with the values
5341 of ARGC and ARGV your `main' function received. scm_shell will add
5342 any SCSH-style meta-arguments from the top of the script file to the
5343 argument vector, and then process the command-line arguments. This
5344 generally means loading a script file or starting up an interactive
5345 command interpreter. For details, see "Changes to the stand-alone
5346 interpreter" above.
5347
5348 ** The new functions scm_get_meta_args and scm_count_argv help you
5349 implement the SCSH-style meta-argument, `\'.
5350
5351 char **scm_get_meta_args (int ARGC, char **ARGV)
5352 If the second element of ARGV is a string consisting of a single
5353 backslash character (i.e. "\\" in Scheme notation), open the file
5354 named by the following argument, parse arguments from it, and return
5355 the spliced command line. The returned array is terminated by a
5356 null pointer.
5357
5358 For details of argument parsing, see above, under "guile now accepts
5359 command-line arguments compatible with SCSH..."
5360
5361 int scm_count_argv (char **ARGV)
5362 Count the arguments in ARGV, assuming it is terminated by a null
5363 pointer.
5364
5365 For an example of how these functions might be used, see the source
5366 code for the function scm_shell in libguile/script.c.
5367
5368 You will usually want to use scm_shell instead of calling this
5369 function yourself.
5370
5371 ** The new function scm_compile_shell_switches turns an array of
5372 command-line arguments into Scheme code to carry out the actions they
5373 describe. Given ARGC and ARGV, it returns a Scheme expression to
5374 evaluate, and calls scm_set_program_arguments to make any remaining
5375 command-line arguments available to the Scheme code. For example,
5376 given the following arguments:
5377
5378 -e main -s ekko a speckled gecko
5379
5380 scm_set_program_arguments will return the following expression:
5381
5382 (begin (load "ekko") (main (command-line)) (quit))
5383
5384 You will usually want to use scm_shell instead of calling this
5385 function yourself.
5386
5387 ** The function scm_shell_usage prints a usage message appropriate for
5388 an interpreter that uses scm_compile_shell_switches to handle its
5389 command-line arguments.
5390
5391 void scm_shell_usage (int FATAL, char *MESSAGE)
5392 Print a usage message to the standard error output. If MESSAGE is
5393 non-zero, write it before the usage message, followed by a newline.
5394 If FATAL is non-zero, exit the process, using FATAL as the
5395 termination status. (If you want to be compatible with Guile,
5396 always use 1 as the exit status when terminating due to command-line
5397 usage problems.)
5398
5399 You will usually want to use scm_shell instead of calling this
5400 function yourself.
5401
5402 ** scm_eval_0str now returns SCM_UNSPECIFIED if the string contains no
5403 expressions. It used to return SCM_EOL. Earth-shattering.
5404
5405 ** The macros for declaring scheme objects in C code have been
5406 rearranged slightly. They are now:
5407
5408 SCM_SYMBOL (C_NAME, SCHEME_NAME)
5409 Declare a static SCM variable named C_NAME, and initialize it to
5410 point to the Scheme symbol whose name is SCHEME_NAME. C_NAME should
5411 be a C identifier, and SCHEME_NAME should be a C string.
5412
5413 SCM_GLOBAL_SYMBOL (C_NAME, SCHEME_NAME)
5414 Just like SCM_SYMBOL, but make C_NAME globally visible.
5415
5416 SCM_VCELL (C_NAME, SCHEME_NAME)
5417 Create a global variable at the Scheme level named SCHEME_NAME.
5418 Declare a static SCM variable named C_NAME, and initialize it to
5419 point to the Scheme variable's value cell.
5420
5421 SCM_GLOBAL_VCELL (C_NAME, SCHEME_NAME)
5422 Just like SCM_VCELL, but make C_NAME globally visible.
5423
5424 The `guile-snarf' script writes initialization code for these macros
5425 to its standard output, given C source code as input.
5426
5427 The SCM_GLOBAL macro is gone.
5428
5429 ** The scm_read_line and scm_read_line_x functions have been replaced
5430 by Scheme code based on the %read-delimited! procedure (known to C
5431 code as scm_read_delimited_x). See its description above for more
5432 information.
5433
5434 ** The function scm_sys_open has been renamed to scm_open. It now
5435 returns a port instead of an FD object.
5436
5437 * The dynamic linking support has changed. For more information, see
5438 libguile/DYNAMIC-LINKING.
5439
5440 \f
5441 Guile 1.0b3
5442
5443 User-visible changes from Thursday, September 5, 1996 until Guile 1.0
5444 (Sun 5 Jan 1997):
5445
5446 * Changes to the 'guile' program:
5447
5448 ** Guile now loads some new files when it starts up. Guile first
5449 searches the load path for init.scm, and loads it if found. Then, if
5450 Guile is not being used to execute a script, and the user's home
5451 directory contains a file named `.guile', Guile loads that.
5452
5453 ** You can now use Guile as a shell script interpreter.
5454
5455 To paraphrase the SCSH manual:
5456
5457 When Unix tries to execute an executable file whose first two
5458 characters are the `#!', it treats the file not as machine code to
5459 be directly executed by the native processor, but as source code
5460 to be executed by some interpreter. The interpreter to use is
5461 specified immediately after the #! sequence on the first line of
5462 the source file. The kernel reads in the name of the interpreter,
5463 and executes that instead. It passes the interpreter the source
5464 filename as its first argument, with the original arguments
5465 following. Consult the Unix man page for the `exec' system call
5466 for more information.
5467
5468 Now you can use Guile as an interpreter, using a mechanism which is a
5469 compatible subset of that provided by SCSH.
5470
5471 Guile now recognizes a '-s' command line switch, whose argument is the
5472 name of a file of Scheme code to load. It also treats the two
5473 characters `#!' as the start of a comment, terminated by `!#'. Thus,
5474 to make a file of Scheme code directly executable by Unix, insert the
5475 following two lines at the top of the file:
5476
5477 #!/usr/local/bin/guile -s
5478 !#
5479
5480 Guile treats the argument of the `-s' command-line switch as the name
5481 of a file of Scheme code to load, and treats the sequence `#!' as the
5482 start of a block comment, terminated by `!#'.
5483
5484 For example, here's a version of 'echo' written in Scheme:
5485
5486 #!/usr/local/bin/guile -s
5487 !#
5488 (let loop ((args (cdr (program-arguments))))
5489 (if (pair? args)
5490 (begin
5491 (display (car args))
5492 (if (pair? (cdr args))
5493 (display " "))
5494 (loop (cdr args)))))
5495 (newline)
5496
5497 Why does `#!' start a block comment terminated by `!#', instead of the
5498 end of the line? That is the notation SCSH uses, and although we
5499 don't yet support the other SCSH features that motivate that choice,
5500 we would like to be backward-compatible with any existing Guile
5501 scripts once we do. Furthermore, if the path to Guile on your system
5502 is too long for your kernel, you can start the script with this
5503 horrible hack:
5504
5505 #!/bin/sh
5506 exec /really/long/path/to/guile -s "$0" ${1+"$@"}
5507 !#
5508
5509 Note that some very old Unix systems don't support the `#!' syntax.
5510
5511
5512 ** You can now run Guile without installing it.
5513
5514 Previous versions of the interactive Guile interpreter (`guile')
5515 couldn't start up unless Guile's Scheme library had been installed;
5516 they used the value of the environment variable `SCHEME_LOAD_PATH'
5517 later on in the startup process, but not to find the startup code
5518 itself. Now Guile uses `SCHEME_LOAD_PATH' in all searches for Scheme
5519 code.
5520
5521 To run Guile without installing it, build it in the normal way, and
5522 then set the environment variable `SCHEME_LOAD_PATH' to a
5523 colon-separated list of directories, including the top-level directory
5524 of the Guile sources. For example, if you unpacked Guile so that the
5525 full filename of this NEWS file is /home/jimb/guile-1.0b3/NEWS, then
5526 you might say
5527
5528 export SCHEME_LOAD_PATH=/home/jimb/my-scheme:/home/jimb/guile-1.0b3
5529
5530
5531 ** Guile's read-eval-print loop no longer prints #<unspecified>
5532 results. If the user wants to see this, she can evaluate the
5533 expression (assert-repl-print-unspecified #t), perhaps in her startup
5534 file.
5535
5536 ** Guile no longer shows backtraces by default when an error occurs;
5537 however, it does display a message saying how to get one, and how to
5538 request that they be displayed by default. After an error, evaluate
5539 (backtrace)
5540 to see a backtrace, and
5541 (debug-enable 'backtrace)
5542 to see them by default.
5543
5544
5545
5546 * Changes to Guile Scheme:
5547
5548 ** Guile now distinguishes between #f and the empty list.
5549
5550 This is for compatibility with the IEEE standard, the (possibly)
5551 upcoming Revised^5 Report on Scheme, and many extant Scheme
5552 implementations.
5553
5554 Guile used to have #f and '() denote the same object, to make Scheme's
5555 type system more compatible with Emacs Lisp's. However, the change
5556 caused too much trouble for Scheme programmers, and we found another
5557 way to reconcile Emacs Lisp with Scheme that didn't require this.
5558
5559
5560 ** Guile's delq, delv, delete functions, and their destructive
5561 counterparts, delq!, delv!, and delete!, now remove all matching
5562 elements from the list, not just the first. This matches the behavior
5563 of the corresponding Emacs Lisp functions, and (I believe) the Maclisp
5564 functions which inspired them.
5565
5566 I recognize that this change may break code in subtle ways, but it
5567 seems best to make the change before the FSF's first Guile release,
5568 rather than after.
5569
5570
5571 ** The compiled-library-path function has been deleted from libguile.
5572
5573 ** The facilities for loading Scheme source files have changed.
5574
5575 *** The variable %load-path now tells Guile which directories to search
5576 for Scheme code. Its value is a list of strings, each of which names
5577 a directory.
5578
5579 *** The variable %load-extensions now tells Guile which extensions to
5580 try appending to a filename when searching the load path. Its value
5581 is a list of strings. Its default value is ("" ".scm").
5582
5583 *** (%search-load-path FILENAME) searches the directories listed in the
5584 value of the %load-path variable for a Scheme file named FILENAME,
5585 with all the extensions listed in %load-extensions. If it finds a
5586 match, then it returns its full filename. If FILENAME is absolute, it
5587 returns it unchanged. Otherwise, it returns #f.
5588
5589 %search-load-path will not return matches that refer to directories.
5590
5591 *** (primitive-load FILENAME :optional CASE-INSENSITIVE-P SHARP)
5592 uses %seach-load-path to find a file named FILENAME, and loads it if
5593 it finds it. If it can't read FILENAME for any reason, it throws an
5594 error.
5595
5596 The arguments CASE-INSENSITIVE-P and SHARP are interpreted as by the
5597 `read' function.
5598
5599 *** load uses the same searching semantics as primitive-load.
5600
5601 *** The functions %try-load, try-load-with-path, %load, load-with-path,
5602 basic-try-load-with-path, basic-load-with-path, try-load-module-with-
5603 path, and load-module-with-path have been deleted. The functions
5604 above should serve their purposes.
5605
5606 *** If the value of the variable %load-hook is a procedure,
5607 `primitive-load' applies its value to the name of the file being
5608 loaded (without the load path directory name prepended). If its value
5609 is #f, it is ignored. Otherwise, an error occurs.
5610
5611 This is mostly useful for printing load notification messages.
5612
5613
5614 ** The function `eval!' is no longer accessible from the scheme level.
5615 We can't allow operations which introduce glocs into the scheme level,
5616 because Guile's type system can't handle these as data. Use `eval' or
5617 `read-and-eval!' (see below) as replacement.
5618
5619 ** The new function read-and-eval! reads an expression from PORT,
5620 evaluates it, and returns the result. This is more efficient than
5621 simply calling `read' and `eval', since it is not necessary to make a
5622 copy of the expression for the evaluator to munge.
5623
5624 Its optional arguments CASE_INSENSITIVE_P and SHARP are interpreted as
5625 for the `read' function.
5626
5627
5628 ** The function `int?' has been removed; its definition was identical
5629 to that of `integer?'.
5630
5631 ** The functions `<?', `<?', `<=?', `=?', `>?', and `>=?'. Code should
5632 use the R4RS names for these functions.
5633
5634 ** The function object-properties no longer returns the hash handle;
5635 it simply returns the object's property list.
5636
5637 ** Many functions have been changed to throw errors, instead of
5638 returning #f on failure. The point of providing exception handling in
5639 the language is to simplify the logic of user code, but this is less
5640 useful if Guile's primitives don't throw exceptions.
5641
5642 ** The function `fileno' has been renamed from `%fileno'.
5643
5644 ** The function primitive-mode->fdes returns #t or #f now, not 1 or 0.
5645
5646
5647 * Changes to Guile's C interface:
5648
5649 ** The library's initialization procedure has been simplified.
5650 scm_boot_guile now has the prototype:
5651
5652 void scm_boot_guile (int ARGC,
5653 char **ARGV,
5654 void (*main_func) (),
5655 void *closure);
5656
5657 scm_boot_guile calls MAIN_FUNC, passing it CLOSURE, ARGC, and ARGV.
5658 MAIN_FUNC should do all the work of the program (initializing other
5659 packages, reading user input, etc.) before returning. When MAIN_FUNC
5660 returns, call exit (0); this function never returns. If you want some
5661 other exit value, MAIN_FUNC may call exit itself.
5662
5663 scm_boot_guile arranges for program-arguments to return the strings
5664 given by ARGC and ARGV. If MAIN_FUNC modifies ARGC/ARGV, should call
5665 scm_set_program_arguments with the final list, so Scheme code will
5666 know which arguments have been processed.
5667
5668 scm_boot_guile establishes a catch-all catch handler which prints an
5669 error message and exits the process. This means that Guile exits in a
5670 coherent way when system errors occur and the user isn't prepared to
5671 handle it. If the user doesn't like this behavior, they can establish
5672 their own universal catcher in MAIN_FUNC to shadow this one.
5673
5674 Why must the caller do all the real work from MAIN_FUNC? The garbage
5675 collector assumes that all local variables of type SCM will be above
5676 scm_boot_guile's stack frame on the stack. If you try to manipulate
5677 SCM values after this function returns, it's the luck of the draw
5678 whether the GC will be able to find the objects you allocate. So,
5679 scm_boot_guile function exits, rather than returning, to discourage
5680 people from making that mistake.
5681
5682 The IN, OUT, and ERR arguments were removed; there are other
5683 convenient ways to override these when desired.
5684
5685 The RESULT argument was deleted; this function should never return.
5686
5687 The BOOT_CMD argument was deleted; the MAIN_FUNC argument is more
5688 general.
5689
5690
5691 ** Guile's header files should no longer conflict with your system's
5692 header files.
5693
5694 In order to compile code which #included <libguile.h>, previous
5695 versions of Guile required you to add a directory containing all the
5696 Guile header files to your #include path. This was a problem, since
5697 Guile's header files have names which conflict with many systems'
5698 header files.
5699
5700 Now only <libguile.h> need appear in your #include path; you must
5701 refer to all Guile's other header files as <libguile/mumble.h>.
5702 Guile's installation procedure puts libguile.h in $(includedir), and
5703 the rest in $(includedir)/libguile.
5704
5705
5706 ** Two new C functions, scm_protect_object and scm_unprotect_object,
5707 have been added to the Guile library.
5708
5709 scm_protect_object (OBJ) protects OBJ from the garbage collector.
5710 OBJ will not be freed, even if all other references are dropped,
5711 until someone does scm_unprotect_object (OBJ). Both functions
5712 return OBJ.
5713
5714 Note that calls to scm_protect_object do not nest. You can call
5715 scm_protect_object any number of times on a given object, and the
5716 next call to scm_unprotect_object will unprotect it completely.
5717
5718 Basically, scm_protect_object and scm_unprotect_object just
5719 maintain a list of references to things. Since the GC knows about
5720 this list, all objects it mentions stay alive. scm_protect_object
5721 adds its argument to the list; scm_unprotect_object remove its
5722 argument from the list.
5723
5724
5725 ** scm_eval_0str now returns the value of the last expression
5726 evaluated.
5727
5728 ** The new function scm_read_0str reads an s-expression from a
5729 null-terminated string, and returns it.
5730
5731 ** The new function `scm_stdio_to_port' converts a STDIO file pointer
5732 to a Scheme port object.
5733
5734 ** The new function `scm_set_program_arguments' allows C code to set
5735 the value returned by the Scheme `program-arguments' function.
5736
5737 \f
5738 Older changes:
5739
5740 * Guile no longer includes sophisticated Tcl/Tk support.
5741
5742 The old Tcl/Tk support was unsatisfying to us, because it required the
5743 user to link against the Tcl library, as well as Tk and Guile. The
5744 interface was also un-lispy, in that it preserved Tcl/Tk's practice of
5745 referring to widgets by names, rather than exporting widgets to Scheme
5746 code as a special datatype.
5747
5748 In the Usenix Tk Developer's Workshop held in July 1996, the Tcl/Tk
5749 maintainers described some very interesting changes in progress to the
5750 Tcl/Tk internals, which would facilitate clean interfaces between lone
5751 Tk and other interpreters --- even for garbage-collected languages
5752 like Scheme. They expected the new Tk to be publicly available in the
5753 fall of 1996.
5754
5755 Since it seems that Guile might soon have a new, cleaner interface to
5756 lone Tk, and that the old Guile/Tk glue code would probably need to be
5757 completely rewritten, we (Jim Blandy and Richard Stallman) have
5758 decided not to support the old code. We'll spend the time instead on
5759 a good interface to the newer Tk, as soon as it is available.
5760
5761 Until then, gtcltk-lib provides trivial, low-maintenance functionality.
5762
5763 \f
5764 Copyright information:
5765
5766 Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
5767
5768 Permission is granted to anyone to make or distribute verbatim copies
5769 of this document as received, in any medium, provided that the
5770 copyright notice and this permission notice are preserved,
5771 thus giving the recipient permission to redistribute in turn.
5772
5773 Permission is granted to distribute modified versions
5774 of this document, or of portions of it,
5775 under the above conditions, provided also that they
5776 carry prominent notices stating who last changed them.
5777
5778 \f
5779 Local variables:
5780 mode: outline
5781 paragraph-separate: "[ \f]*$"
5782 end:
5783