* ioext.h: fix up prototypes.
[bpt/guile.git] / NEWS
1 Guile NEWS --- history of user-visible changes. -*- text -*-
2 Copyright (C) 1996, 1997 Free Software Foundation, Inc.
3 See the end for copying conditions.
4
5 Please send Guile bug reports to bug-guile@prep.ai.mit.edu.
6 \f
7 Changes since Guile 1.2:
8
9 * Changes to the distribution
10
11 * Changes to the stand-alone interpreter
12
13 * Changes to the procedure for linking libguile with your programs
14
15 * Changes to Scheme functions and syntax
16
17 ** The detection of circular references has been extended to structs.
18 That is, a structure that -- in the process of being printed -- prints
19 itself does not lead to infinite recursion.
20
21 ** There is now some basic support for fluids. Please read
22 "libguile/fluid.h" to find out more. It is accessible from Scheme with
23 the following functions and macros:
24
25 Function: make-fluid
26
27 Create a new fluid object. Fluids are not special variables or
28 some other extension to the semantics of Scheme, but rather
29 ordinary Scheme objects. You can store them into variables (that
30 are still lexically scoped, of course) or into any other place you
31 like. Every fluid has a initial value of `#f'.
32
33 Function: fluid? OBJ
34
35 Test whether OBJ is a fluid.
36
37 Function: fluid-ref FLUID
38 Function: fluid-set! FLUID VAL
39
40 Access/modify the fluid FLUID. Modifications are only visible
41 within the current dynamic root (that includes threads).
42
43 Function: with-fluids* FLUIDS VALUES THUNK
44
45 FLUIDS is a list of fluids and VALUES a corresponding list of
46 values for these fluids. Before THUNK gets called the values are
47 installed in the fluids and the old values of the fluids are
48 saved in the VALUES list. When the flow of control leaves THUNK
49 or reenters it, the values get swapped again. You might think of
50 this as a `safe-fluid-excursion'. Note that the VALUES list is
51 modified by `with-fluids*'.
52
53 Macro: with-fluids ((FLUID VALUE) ...) FORM ...
54
55 The same as `with-fluids*' but with a different syntax. It looks
56 just like `let', but both FLUID and VALUE are evaluated. Remember,
57 fluids are not special variables but ordinary objects. FLUID
58 should evaluate to a fluid.
59
60 * Changes to system call interfaces:
61
62 ** close-port, close-input-port and close-output-port now return a
63 boolean instead of an `unspecified' object. #t means that the port
64 was successfully closed, while #f means it was already closed. It is
65 also now possible for these procedures to raise an exception if an
66 error occurs (some errors from write can be delayed until close.)
67
68 ** The following new procedures have been added (most use scsh
69 interfaces):
70
71 ** close PORT/FD
72 Similar to close-port, but also works on file descriptors. A side
73 effect of closing a file descriptor is that any ports using that file
74 descriptor are moved to a different file descriptor and have
75 their revealed counts set to zero.
76
77 The next five procedures perform a dup2 system call, if NEWFD (an
78 integer) is supplied, otherwise a dup. The file descriptor to be
79 duplicated can be supplied as an integer or wrapped in a port. The
80 type of value returned varies depending on which procedure is used.
81
82 All procedures also have the side effect when performing dup2 that any
83 ports using NEWFD are moved to a different file descriptor and have
84 their revealed counts set to zero.
85
86 ** dup->fdes PORT/FD [NEWFD]
87 Returns an integer file descriptor.
88
89 ** dup->inport PORT/FD [NEWFD]
90 Returns a new input port using the new file descriptor.
91
92 ** dup->outport PORT/FD [NEWFD]
93 Returns a new output port using the new file descriptor.
94
95 ** dup PORT/FD [NEWFD]
96 Returns a new port if PORT/FD is a port, with the same mode as the
97 supplied port, otherwise returns an integer file descriptor.
98
99 ** dup->port PORT/FD MODE [NEWFD]
100 Returns a new port using the new file descriptor. MODE supplies a
101 mode string for the port (as for `open-file').
102
103 ** port->fdes PORT
104 Returns the integer file descriptor underlying PORT. As a
105 side effect the revealed count of PORT is incremented.
106
107 ** fdes->inport FDES
108 Returns an existing input port which has FDES as its underlying file
109 descriptor, if one exists, and increments its revealed count.
110 Otherwise, returns a new input port with a revealed count of 1.
111
112 ** fdes->outport FDES
113 Returns an existing output port which has FDES as its underlying file
114 descriptor, if one exists, and increments its revealed count.
115 Otherwise, returns a new output port with a revealed count of 1.
116
117 ** setenv NAME VALUE
118 If VALUE is `#f', removes NAME from the environment. Otherwise
119 adds the string NAME=VALUE to the environment, replacing any previous
120 value for NAME.
121
122 ** setvbuf PORT MODE [SIZE]
123 Set the buffering mode for PORT. MODE can be:
124 `_IONBF'
125 non-buffered
126
127 `_IOLBF'
128 line buffered
129
130 `_IOFBF'
131 block buffered, using a newly allocated buffer of SIZE bytes.
132 However if SIZE is zero or unspecified, the port will be made
133 non-buffered.
134
135 This procedure should not be used after I/O has been performed with
136 the port.
137
138 Ports are usually block buffered by default, with a default buffer
139 size. Procedures e.g., *Note open-file: File Ports, which accept a
140 mode string allow `0' to be added to request an unbuffered port.
141
142 ** primitive-exit [STATUS]
143 Terminates the current process without unwinding the Scheme stack.
144 This would usually be used after a fork.
145
146 * Changes to the gh_ interface
147
148 * Changes to the scm_ interface
149
150 \f
151 Changes in Guile 1.2 (released Tuesday, June 24 1997):
152
153 * Changes to the distribution
154
155 ** Nightly snapshots are now available from ftp.red-bean.com.
156 The old server, ftp.cyclic.com, has been relinquished to its rightful
157 owner.
158
159 Nightly snapshots of the Guile development sources are now available via
160 anonymous FTP from ftp.red-bean.com, as /pub/guile/guile-snap.tar.gz.
161
162 Via the web, that's: ftp://ftp.red-bean.com/pub/guile/guile-snap.tar.gz
163 For getit, that's: ftp.red-bean.com:/pub/guile/guile-snap.tar.gz
164
165 ** To run Guile without installing it, the procedure has changed a bit.
166
167 If you used a separate build directory to compile Guile, you'll need
168 to include the build directory in SCHEME_LOAD_PATH, as well as the
169 source directory. See the `INSTALL' file for examples.
170
171 * Changes to the procedure for linking libguile with your programs
172
173 ** The standard Guile load path for Scheme code now includes
174 $(datadir)/guile (usually /usr/local/share/guile). This means that
175 you can install your own Scheme files there, and Guile will find them.
176 (Previous versions of Guile only checked a directory whose name
177 contained the Guile version number, so you had to re-install or move
178 your Scheme sources each time you installed a fresh version of Guile.)
179
180 The load path also includes $(datadir)/guile/site; we recommend
181 putting individual Scheme files there. If you want to install a
182 package with multiple source files, create a directory for them under
183 $(datadir)/guile.
184
185 ** Guile 1.2 will now use the Rx regular expression library, if it is
186 installed on your system. When you are linking libguile into your own
187 programs, this means you will have to link against -lguile, -lqt (if
188 you configured Guile with thread support), and -lrx.
189
190 If you are using autoconf to generate configuration scripts for your
191 application, the following lines should suffice to add the appropriate
192 libraries to your link command:
193
194 ### Find Rx, quickthreads and libguile.
195 AC_CHECK_LIB(rx, main)
196 AC_CHECK_LIB(qt, main)
197 AC_CHECK_LIB(guile, scm_shell)
198
199 The Guile 1.2 distribution does not contain sources for the Rx
200 library, as Guile 1.0 did. If you want to use Rx, you'll need to
201 retrieve it from a GNU FTP site and install it separately.
202
203 * Changes to Scheme functions and syntax
204
205 ** The dynamic linking features of Guile are now enabled by default.
206 You can disable them by giving the `--disable-dynamic-linking' option
207 to configure.
208
209 (dynamic-link FILENAME)
210
211 Find the object file denoted by FILENAME (a string) and link it
212 into the running Guile application. When everything works out,
213 return a Scheme object suitable for representing the linked object
214 file. Otherwise an error is thrown. How object files are
215 searched is system dependent.
216
217 (dynamic-object? VAL)
218
219 Determine whether VAL represents a dynamically linked object file.
220
221 (dynamic-unlink DYNOBJ)
222
223 Unlink the indicated object file from the application. DYNOBJ
224 should be one of the values returned by `dynamic-link'.
225
226 (dynamic-func FUNCTION DYNOBJ)
227
228 Search the C function indicated by FUNCTION (a string or symbol)
229 in DYNOBJ and return some Scheme object that can later be used
230 with `dynamic-call' to actually call this function. Right now,
231 these Scheme objects are formed by casting the address of the
232 function to `long' and converting this number to its Scheme
233 representation.
234
235 (dynamic-call FUNCTION DYNOBJ)
236
237 Call the C function indicated by FUNCTION and DYNOBJ. The
238 function is passed no arguments and its return value is ignored.
239 When FUNCTION is something returned by `dynamic-func', call that
240 function and ignore DYNOBJ. When FUNCTION is a string (or symbol,
241 etc.), look it up in DYNOBJ; this is equivalent to
242
243 (dynamic-call (dynamic-func FUNCTION DYNOBJ) #f)
244
245 Interrupts are deferred while the C function is executing (with
246 SCM_DEFER_INTS/SCM_ALLOW_INTS).
247
248 (dynamic-args-call FUNCTION DYNOBJ ARGS)
249
250 Call the C function indicated by FUNCTION and DYNOBJ, but pass it
251 some arguments and return its return value. The C function is
252 expected to take two arguments and return an `int', just like
253 `main':
254
255 int c_func (int argc, char **argv);
256
257 ARGS must be a list of strings and is converted into an array of
258 `char *'. The array is passed in ARGV and its size in ARGC. The
259 return value is converted to a Scheme number and returned from the
260 call to `dynamic-args-call'.
261
262 When dynamic linking is disabled or not supported on your system,
263 the above functions throw errors, but they are still available.
264
265 Here is a small example that works on GNU/Linux:
266
267 (define libc-obj (dynamic-link "libc.so"))
268 (dynamic-args-call 'rand libc-obj '())
269
270 See the file `libguile/DYNAMIC-LINKING' for additional comments.
271
272 ** The #/ syntax for module names is depreciated, and will be removed
273 in a future version of Guile. Instead of
274
275 #/foo/bar/baz
276
277 instead write
278
279 (foo bar baz)
280
281 The latter syntax is more consistent with existing Lisp practice.
282
283 ** Guile now does fancier printing of structures. Structures are the
284 underlying implementation for records, which in turn are used to
285 implement modules, so all of these object now print differently and in
286 a more informative way.
287
288 The Scheme printer will examine the builtin variable *struct-printer*
289 whenever it needs to print a structure object. When this variable is
290 not `#f' it is deemed to be a procedure and will be applied to the
291 structure object and the output port. When *struct-printer* is `#f'
292 or the procedure return `#f' the structure object will be printed in
293 the boring #<struct 80458270> form.
294
295 This hook is used by some routines in ice-9/boot-9.scm to implement
296 type specific printing routines. Please read the comments there about
297 "printing structs".
298
299 One of the more specific uses of structs are records. The printing
300 procedure that could be passed to MAKE-RECORD-TYPE is now actually
301 called. It should behave like a *struct-printer* procedure (described
302 above).
303
304 ** Guile now supports a new R4RS-compliant syntax for keywords. A
305 token of the form #:NAME, where NAME has the same syntax as a Scheme
306 symbol, is the external representation of the keyword named NAME.
307 Keyword objects print using this syntax as well, so values containing
308 keyword objects can be read back into Guile. When used in an
309 expression, keywords are self-quoting objects.
310
311 Guile suports this read syntax, and uses this print syntax, regardless
312 of the current setting of the `keyword' read option. The `keyword'
313 read option only controls whether Guile recognizes the `:NAME' syntax,
314 which is incompatible with R4RS. (R4RS says such token represent
315 symbols.)
316
317 ** Guile has regular expression support again. Guile 1.0 included
318 functions for matching regular expressions, based on the Rx library.
319 In Guile 1.1, the Guile/Rx interface was removed to simplify the
320 distribution, and thus Guile had no regular expression support. Guile
321 1.2 again supports the most commonly used functions, and supports all
322 of SCSH's regular expression functions.
323
324 If your system does not include a POSIX regular expression library,
325 and you have not linked Guile with a third-party regexp library such as
326 Rx, these functions will not be available. You can tell whether your
327 Guile installation includes regular expression support by checking
328 whether the `*features*' list includes the `regex' symbol.
329
330 *** regexp functions
331
332 By default, Guile supports POSIX extended regular expressions. That
333 means that the characters `(', `)', `+' and `?' are special, and must
334 be escaped if you wish to match the literal characters.
335
336 This regular expression interface was modeled after that implemented
337 by SCSH, the Scheme Shell. It is intended to be upwardly compatible
338 with SCSH regular expressions.
339
340 **** Function: string-match PATTERN STR [START]
341 Compile the string PATTERN into a regular expression and compare
342 it with STR. The optional numeric argument START specifies the
343 position of STR at which to begin matching.
344
345 `string-match' returns a "match structure" which describes what,
346 if anything, was matched by the regular expression. *Note Match
347 Structures::. If STR does not match PATTERN at all,
348 `string-match' returns `#f'.
349
350 Each time `string-match' is called, it must compile its PATTERN
351 argument into a regular expression structure. This operation is
352 expensive, which makes `string-match' inefficient if the same regular
353 expression is used several times (for example, in a loop). For better
354 performance, you can compile a regular expression in advance and then
355 match strings against the compiled regexp.
356
357 **** Function: make-regexp STR [FLAGS]
358 Compile the regular expression described by STR, and return the
359 compiled regexp structure. If STR does not describe a legal
360 regular expression, `make-regexp' throws a
361 `regular-expression-syntax' error.
362
363 FLAGS may be the bitwise-or of one or more of the following:
364
365 **** Constant: regexp/extended
366 Use POSIX Extended Regular Expression syntax when interpreting
367 STR. If not set, POSIX Basic Regular Expression syntax is used.
368 If the FLAGS argument is omitted, we assume regexp/extended.
369
370 **** Constant: regexp/icase
371 Do not differentiate case. Subsequent searches using the
372 returned regular expression will be case insensitive.
373
374 **** Constant: regexp/newline
375 Match-any-character operators don't match a newline.
376
377 A non-matching list ([^...]) not containing a newline matches a
378 newline.
379
380 Match-beginning-of-line operator (^) matches the empty string
381 immediately after a newline, regardless of whether the FLAGS
382 passed to regexp-exec contain regexp/notbol.
383
384 Match-end-of-line operator ($) matches the empty string
385 immediately before a newline, regardless of whether the FLAGS
386 passed to regexp-exec contain regexp/noteol.
387
388 **** Function: regexp-exec REGEXP STR [START [FLAGS]]
389 Match the compiled regular expression REGEXP against `str'. If
390 the optional integer START argument is provided, begin matching
391 from that position in the string. Return a match structure
392 describing the results of the match, or `#f' if no match could be
393 found.
394
395 FLAGS may be the bitwise-or of one or more of the following:
396
397 **** Constant: regexp/notbol
398 The match-beginning-of-line operator always fails to match (but
399 see the compilation flag regexp/newline above) This flag may be
400 used when different portions of a string are passed to
401 regexp-exec and the beginning of the string should not be
402 interpreted as the beginning of the line.
403
404 **** Constant: regexp/noteol
405 The match-end-of-line operator always fails to match (but see the
406 compilation flag regexp/newline above)
407
408 **** Function: regexp? OBJ
409 Return `#t' if OBJ is a compiled regular expression, or `#f'
410 otherwise.
411
412 Regular expressions are commonly used to find patterns in one string
413 and replace them with the contents of another string.
414
415 **** Function: regexp-substitute PORT MATCH [ITEM...]
416 Write to the output port PORT selected contents of the match
417 structure MATCH. Each ITEM specifies what should be written, and
418 may be one of the following arguments:
419
420 * A string. String arguments are written out verbatim.
421
422 * An integer. The submatch with that number is written.
423
424 * The symbol `pre'. The portion of the matched string preceding
425 the regexp match is written.
426
427 * The symbol `post'. The portion of the matched string
428 following the regexp match is written.
429
430 PORT may be `#f', in which case nothing is written; instead,
431 `regexp-substitute' constructs a string from the specified ITEMs
432 and returns that.
433
434 **** Function: regexp-substitute/global PORT REGEXP TARGET [ITEM...]
435 Similar to `regexp-substitute', but can be used to perform global
436 substitutions on STR. Instead of taking a match structure as an
437 argument, `regexp-substitute/global' takes two string arguments: a
438 REGEXP string describing a regular expression, and a TARGET string
439 which should be matched against this regular expression.
440
441 Each ITEM behaves as in REGEXP-SUBSTITUTE, with the following
442 exceptions:
443
444 * A function may be supplied. When this function is called, it
445 will be passed one argument: a match structure for a given
446 regular expression match. It should return a string to be
447 written out to PORT.
448
449 * The `post' symbol causes `regexp-substitute/global' to recurse
450 on the unmatched portion of STR. This *must* be supplied in
451 order to perform global search-and-replace on STR; if it is
452 not present among the ITEMs, then `regexp-substitute/global'
453 will return after processing a single match.
454
455 *** Match Structures
456
457 A "match structure" is the object returned by `string-match' and
458 `regexp-exec'. It describes which portion of a string, if any, matched
459 the given regular expression. Match structures include: a reference to
460 the string that was checked for matches; the starting and ending
461 positions of the regexp match; and, if the regexp included any
462 parenthesized subexpressions, the starting and ending positions of each
463 submatch.
464
465 In each of the regexp match functions described below, the `match'
466 argument must be a match structure returned by a previous call to
467 `string-match' or `regexp-exec'. Most of these functions return some
468 information about the original target string that was matched against a
469 regular expression; we will call that string TARGET for easy reference.
470
471 **** Function: regexp-match? OBJ
472 Return `#t' if OBJ is a match structure returned by a previous
473 call to `regexp-exec', or `#f' otherwise.
474
475 **** Function: match:substring MATCH [N]
476 Return the portion of TARGET matched by subexpression number N.
477 Submatch 0 (the default) represents the entire regexp match. If
478 the regular expression as a whole matched, but the subexpression
479 number N did not match, return `#f'.
480
481 **** Function: match:start MATCH [N]
482 Return the starting position of submatch number N.
483
484 **** Function: match:end MATCH [N]
485 Return the ending position of submatch number N.
486
487 **** Function: match:prefix MATCH
488 Return the unmatched portion of TARGET preceding the regexp match.
489
490 **** Function: match:suffix MATCH
491 Return the unmatched portion of TARGET following the regexp match.
492
493 **** Function: match:count MATCH
494 Return the number of parenthesized subexpressions from MATCH.
495 Note that the entire regular expression match itself counts as a
496 subexpression, and failed submatches are included in the count.
497
498 **** Function: match:string MATCH
499 Return the original TARGET string.
500
501 *** Backslash Escapes
502
503 Sometimes you will want a regexp to match characters like `*' or `$'
504 exactly. For example, to check whether a particular string represents
505 a menu entry from an Info node, it would be useful to match it against
506 a regexp like `^* [^:]*::'. However, this won't work; because the
507 asterisk is a metacharacter, it won't match the `*' at the beginning of
508 the string. In this case, we want to make the first asterisk un-magic.
509
510 You can do this by preceding the metacharacter with a backslash
511 character `\'. (This is also called "quoting" the metacharacter, and
512 is known as a "backslash escape".) When Guile sees a backslash in a
513 regular expression, it considers the following glyph to be an ordinary
514 character, no matter what special meaning it would ordinarily have.
515 Therefore, we can make the above example work by changing the regexp to
516 `^\* [^:]*::'. The `\*' sequence tells the regular expression engine
517 to match only a single asterisk in the target string.
518
519 Since the backslash is itself a metacharacter, you may force a
520 regexp to match a backslash in the target string by preceding the
521 backslash with itself. For example, to find variable references in a
522 TeX program, you might want to find occurrences of the string `\let\'
523 followed by any number of alphabetic characters. The regular expression
524 `\\let\\[A-Za-z]*' would do this: the double backslashes in the regexp
525 each match a single backslash in the target string.
526
527 **** Function: regexp-quote STR
528 Quote each special character found in STR with a backslash, and
529 return the resulting string.
530
531 *Very important:* Using backslash escapes in Guile source code (as
532 in Emacs Lisp or C) can be tricky, because the backslash character has
533 special meaning for the Guile reader. For example, if Guile encounters
534 the character sequence `\n' in the middle of a string while processing
535 Scheme code, it replaces those characters with a newline character.
536 Similarly, the character sequence `\t' is replaced by a horizontal tab.
537 Several of these "escape sequences" are processed by the Guile reader
538 before your code is executed. Unrecognized escape sequences are
539 ignored: if the characters `\*' appear in a string, they will be
540 translated to the single character `*'.
541
542 This translation is obviously undesirable for regular expressions,
543 since we want to be able to include backslashes in a string in order to
544 escape regexp metacharacters. Therefore, to make sure that a backslash
545 is preserved in a string in your Guile program, you must use *two*
546 consecutive backslashes:
547
548 (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
549
550 The string in this example is preprocessed by the Guile reader before
551 any code is executed. The resulting argument to `make-regexp' is the
552 string `^\* [^:]*', which is what we really want.
553
554 This also means that in order to write a regular expression that
555 matches a single backslash character, the regular expression string in
556 the source code must include *four* backslashes. Each consecutive pair
557 of backslashes gets translated by the Guile reader to a single
558 backslash, and the resulting double-backslash is interpreted by the
559 regexp engine as matching a single backslash character. Hence:
560
561 (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
562
563 The reason for the unwieldiness of this syntax is historical. Both
564 regular expression pattern matchers and Unix string processing systems
565 have traditionally used backslashes with the special meanings described
566 above. The POSIX regular expression specification and ANSI C standard
567 both require these semantics. Attempting to abandon either convention
568 would cause other kinds of compatibility problems, possibly more severe
569 ones. Therefore, without extending the Scheme reader to support
570 strings with different quoting conventions (an ungainly and confusing
571 extension when implemented in other languages), we must adhere to this
572 cumbersome escape syntax.
573
574 * Changes to the gh_ interface
575
576 * Changes to the scm_ interface
577
578 * Changes to system call interfaces:
579
580 ** The value returned by `raise' is now unspecified. It throws an exception
581 if an error occurs.
582
583 *** A new procedure `sigaction' can be used to install signal handlers
584
585 (sigaction signum [action] [flags])
586
587 signum is the signal number, which can be specified using the value
588 of SIGINT etc.
589
590 If action is omitted, sigaction returns a pair: the CAR is the current
591 signal hander, which will be either an integer with the value SIG_DFL
592 (default action) or SIG_IGN (ignore), or the Scheme procedure which
593 handles the signal, or #f if a non-Scheme procedure handles the
594 signal. The CDR contains the current sigaction flags for the handler.
595
596 If action is provided, it is installed as the new handler for signum.
597 action can be a Scheme procedure taking one argument, or the value of
598 SIG_DFL (default action) or SIG_IGN (ignore), or #f to restore
599 whatever signal handler was installed before sigaction was first used.
600 Flags can optionally be specified for the new handler (SA_RESTART is
601 always used if the system provides it, so need not be specified.) The
602 return value is a pair with information about the old handler as
603 described above.
604
605 This interface does not provide access to the "signal blocking"
606 facility. Maybe this is not needed, since the thread support may
607 provide solutions to the problem of consistent access to data
608 structures.
609
610 *** A new procedure `flush-all-ports' is equivalent to running
611 `force-output' on every port open for output.
612
613 ** Guile now provides information on how it was built, via the new
614 global variable, %guile-build-info. This variable records the values
615 of the standard GNU makefile directory variables as an assocation
616 list, mapping variable names (symbols) onto directory paths (strings).
617 For example, to find out where the Guile link libraries were
618 installed, you can say:
619
620 guile -c "(display (assq-ref %guile-build-info 'libdir)) (newline)"
621
622
623 * Changes to the scm_ interface
624
625 ** The new function scm_handle_by_message_noexit is just like the
626 existing scm_handle_by_message function, except that it doesn't call
627 exit to terminate the process. Instead, it prints a message and just
628 returns #f. This might be a more appropriate catch-all handler for
629 new dynamic roots and threads.
630
631 \f
632 Changes in Guile 1.1 (released Friday, May 16 1997):
633
634 * Changes to the distribution.
635
636 The Guile 1.0 distribution has been split up into several smaller
637 pieces:
638 guile-core --- the Guile interpreter itself.
639 guile-tcltk --- the interface between the Guile interpreter and
640 Tcl/Tk; Tcl is an interpreter for a stringy language, and Tk
641 is a toolkit for building graphical user interfaces.
642 guile-rgx-ctax --- the interface between Guile and the Rx regular
643 expression matcher, and the translator for the Ctax
644 programming language. These are packaged together because the
645 Ctax translator uses Rx to parse Ctax source code.
646
647 This NEWS file describes the changes made to guile-core since the 1.0
648 release.
649
650 We no longer distribute the documentation, since it was either out of
651 date, or incomplete. As soon as we have current documentation, we
652 will distribute it.
653
654
655
656 * Changes to the stand-alone interpreter
657
658 ** guile now accepts command-line arguments compatible with SCSH, Olin
659 Shivers' Scheme Shell.
660
661 In general, arguments are evaluated from left to right, but there are
662 exceptions. The following switches stop argument processing, and
663 stash all remaining command-line arguments as the value returned by
664 the (command-line) function.
665 -s SCRIPT load Scheme source code from FILE, and exit
666 -c EXPR evalute Scheme expression EXPR, and exit
667 -- stop scanning arguments; run interactively
668
669 The switches below are processed as they are encountered.
670 -l FILE load Scheme source code from FILE
671 -e FUNCTION after reading script, apply FUNCTION to
672 command line arguments
673 -ds do -s script at this point
674 --emacs enable Emacs protocol (experimental)
675 -h, --help display this help and exit
676 -v, --version display version information and exit
677 \ read arguments from following script lines
678
679 So, for example, here is a Guile script named `ekko' (thanks, Olin)
680 which re-implements the traditional "echo" command:
681
682 #!/usr/local/bin/guile -s
683 !#
684 (define (main args)
685 (map (lambda (arg) (display arg) (display " "))
686 (cdr args))
687 (newline))
688
689 (main (command-line))
690
691 Suppose we invoke this script as follows:
692
693 ekko a speckled gecko
694
695 Through the magic of Unix script processing (triggered by the `#!'
696 token at the top of the file), /usr/local/bin/guile receives the
697 following list of command-line arguments:
698
699 ("-s" "./ekko" "a" "speckled" "gecko")
700
701 Unix inserts the name of the script after the argument specified on
702 the first line of the file (in this case, "-s"), and then follows that
703 with the arguments given to the script. Guile loads the script, which
704 defines the `main' function, and then applies it to the list of
705 remaining command-line arguments, ("a" "speckled" "gecko").
706
707 In Unix, the first line of a script file must take the following form:
708
709 #!INTERPRETER ARGUMENT
710
711 where INTERPRETER is the absolute filename of the interpreter
712 executable, and ARGUMENT is a single command-line argument to pass to
713 the interpreter.
714
715 You may only pass one argument to the interpreter, and its length is
716 limited. These restrictions can be annoying to work around, so Guile
717 provides a general mechanism (borrowed from, and compatible with,
718 SCSH) for circumventing them.
719
720 If the ARGUMENT in a Guile script is a single backslash character,
721 `\', Guile will open the script file, parse arguments from its second
722 and subsequent lines, and replace the `\' with them. So, for example,
723 here is another implementation of the `ekko' script:
724
725 #!/usr/local/bin/guile \
726 -e main -s
727 !#
728 (define (main args)
729 (for-each (lambda (arg) (display arg) (display " "))
730 (cdr args))
731 (newline))
732
733 If the user invokes this script as follows:
734
735 ekko a speckled gecko
736
737 Unix expands this into
738
739 /usr/local/bin/guile \ ekko a speckled gecko
740
741 When Guile sees the `\' argument, it replaces it with the arguments
742 read from the second line of the script, producing:
743
744 /usr/local/bin/guile -e main -s ekko a speckled gecko
745
746 This tells Guile to load the `ekko' script, and apply the function
747 `main' to the argument list ("a" "speckled" "gecko").
748
749 Here is how Guile parses the command-line arguments:
750 - Each space character terminates an argument. This means that two
751 spaces in a row introduce an empty-string argument.
752 - The tab character is not permitted (unless you quote it with the
753 backslash character, as described below), to avoid confusion.
754 - The newline character terminates the sequence of arguments, and will
755 also terminate a final non-empty argument. (However, a newline
756 following a space will not introduce a final empty-string argument;
757 it only terminates the argument list.)
758 - The backslash character is the escape character. It escapes
759 backslash, space, tab, and newline. The ANSI C escape sequences
760 like \n and \t are also supported. These produce argument
761 constituents; the two-character combination \n doesn't act like a
762 terminating newline. The escape sequence \NNN for exactly three
763 octal digits reads as the character whose ASCII code is NNN. As
764 above, characters produced this way are argument constituents.
765 Backslash followed by other characters is not allowed.
766
767 * Changes to the procedure for linking libguile with your programs
768
769 ** Guile now builds and installs a shared guile library, if your
770 system support shared libraries. (It still builds a static library on
771 all systems.) Guile automatically detects whether your system
772 supports shared libraries. To prevent Guile from buildisg shared
773 libraries, pass the `--disable-shared' flag to the configure script.
774
775 Guile takes longer to compile when it builds shared libraries, because
776 it must compile every file twice --- once to produce position-
777 independent object code, and once to produce normal object code.
778
779 ** The libthreads library has been merged into libguile.
780
781 To link a program against Guile, you now need only link against
782 -lguile and -lqt; -lthreads is no longer needed. If you are using
783 autoconf to generate configuration scripts for your application, the
784 following lines should suffice to add the appropriate libraries to
785 your link command:
786
787 ### Find quickthreads and libguile.
788 AC_CHECK_LIB(qt, main)
789 AC_CHECK_LIB(guile, scm_shell)
790
791 * Changes to Scheme functions
792
793 ** Guile Scheme's special syntax for keyword objects is now optional,
794 and disabled by default.
795
796 The syntax variation from R4RS made it difficult to port some
797 interesting packages to Guile. The routines which accepted keyword
798 arguments (mostly in the module system) have been modified to also
799 accept symbols whose names begin with `:'.
800
801 To change the keyword syntax, you must first import the (ice-9 debug)
802 module:
803 (use-modules (ice-9 debug))
804
805 Then you can enable the keyword syntax as follows:
806 (read-set! keywords 'prefix)
807
808 To disable keyword syntax, do this:
809 (read-set! keywords #f)
810
811 ** Many more primitive functions accept shared substrings as
812 arguments. In the past, these functions required normal, mutable
813 strings as arguments, although they never made use of this
814 restriction.
815
816 ** The uniform array functions now operate on byte vectors. These
817 functions are `array-fill!', `serial-array-copy!', `array-copy!',
818 `serial-array-map', `array-map', `array-for-each', and
819 `array-index-map!'.
820
821 ** The new functions `trace' and `untrace' implement simple debugging
822 support for Scheme functions.
823
824 The `trace' function accepts any number of procedures as arguments,
825 and tells the Guile interpreter to display each procedure's name and
826 arguments each time the procedure is invoked. When invoked with no
827 arguments, `trace' returns the list of procedures currently being
828 traced.
829
830 The `untrace' function accepts any number of procedures as arguments,
831 and tells the Guile interpreter not to trace them any more. When
832 invoked with no arguments, `untrace' untraces all curretly traced
833 procedures.
834
835 The tracing in Guile has an advantage over most other systems: we
836 don't create new procedure objects, but mark the procedure objects
837 themselves. This means that anonymous and internal procedures can be
838 traced.
839
840 ** The function `assert-repl-prompt' has been renamed to
841 `set-repl-prompt!'. It takes one argument, PROMPT.
842 - If PROMPT is #f, the Guile read-eval-print loop will not prompt.
843 - If PROMPT is a string, we use it as a prompt.
844 - If PROMPT is a procedure accepting no arguments, we call it, and
845 display the result as a prompt.
846 - Otherwise, we display "> ".
847
848 ** The new function `eval-string' reads Scheme expressions from a
849 string and evaluates them, returning the value of the last expression
850 in the string. If the string contains no expressions, it returns an
851 unspecified value.
852
853 ** The new function `thunk?' returns true iff its argument is a
854 procedure of zero arguments.
855
856 ** `defined?' is now a builtin function, instead of syntax. This
857 means that its argument should be quoted. It returns #t iff its
858 argument is bound in the current module.
859
860 ** The new syntax `use-modules' allows you to add new modules to your
861 environment without re-typing a complete `define-module' form. It
862 accepts any number of module names as arguments, and imports their
863 public bindings into the current module.
864
865 ** The new function (module-defined? NAME MODULE) returns true iff
866 NAME, a symbol, is defined in MODULE, a module object.
867
868 ** The new function `builtin-bindings' creates and returns a hash
869 table containing copies of all the root module's bindings.
870
871 ** The new function `builtin-weak-bindings' does the same as
872 `builtin-bindings', but creates a doubly-weak hash table.
873
874 ** The `equal?' function now considers variable objects to be
875 equivalent if they have the same name and the same value.
876
877 ** The new function `command-line' returns the command-line arguments
878 given to Guile, as a list of strings.
879
880 When using guile as a script interpreter, `command-line' returns the
881 script's arguments; those processed by the interpreter (like `-s' or
882 `-c') are omitted. (In other words, you get the normal, expected
883 behavior.) Any application that uses scm_shell to process its
884 command-line arguments gets this behavior as well.
885
886 ** The new function `load-user-init' looks for a file called `.guile'
887 in the user's home directory, and loads it if it exists. This is
888 mostly for use by the code generated by scm_compile_shell_switches,
889 but we thought it might also be useful in other circumstances.
890
891 ** The new function `log10' returns the base-10 logarithm of its
892 argument.
893
894 ** Changes to I/O functions
895
896 *** The functions `read', `primitive-load', `read-and-eval!', and
897 `primitive-load-path' no longer take optional arguments controlling
898 case insensitivity and a `#' parser.
899
900 Case sensitivity is now controlled by a read option called
901 `case-insensitive'. The user can add new `#' syntaxes with the
902 `read-hash-extend' function (see below).
903
904 *** The new function `read-hash-extend' allows the user to change the
905 syntax of Guile Scheme in a somewhat controlled way.
906
907 (read-hash-extend CHAR PROC)
908 When parsing S-expressions, if we read a `#' character followed by
909 the character CHAR, use PROC to parse an object from the stream.
910 If PROC is #f, remove any parsing procedure registered for CHAR.
911
912 The reader applies PROC to two arguments: CHAR and an input port.
913
914 *** The new functions read-delimited and read-delimited! provide a
915 general mechanism for doing delimited input on streams.
916
917 (read-delimited DELIMS [PORT HANDLE-DELIM])
918 Read until we encounter one of the characters in DELIMS (a string),
919 or end-of-file. PORT is the input port to read from; it defaults to
920 the current input port. The HANDLE-DELIM parameter determines how
921 the terminating character is handled; it should be one of the
922 following symbols:
923
924 'trim omit delimiter from result
925 'peek leave delimiter character in input stream
926 'concat append delimiter character to returned value
927 'split return a pair: (RESULT . TERMINATOR)
928
929 HANDLE-DELIM defaults to 'peek.
930
931 (read-delimited! DELIMS BUF [PORT HANDLE-DELIM START END])
932 A side-effecting variant of `read-delimited'.
933
934 The data is written into the string BUF at the indices in the
935 half-open interval [START, END); the default interval is the whole
936 string: START = 0 and END = (string-length BUF). The values of
937 START and END must specify a well-defined interval in BUF, i.e.
938 0 <= START <= END <= (string-length BUF).
939
940 It returns NBYTES, the number of bytes read. If the buffer filled
941 up without a delimiter character being found, it returns #f. If the
942 port is at EOF when the read starts, it returns the EOF object.
943
944 If an integer is returned (i.e., the read is successfully terminated
945 by reading a delimiter character), then the HANDLE-DELIM parameter
946 determines how to handle the terminating character. It is described
947 above, and defaults to 'peek.
948
949 (The descriptions of these functions were borrowed from the SCSH
950 manual, by Olin Shivers and Brian Carlstrom.)
951
952 *** The `%read-delimited!' function is the primitive used to implement
953 `read-delimited' and `read-delimited!'.
954
955 (%read-delimited! DELIMS BUF GOBBLE? [PORT START END])
956
957 This returns a pair of values: (TERMINATOR . NUM-READ).
958 - TERMINATOR describes why the read was terminated. If it is a
959 character or the eof object, then that is the value that terminated
960 the read. If it is #f, the function filled the buffer without finding
961 a delimiting character.
962 - NUM-READ is the number of characters read into BUF.
963
964 If the read is successfully terminated by reading a delimiter
965 character, then the gobble? parameter determines what to do with the
966 terminating character. If true, the character is removed from the
967 input stream; if false, the character is left in the input stream
968 where a subsequent read operation will retrieve it. In either case,
969 the character is also the first value returned by the procedure call.
970
971 (The descriptions of this function was borrowed from the SCSH manual,
972 by Olin Shivers and Brian Carlstrom.)
973
974 *** The `read-line' and `read-line!' functions have changed; they now
975 trim the terminator by default; previously they appended it to the
976 returned string. For the old behavior, use (read-line PORT 'concat).
977
978 *** The functions `uniform-array-read!' and `uniform-array-write!' now
979 take new optional START and END arguments, specifying the region of
980 the array to read and write.
981
982 *** The `ungetc-char-ready?' function has been removed. We feel it's
983 inappropriate for an interface to expose implementation details this
984 way.
985
986 ** Changes to the Unix library and system call interface
987
988 *** The new fcntl function provides access to the Unix `fcntl' system
989 call.
990
991 (fcntl PORT COMMAND VALUE)
992 Apply COMMAND to PORT's file descriptor, with VALUE as an argument.
993 Values for COMMAND are:
994
995 F_DUPFD duplicate a file descriptor
996 F_GETFD read the descriptor's close-on-exec flag
997 F_SETFD set the descriptor's close-on-exec flag to VALUE
998 F_GETFL read the descriptor's flags, as set on open
999 F_SETFL set the descriptor's flags, as set on open to VALUE
1000 F_GETOWN return the process ID of a socket's owner, for SIGIO
1001 F_SETOWN set the process that owns a socket to VALUE, for SIGIO
1002 FD_CLOEXEC not sure what this is
1003
1004 For details, see the documentation for the fcntl system call.
1005
1006 *** The arguments to `select' have changed, for compatibility with
1007 SCSH. The TIMEOUT parameter may now be non-integral, yielding the
1008 expected behavior. The MILLISECONDS parameter has been changed to
1009 MICROSECONDS, to more closely resemble the underlying system call.
1010 The RVEC, WVEC, and EVEC arguments can now be vectors; the type of the
1011 corresponding return set will be the same.
1012
1013 *** The arguments to the `mknod' system call have changed. They are
1014 now:
1015
1016 (mknod PATH TYPE PERMS DEV)
1017 Create a new file (`node') in the file system. PATH is the name of
1018 the file to create. TYPE is the kind of file to create; it should
1019 be 'fifo, 'block-special, or 'char-special. PERMS specifies the
1020 permission bits to give the newly created file. If TYPE is
1021 'block-special or 'char-special, DEV specifies which device the
1022 special file refers to; its interpretation depends on the kind of
1023 special file being created.
1024
1025 *** The `fork' function has been renamed to `primitive-fork', to avoid
1026 clashing with various SCSH forks.
1027
1028 *** The `recv' and `recvfrom' functions have been renamed to `recv!'
1029 and `recvfrom!'. They no longer accept a size for a second argument;
1030 you must pass a string to hold the received value. They no longer
1031 return the buffer. Instead, `recv' returns the length of the message
1032 received, and `recvfrom' returns a pair containing the packet's length
1033 and originating address.
1034
1035 *** The file descriptor datatype has been removed, as have the
1036 `read-fd', `write-fd', `close', `lseek', and `dup' functions.
1037 We plan to replace these functions with a SCSH-compatible interface.
1038
1039 *** The `create' function has been removed; it's just a special case
1040 of `open'.
1041
1042 *** There are new functions to break down process termination status
1043 values. In the descriptions below, STATUS is a value returned by
1044 `waitpid'.
1045
1046 (status:exit-val STATUS)
1047 If the child process exited normally, this function returns the exit
1048 code for the child process (i.e., the value passed to exit, or
1049 returned from main). If the child process did not exit normally,
1050 this function returns #f.
1051
1052 (status:stop-sig STATUS)
1053 If the child process was suspended by a signal, this function
1054 returns the signal that suspended the child. Otherwise, it returns
1055 #f.
1056
1057 (status:term-sig STATUS)
1058 If the child process terminated abnormally, this function returns
1059 the signal that terminated the child. Otherwise, this function
1060 returns false.
1061
1062 POSIX promises that exactly one of these functions will return true on
1063 a valid STATUS value.
1064
1065 These functions are compatible with SCSH.
1066
1067 *** There are new accessors and setters for the broken-out time vectors
1068 returned by `localtime', `gmtime', and that ilk. They are:
1069
1070 Component Accessor Setter
1071 ========================= ============ ============
1072 seconds tm:sec set-tm:sec
1073 minutes tm:min set-tm:min
1074 hours tm:hour set-tm:hour
1075 day of the month tm:mday set-tm:mday
1076 month tm:mon set-tm:mon
1077 year tm:year set-tm:year
1078 day of the week tm:wday set-tm:wday
1079 day in the year tm:yday set-tm:yday
1080 daylight saving time tm:isdst set-tm:isdst
1081 GMT offset, seconds tm:gmtoff set-tm:gmtoff
1082 name of time zone tm:zone set-tm:zone
1083
1084 *** There are new accessors for the vectors returned by `uname',
1085 describing the host system:
1086
1087 Component Accessor
1088 ============================================== ================
1089 name of the operating system implementation utsname:sysname
1090 network name of this machine utsname:nodename
1091 release level of the operating system utsname:release
1092 version level of the operating system utsname:version
1093 machine hardware platform utsname:machine
1094
1095 *** There are new accessors for the vectors returned by `getpw',
1096 `getpwnam', `getpwuid', and `getpwent', describing entries from the
1097 system's user database:
1098
1099 Component Accessor
1100 ====================== =================
1101 user name passwd:name
1102 user password passwd:passwd
1103 user id passwd:uid
1104 group id passwd:gid
1105 real name passwd:gecos
1106 home directory passwd:dir
1107 shell program passwd:shell
1108
1109 *** There are new accessors for the vectors returned by `getgr',
1110 `getgrnam', `getgrgid', and `getgrent', describing entries from the
1111 system's group database:
1112
1113 Component Accessor
1114 ======================= ============
1115 group name group:name
1116 group password group:passwd
1117 group id group:gid
1118 group members group:mem
1119
1120 *** There are new accessors for the vectors returned by `gethost',
1121 `gethostbyaddr', `gethostbyname', and `gethostent', describing
1122 internet hosts:
1123
1124 Component Accessor
1125 ========================= ===============
1126 official name of host hostent:name
1127 alias list hostent:aliases
1128 host address type hostent:addrtype
1129 length of address hostent:length
1130 list of addresses hostent:addr-list
1131
1132 *** There are new accessors for the vectors returned by `getnet',
1133 `getnetbyaddr', `getnetbyname', and `getnetent', describing internet
1134 networks:
1135
1136 Component Accessor
1137 ========================= ===============
1138 official name of net netent:name
1139 alias list netent:aliases
1140 net number type netent:addrtype
1141 net number netent:net
1142
1143 *** There are new accessors for the vectors returned by `getproto',
1144 `getprotobyname', `getprotobynumber', and `getprotoent', describing
1145 internet protocols:
1146
1147 Component Accessor
1148 ========================= ===============
1149 official protocol name protoent:name
1150 alias list protoent:aliases
1151 protocol number protoent:proto
1152
1153 *** There are new accessors for the vectors returned by `getserv',
1154 `getservbyname', `getservbyport', and `getservent', describing
1155 internet protocols:
1156
1157 Component Accessor
1158 ========================= ===============
1159 official service name servent:name
1160 alias list servent:aliases
1161 port number servent:port
1162 protocol to use servent:proto
1163
1164 *** There are new accessors for the sockaddr structures returned by
1165 `accept', `getsockname', `getpeername', `recvfrom!':
1166
1167 Component Accessor
1168 ======================================== ===============
1169 address format (`family') sockaddr:fam
1170 path, for file domain addresses sockaddr:path
1171 address, for internet domain addresses sockaddr:addr
1172 TCP or UDP port, for internet sockaddr:port
1173
1174 *** The `getpwent', `getgrent', `gethostent', `getnetent',
1175 `getprotoent', and `getservent' functions now return #f at the end of
1176 the user database. (They used to throw an exception.)
1177
1178 Note that calling MUMBLEent function is equivalent to calling the
1179 corresponding MUMBLE function with no arguments.
1180
1181 *** The `setpwent', `setgrent', `sethostent', `setnetent',
1182 `setprotoent', and `setservent' routines now take no arguments.
1183
1184 *** The `gethost', `getproto', `getnet', and `getserv' functions now
1185 provide more useful information when they throw an exception.
1186
1187 *** The `lnaof' function has been renamed to `inet-lnaof'.
1188
1189 *** Guile now claims to have the `current-time' feature.
1190
1191 *** The `mktime' function now takes an optional second argument ZONE,
1192 giving the time zone to use for the conversion. ZONE should be a
1193 string, in the same format as expected for the "TZ" environment variable.
1194
1195 *** The `strptime' function now returns a pair (TIME . COUNT), where
1196 TIME is the parsed time as a vector, and COUNT is the number of
1197 characters from the string left unparsed. This function used to
1198 return the remaining characters as a string.
1199
1200 *** The `gettimeofday' function has replaced the old `time+ticks' function.
1201 The return value is now (SECONDS . MICROSECONDS); the fractional
1202 component is no longer expressed in "ticks".
1203
1204 *** The `ticks/sec' constant has been removed, in light of the above change.
1205
1206 * Changes to the gh_ interface
1207
1208 ** gh_eval_str() now returns an SCM object which is the result of the
1209 evaluation
1210
1211 ** gh_scm2str() now copies the Scheme data to a caller-provided C
1212 array
1213
1214 ** gh_scm2newstr() now makes a C array, copies the Scheme data to it,
1215 and returns the array
1216
1217 ** gh_scm2str0() is gone: there is no need to distinguish
1218 null-terminated from non-null-terminated, since gh_scm2newstr() allows
1219 the user to interpret the data both ways.
1220
1221 * Changes to the scm_ interface
1222
1223 ** The new function scm_symbol_value0 provides an easy way to get a
1224 symbol's value from C code:
1225
1226 SCM scm_symbol_value0 (char *NAME)
1227 Return the value of the symbol named by the null-terminated string
1228 NAME in the current module. If the symbol named NAME is unbound in
1229 the current module, return SCM_UNDEFINED.
1230
1231 ** The new function scm_sysintern0 creates new top-level variables,
1232 without assigning them a value.
1233
1234 SCM scm_sysintern0 (char *NAME)
1235 Create a new Scheme top-level variable named NAME. NAME is a
1236 null-terminated string. Return the variable's value cell.
1237
1238 ** The function scm_internal_catch is the guts of catch. It handles
1239 all the mechanics of setting up a catch target, invoking the catch
1240 body, and perhaps invoking the handler if the body does a throw.
1241
1242 The function is designed to be usable from C code, but is general
1243 enough to implement all the semantics Guile Scheme expects from throw.
1244
1245 TAG is the catch tag. Typically, this is a symbol, but this function
1246 doesn't actually care about that.
1247
1248 BODY is a pointer to a C function which runs the body of the catch;
1249 this is the code you can throw from. We call it like this:
1250 BODY (BODY_DATA, JMPBUF)
1251 where:
1252 BODY_DATA is just the BODY_DATA argument we received; we pass it
1253 through to BODY as its first argument. The caller can make
1254 BODY_DATA point to anything useful that BODY might need.
1255 JMPBUF is the Scheme jmpbuf object corresponding to this catch,
1256 which we have just created and initialized.
1257
1258 HANDLER is a pointer to a C function to deal with a throw to TAG,
1259 should one occur. We call it like this:
1260 HANDLER (HANDLER_DATA, THROWN_TAG, THROW_ARGS)
1261 where
1262 HANDLER_DATA is the HANDLER_DATA argument we recevied; it's the
1263 same idea as BODY_DATA above.
1264 THROWN_TAG is the tag that the user threw to; usually this is
1265 TAG, but it could be something else if TAG was #t (i.e., a
1266 catch-all), or the user threw to a jmpbuf.
1267 THROW_ARGS is the list of arguments the user passed to the THROW
1268 function.
1269
1270 BODY_DATA is just a pointer we pass through to BODY. HANDLER_DATA
1271 is just a pointer we pass through to HANDLER. We don't actually
1272 use either of those pointers otherwise ourselves. The idea is
1273 that, if our caller wants to communicate something to BODY or
1274 HANDLER, it can pass a pointer to it as MUMBLE_DATA, which BODY and
1275 HANDLER can then use. Think of it as a way to make BODY and
1276 HANDLER closures, not just functions; MUMBLE_DATA points to the
1277 enclosed variables.
1278
1279 Of course, it's up to the caller to make sure that any data a
1280 MUMBLE_DATA needs is protected from GC. A common way to do this is
1281 to make MUMBLE_DATA a pointer to data stored in an automatic
1282 structure variable; since the collector must scan the stack for
1283 references anyway, this assures that any references in MUMBLE_DATA
1284 will be found.
1285
1286 ** The new function scm_internal_lazy_catch is exactly like
1287 scm_internal_catch, except:
1288
1289 - It does not unwind the stack (this is the major difference).
1290 - If handler returns, its value is returned from the throw.
1291 - BODY always receives #f as its JMPBUF argument (since there's no
1292 jmpbuf associated with a lazy catch, because we don't unwind the
1293 stack.)
1294
1295 ** scm_body_thunk is a new body function you can pass to
1296 scm_internal_catch if you want the body to be like Scheme's `catch'
1297 --- a thunk, or a function of one argument if the tag is #f.
1298
1299 BODY_DATA is a pointer to a scm_body_thunk_data structure, which
1300 contains the Scheme procedure to invoke as the body, and the tag
1301 we're catching. If the tag is #f, then we pass JMPBUF (created by
1302 scm_internal_catch) to the body procedure; otherwise, the body gets
1303 no arguments.
1304
1305 ** scm_handle_by_proc is a new handler function you can pass to
1306 scm_internal_catch if you want the handler to act like Scheme's catch
1307 --- call a procedure with the tag and the throw arguments.
1308
1309 If the user does a throw to this catch, this function runs a handler
1310 procedure written in Scheme. HANDLER_DATA is a pointer to an SCM
1311 variable holding the Scheme procedure object to invoke. It ought to
1312 be a pointer to an automatic variable (i.e., one living on the stack),
1313 or the procedure object should be otherwise protected from GC.
1314
1315 ** scm_handle_by_message is a new handler function to use with
1316 `scm_internal_catch' if you want Guile to print a message and die.
1317 It's useful for dealing with throws to uncaught keys at the top level.
1318
1319 HANDLER_DATA, if non-zero, is assumed to be a char * pointing to a
1320 message header to print; if zero, we use "guile" instead. That
1321 text is followed by a colon, then the message described by ARGS.
1322
1323 ** The return type of scm_boot_guile is now void; the function does
1324 not return a value, and indeed, never returns at all.
1325
1326 ** The new function scm_shell makes it easy for user applications to
1327 process command-line arguments in a way that is compatible with the
1328 stand-alone guile interpreter (which is in turn compatible with SCSH,
1329 the Scheme shell).
1330
1331 To use the scm_shell function, first initialize any guile modules
1332 linked into your application, and then call scm_shell with the values
1333 of ARGC and ARGV your `main' function received. scm_shell will adding
1334 any SCSH-style meta-arguments from the top of the script file to the
1335 argument vector, and then process the command-line arguments. This
1336 generally means loading a script file or starting up an interactive
1337 command interpreter. For details, see "Changes to the stand-alone
1338 interpreter" above.
1339
1340 ** The new functions scm_get_meta_args and scm_count_argv help you
1341 implement the SCSH-style meta-argument, `\'.
1342
1343 char **scm_get_meta_args (int ARGC, char **ARGV)
1344 If the second element of ARGV is a string consisting of a single
1345 backslash character (i.e. "\\" in Scheme notation), open the file
1346 named by the following argument, parse arguments from it, and return
1347 the spliced command line. The returned array is terminated by a
1348 null pointer.
1349
1350 For details of argument parsing, see above, under "guile now accepts
1351 command-line arguments compatible with SCSH..."
1352
1353 int scm_count_argv (char **ARGV)
1354 Count the arguments in ARGV, assuming it is terminated by a null
1355 pointer.
1356
1357 For an example of how these functions might be used, see the source
1358 code for the function scm_shell in libguile/script.c.
1359
1360 You will usually want to use scm_shell instead of calling this
1361 function yourself.
1362
1363 ** The new function scm_compile_shell_switches turns an array of
1364 command-line arguments into Scheme code to carry out the actions they
1365 describe. Given ARGC and ARGV, it returns a Scheme expression to
1366 evaluate, and calls scm_set_program_arguments to make any remaining
1367 command-line arguments available to the Scheme code. For example,
1368 given the following arguments:
1369
1370 -e main -s ekko a speckled gecko
1371
1372 scm_set_program_arguments will return the following expression:
1373
1374 (begin (load "ekko") (main (command-line)) (quit))
1375
1376 You will usually want to use scm_shell instead of calling this
1377 function yourself.
1378
1379 ** The function scm_shell_usage prints a usage message appropriate for
1380 an interpreter that uses scm_compile_shell_switches to handle its
1381 command-line arguments.
1382
1383 void scm_shell_usage (int FATAL, char *MESSAGE)
1384 Print a usage message to the standard error output. If MESSAGE is
1385 non-zero, write it before the usage message, followed by a newline.
1386 If FATAL is non-zero, exit the process, using FATAL as the
1387 termination status. (If you want to be compatible with Guile,
1388 always use 1 as the exit status when terminating due to command-line
1389 usage problems.)
1390
1391 You will usually want to use scm_shell instead of calling this
1392 function yourself.
1393
1394 ** scm_eval_0str now returns SCM_UNSPECIFIED if the string contains no
1395 expressions. It used to return SCM_EOL. Earth-shattering.
1396
1397 ** The macros for declaring scheme objects in C code have been
1398 rearranged slightly. They are now:
1399
1400 SCM_SYMBOL (C_NAME, SCHEME_NAME)
1401 Declare a static SCM variable named C_NAME, and initialize it to
1402 point to the Scheme symbol whose name is SCHEME_NAME. C_NAME should
1403 be a C identifier, and SCHEME_NAME should be a C string.
1404
1405 SCM_GLOBAL_SYMBOL (C_NAME, SCHEME_NAME)
1406 Just like SCM_SYMBOL, but make C_NAME globally visible.
1407
1408 SCM_VCELL (C_NAME, SCHEME_NAME)
1409 Create a global variable at the Scheme level named SCHEME_NAME.
1410 Declare a static SCM variable named C_NAME, and initialize it to
1411 point to the Scheme variable's value cell.
1412
1413 SCM_GLOBAL_VCELL (C_NAME, SCHEME_NAME)
1414 Just like SCM_VCELL, but make C_NAME globally visible.
1415
1416 The `guile-snarf' script writes initialization code for these macros
1417 to its standard output, given C source code as input.
1418
1419 The SCM_GLOBAL macro is gone.
1420
1421 ** The scm_read_line and scm_read_line_x functions have been replaced
1422 by Scheme code based on the %read-delimited! procedure (known to C
1423 code as scm_read_delimited_x). See its description above for more
1424 information.
1425
1426 ** The function scm_sys_open has been renamed to scm_open. It now
1427 returns a port instead of an FD object.
1428
1429 * The dynamic linking support has changed. For more information, see
1430 libguile/DYNAMIC-LINKING.
1431
1432 \f
1433 Guile 1.0b3
1434
1435 User-visible changes from Thursday, September 5, 1996 until Guile 1.0
1436 (Sun 5 Jan 1997):
1437
1438 * Changes to the 'guile' program:
1439
1440 ** Guile now loads some new files when it starts up. Guile first
1441 searches the load path for init.scm, and loads it if found. Then, if
1442 Guile is not being used to execute a script, and the user's home
1443 directory contains a file named `.guile', Guile loads that.
1444
1445 ** You can now use Guile as a shell script interpreter.
1446
1447 To paraphrase the SCSH manual:
1448
1449 When Unix tries to execute an executable file whose first two
1450 characters are the `#!', it treats the file not as machine code to
1451 be directly executed by the native processor, but as source code
1452 to be executed by some interpreter. The interpreter to use is
1453 specified immediately after the #! sequence on the first line of
1454 the source file. The kernel reads in the name of the interpreter,
1455 and executes that instead. It passes the interpreter the source
1456 filename as its first argument, with the original arguments
1457 following. Consult the Unix man page for the `exec' system call
1458 for more information.
1459
1460 Now you can use Guile as an interpreter, using a mechanism which is a
1461 compatible subset of that provided by SCSH.
1462
1463 Guile now recognizes a '-s' command line switch, whose argument is the
1464 name of a file of Scheme code to load. It also treats the two
1465 characters `#!' as the start of a comment, terminated by `!#'. Thus,
1466 to make a file of Scheme code directly executable by Unix, insert the
1467 following two lines at the top of the file:
1468
1469 #!/usr/local/bin/guile -s
1470 !#
1471
1472 Guile treats the argument of the `-s' command-line switch as the name
1473 of a file of Scheme code to load, and treats the sequence `#!' as the
1474 start of a block comment, terminated by `!#'.
1475
1476 For example, here's a version of 'echo' written in Scheme:
1477
1478 #!/usr/local/bin/guile -s
1479 !#
1480 (let loop ((args (cdr (program-arguments))))
1481 (if (pair? args)
1482 (begin
1483 (display (car args))
1484 (if (pair? (cdr args))
1485 (display " "))
1486 (loop (cdr args)))))
1487 (newline)
1488
1489 Why does `#!' start a block comment terminated by `!#', instead of the
1490 end of the line? That is the notation SCSH uses, and although we
1491 don't yet support the other SCSH features that motivate that choice,
1492 we would like to be backward-compatible with any existing Guile
1493 scripts once we do. Furthermore, if the path to Guile on your system
1494 is too long for your kernel, you can start the script with this
1495 horrible hack:
1496
1497 #!/bin/sh
1498 exec /really/long/path/to/guile -s "$0" ${1+"$@"}
1499 !#
1500
1501 Note that some very old Unix systems don't support the `#!' syntax.
1502
1503
1504 ** You can now run Guile without installing it.
1505
1506 Previous versions of the interactive Guile interpreter (`guile')
1507 couldn't start up unless Guile's Scheme library had been installed;
1508 they used the value of the environment variable `SCHEME_LOAD_PATH'
1509 later on in the startup process, but not to find the startup code
1510 itself. Now Guile uses `SCHEME_LOAD_PATH' in all searches for Scheme
1511 code.
1512
1513 To run Guile without installing it, build it in the normal way, and
1514 then set the environment variable `SCHEME_LOAD_PATH' to a
1515 colon-separated list of directories, including the top-level directory
1516 of the Guile sources. For example, if you unpacked Guile so that the
1517 full filename of this NEWS file is /home/jimb/guile-1.0b3/NEWS, then
1518 you might say
1519
1520 export SCHEME_LOAD_PATH=/home/jimb/my-scheme:/home/jimb/guile-1.0b3
1521
1522
1523 ** Guile's read-eval-print loop no longer prints #<unspecified>
1524 results. If the user wants to see this, she can evaluate the
1525 expression (assert-repl-print-unspecified #t), perhaps in her startup
1526 file.
1527
1528 ** Guile no longer shows backtraces by default when an error occurs;
1529 however, it does display a message saying how to get one, and how to
1530 request that they be displayed by default. After an error, evaluate
1531 (backtrace)
1532 to see a backtrace, and
1533 (debug-enable 'backtrace)
1534 to see them by default.
1535
1536
1537
1538 * Changes to Guile Scheme:
1539
1540 ** Guile now distinguishes between #f and the empty list.
1541
1542 This is for compatibility with the IEEE standard, the (possibly)
1543 upcoming Revised^5 Report on Scheme, and many extant Scheme
1544 implementations.
1545
1546 Guile used to have #f and '() denote the same object, to make Scheme's
1547 type system more compatible with Emacs Lisp's. However, the change
1548 caused too much trouble for Scheme programmers, and we found another
1549 way to reconcile Emacs Lisp with Scheme that didn't require this.
1550
1551
1552 ** Guile's delq, delv, delete functions, and their destructive
1553 counterparts, delq!, delv!, and delete!, now remove all matching
1554 elements from the list, not just the first. This matches the behavior
1555 of the corresponding Emacs Lisp functions, and (I believe) the Maclisp
1556 functions which inspired them.
1557
1558 I recognize that this change may break code in subtle ways, but it
1559 seems best to make the change before the FSF's first Guile release,
1560 rather than after.
1561
1562
1563 ** The compiled-library-path function has been deleted from libguile.
1564
1565 ** The facilities for loading Scheme source files have changed.
1566
1567 *** The variable %load-path now tells Guile which directories to search
1568 for Scheme code. Its value is a list of strings, each of which names
1569 a directory.
1570
1571 *** The variable %load-extensions now tells Guile which extensions to
1572 try appending to a filename when searching the load path. Its value
1573 is a list of strings. Its default value is ("" ".scm").
1574
1575 *** (%search-load-path FILENAME) searches the directories listed in the
1576 value of the %load-path variable for a Scheme file named FILENAME,
1577 with all the extensions listed in %load-extensions. If it finds a
1578 match, then it returns its full filename. If FILENAME is absolute, it
1579 returns it unchanged. Otherwise, it returns #f.
1580
1581 %search-load-path will not return matches that refer to directories.
1582
1583 *** (primitive-load FILENAME :optional CASE-INSENSITIVE-P SHARP)
1584 uses %seach-load-path to find a file named FILENAME, and loads it if
1585 it finds it. If it can't read FILENAME for any reason, it throws an
1586 error.
1587
1588 The arguments CASE-INSENSITIVE-P and SHARP are interpreted as by the
1589 `read' function.
1590
1591 *** load uses the same searching semantics as primitive-load.
1592
1593 *** The functions %try-load, try-load-with-path, %load, load-with-path,
1594 basic-try-load-with-path, basic-load-with-path, try-load-module-with-
1595 path, and load-module-with-path have been deleted. The functions
1596 above should serve their purposes.
1597
1598 *** If the value of the variable %load-hook is a procedure,
1599 `primitive-load' applies its value to the name of the file being
1600 loaded (without the load path directory name prepended). If its value
1601 is #f, it is ignored. Otherwise, an error occurs.
1602
1603 This is mostly useful for printing load notification messages.
1604
1605
1606 ** The function `eval!' is no longer accessible from the scheme level.
1607 We can't allow operations which introduce glocs into the scheme level,
1608 because Guile's type system can't handle these as data. Use `eval' or
1609 `read-and-eval!' (see below) as replacement.
1610
1611 ** The new function read-and-eval! reads an expression from PORT,
1612 evaluates it, and returns the result. This is more efficient than
1613 simply calling `read' and `eval', since it is not necessary to make a
1614 copy of the expression for the evaluator to munge.
1615
1616 Its optional arguments CASE_INSENSITIVE_P and SHARP are interpreted as
1617 for the `read' function.
1618
1619
1620 ** The function `int?' has been removed; its definition was identical
1621 to that of `integer?'.
1622
1623 ** The functions `<?', `<?', `<=?', `=?', `>?', and `>=?'. Code should
1624 use the R4RS names for these functions.
1625
1626 ** The function object-properties no longer returns the hash handle;
1627 it simply returns the object's property list.
1628
1629 ** Many functions have been changed to throw errors, instead of
1630 returning #f on failure. The point of providing exception handling in
1631 the language is to simplify the logic of user code, but this is less
1632 useful if Guile's primitives don't throw exceptions.
1633
1634 ** The function `fileno' has been renamed from `%fileno'.
1635
1636 ** The function primitive-mode->fdes returns #t or #f now, not 1 or 0.
1637
1638
1639 * Changes to Guile's C interface:
1640
1641 ** The library's initialization procedure has been simplified.
1642 scm_boot_guile now has the prototype:
1643
1644 void scm_boot_guile (int ARGC,
1645 char **ARGV,
1646 void (*main_func) (),
1647 void *closure);
1648
1649 scm_boot_guile calls MAIN_FUNC, passing it CLOSURE, ARGC, and ARGV.
1650 MAIN_FUNC should do all the work of the program (initializing other
1651 packages, reading user input, etc.) before returning. When MAIN_FUNC
1652 returns, call exit (0); this function never returns. If you want some
1653 other exit value, MAIN_FUNC may call exit itself.
1654
1655 scm_boot_guile arranges for program-arguments to return the strings
1656 given by ARGC and ARGV. If MAIN_FUNC modifies ARGC/ARGV, should call
1657 scm_set_program_arguments with the final list, so Scheme code will
1658 know which arguments have been processed.
1659
1660 scm_boot_guile establishes a catch-all catch handler which prints an
1661 error message and exits the process. This means that Guile exits in a
1662 coherent way when system errors occur and the user isn't prepared to
1663 handle it. If the user doesn't like this behavior, they can establish
1664 their own universal catcher in MAIN_FUNC to shadow this one.
1665
1666 Why must the caller do all the real work from MAIN_FUNC? The garbage
1667 collector assumes that all local variables of type SCM will be above
1668 scm_boot_guile's stack frame on the stack. If you try to manipulate
1669 SCM values after this function returns, it's the luck of the draw
1670 whether the GC will be able to find the objects you allocate. So,
1671 scm_boot_guile function exits, rather than returning, to discourage
1672 people from making that mistake.
1673
1674 The IN, OUT, and ERR arguments were removed; there are other
1675 convenient ways to override these when desired.
1676
1677 The RESULT argument was deleted; this function should never return.
1678
1679 The BOOT_CMD argument was deleted; the MAIN_FUNC argument is more
1680 general.
1681
1682
1683 ** Guile's header files should no longer conflict with your system's
1684 header files.
1685
1686 In order to compile code which #included <libguile.h>, previous
1687 versions of Guile required you to add a directory containing all the
1688 Guile header files to your #include path. This was a problem, since
1689 Guile's header files have names which conflict with many systems'
1690 header files.
1691
1692 Now only <libguile.h> need appear in your #include path; you must
1693 refer to all Guile's other header files as <libguile/mumble.h>.
1694 Guile's installation procedure puts libguile.h in $(includedir), and
1695 the rest in $(includedir)/libguile.
1696
1697
1698 ** Two new C functions, scm_protect_object and scm_unprotect_object,
1699 have been added to the Guile library.
1700
1701 scm_protect_object (OBJ) protects OBJ from the garbage collector.
1702 OBJ will not be freed, even if all other references are dropped,
1703 until someone does scm_unprotect_object (OBJ). Both functions
1704 return OBJ.
1705
1706 Note that calls to scm_protect_object do not nest. You can call
1707 scm_protect_object any number of times on a given object, and the
1708 next call to scm_unprotect_object will unprotect it completely.
1709
1710 Basically, scm_protect_object and scm_unprotect_object just
1711 maintain a list of references to things. Since the GC knows about
1712 this list, all objects it mentions stay alive. scm_protect_object
1713 adds its argument to the list; scm_unprotect_object remove its
1714 argument from the list.
1715
1716
1717 ** scm_eval_0str now returns the value of the last expression
1718 evaluated.
1719
1720 ** The new function scm_read_0str reads an s-expression from a
1721 null-terminated string, and returns it.
1722
1723 ** The new function `scm_stdio_to_port' converts a STDIO file pointer
1724 to a Scheme port object.
1725
1726 ** The new function `scm_set_program_arguments' allows C code to set
1727 the value teruturned by the Scheme `program-arguments' function.
1728
1729 \f
1730 Older changes:
1731
1732 * Guile no longer includes sophisticated Tcl/Tk support.
1733
1734 The old Tcl/Tk support was unsatisfying to us, because it required the
1735 user to link against the Tcl library, as well as Tk and Guile. The
1736 interface was also un-lispy, in that it preserved Tcl/Tk's practice of
1737 referring to widgets by names, rather than exporting widgets to Scheme
1738 code as a special datatype.
1739
1740 In the Usenix Tk Developer's Workshop held in July 1996, the Tcl/Tk
1741 maintainers described some very interesting changes in progress to the
1742 Tcl/Tk internals, which would facilitate clean interfaces between lone
1743 Tk and other interpreters --- even for garbage-collected languages
1744 like Scheme. They expected the new Tk to be publicly available in the
1745 fall of 1996.
1746
1747 Since it seems that Guile might soon have a new, cleaner interface to
1748 lone Tk, and that the old Guile/Tk glue code would probably need to be
1749 completely rewritten, we (Jim Blandy and Richard Stallman) have
1750 decided not to support the old code. We'll spend the time instead on
1751 a good interface to the newer Tk, as soon as it is available.
1752
1753 Until then, gtcltk-lib provides trivial, low-maintenance functionality.
1754
1755 \f
1756 Copyright information:
1757
1758 Copyright (C) 1996,1997 Free Software Foundation, Inc.
1759
1760 Permission is granted to anyone to make or distribute verbatim copies
1761 of this document as received, in any medium, provided that the
1762 copyright notice and this permission notice are preserved,
1763 thus giving the recipient permission to redistribute in turn.
1764
1765 Permission is granted to distribute modified versions
1766 of this document, or of portions of it,
1767 under the above conditions, provided also that they
1768 carry prominent notices stating who last changed them.
1769
1770 \f
1771 Local variables:
1772 mode: outline
1773 paragraph-separate: "[ \f]*$"
1774 end:
1775