Guile NEWS --- history of user-visible changes. -*- text -*-
-Copyright (C) 1996, 1997 Free Software Foundation, Inc.
+Copyright (C) 1996, 1997, 1998, 1999 Free Software Foundation, Inc.
See the end for copying conditions.
-Please send Guile bug reports to bug-guile@prep.ai.mit.edu.
+Please send Guile bug reports to bug-guile@gnu.org.
\f
-Changes in Guile 1.2:
+Changes since Guile 1.3:
-[[trim out any sections we don't need]]
+* Changes to the distribution
+
+** Readline support is no longer included with Guile by default.
+
+Based on the different license terms of Guile and Readline, we
+concluded that Guile should not *by default* cause the linking of
+Readline into an application program. Readline support is now offered
+as a separate module, which is linked into an application only when
+you explicitly specify it.
+
+Although Guile is GNU software, its distribution terms add a special
+exception to the usual GNU General Public License (GPL). Guile's
+license includes a clause that allows you to link Guile with non-free
+programs. We add this exception so as not to put Guile at a
+disadvantage vis-a-vis other extensibility packages that support other
+languages.
+
+In contrast, the GNU Readline library is distributed under the GNU
+General Public License pure and simple. This means that you may not
+link Readline, even dynamically, into an application unless it is
+distributed under a free software license that is compatible the GPL.
+
+Because of this difference in distribution terms, an application that
+can use Guile may not be able to use Readline. Now users will be
+explicitly offered two independent decisions about the use of these
+two packages.
+
+* Changes to the stand-alone interpreter
+
+** All builtins now print as primitives.
+Previously builtin procedures not belonging to the fundamental subr
+types printed as #<compiled closure #<primitive-procedure gsubr-apply>>.
+Now, they print as #<primitive-procedure NAME>.
+
+** Backtraces slightly more intelligible.
+gsubr-apply and macro transformer application frames no longer appear
+in backtraces.
+
+* Changes to Scheme functions and syntax
+
+** The function `dynamic-link' now takes optional keyword arguments.
+ The only keyword argument that is currently defined is `:global
+ BOOL'. With it, you can control whether the shared library will be
+ linked in global mode or not. In global mode, the symbols from the
+ linked library can be used to resolve references from other
+ dynamically linked libraries. In non-global mode, the linked
+ library is essentially invisible and can only be accessed via
+ `dynamic-func', etc. The default is now to link in global mode.
+ Previously, the default has been non-global mode.
+
+ The `#:global' keyword is only effective on platforms that support
+ the dlopen family of functions.
+
+** New function `provided?'
+
+ - Function: provided? FEATURE
+ Return true iff FEATURE is supported by this installation of
+ Guile. FEATURE must be a symbol naming a feature; the global
+ variable `*features*' is a list of available features.
+
+** Changes to the module (ice-9 expect):
+
+*** The expect-strings macro now matches `$' in a regular expression
+ only at a line-break or end-of-file by default. Previously it would
+ match the end of the string accumulated so far. The old behaviour
+ can be obtained by setting the variable `expect-strings-exec-flags'
+ to 0.
+
+*** The expect-strings macro now uses a variable `expect-strings-exec-flags'
+ for the regexp-exec flags. If `regexp/noteol' is included, then `$'
+ in a regular expression will still match before a line-break or
+ end-of-file. The default is `regexp/noteol'.
+
+*** The expect-strings macro now uses a variable
+ `expect-strings-compile-flags' for the flags to be supplied to
+ `make-regexp'. The default is `regexp/newline', which was previously
+ hard-coded.
+
+*** The expect macro now supplies two arguments to a match procedure:
+ the current accumulated string and a flag to indicate whether
+ end-of-file has been reached. Previously only the string was supplied.
+ If end-of-file is reached, the match procedure will be called an
+ additional time with the same accumulated string as the previous call
+ but with the flag set.
+
+** New module (ice-9 format), implementing the Common Lisp `format' function.
+
+This code, and the documentation for it that appears here, was
+borrowed from SLIB, with minor adaptations for Guile.
+
+ - Function: format DESTINATION FORMAT-STRING . ARGUMENTS
+ An almost complete implementation of Common LISP format description
+ according to the CL reference book `Common LISP' from Guy L.
+ Steele, Digital Press. Backward compatible to most of the
+ available Scheme format implementations.
+
+ Returns `#t', `#f' or a string; has side effect of printing
+ according to FORMAT-STRING. If DESTINATION is `#t', the output is
+ to the current output port and `#t' is returned. If DESTINATION
+ is `#f', a formatted string is returned as the result of the call.
+ NEW: If DESTINATION is a string, DESTINATION is regarded as the
+ format string; FORMAT-STRING is then the first argument and the
+ output is returned as a string. If DESTINATION is a number, the
+ output is to the current error port if available by the
+ implementation. Otherwise DESTINATION must be an output port and
+ `#t' is returned.
+
+ FORMAT-STRING must be a string. In case of a formatting error
+ format returns `#f' and prints a message on the current output or
+ error port. Characters are output as if the string were output by
+ the `display' function with the exception of those prefixed by a
+ tilde (~). For a detailed description of the FORMAT-STRING syntax
+ please consult a Common LISP format reference manual. For a test
+ suite to verify this format implementation load `formatst.scm'.
+ Please send bug reports to `lutzeb@cs.tu-berlin.de'.
+
+ Note: `format' is not reentrant, i.e. only one `format'-call may
+ be executed at a time.
+
+
+*** Format Specification (Format version 3.0)
+
+ Please consult a Common LISP format reference manual for a detailed
+description of the format string syntax. For a demonstration of the
+implemented directives see `formatst.scm'.
+
+ This implementation supports directive parameters and modifiers (`:'
+and `@' characters). Multiple parameters must be separated by a comma
+(`,'). Parameters can be numerical parameters (positive or negative),
+character parameters (prefixed by a quote character (`''), variable
+parameters (`v'), number of rest arguments parameter (`#'), empty and
+default parameters. Directive characters are case independent. The
+general form of a directive is:
+
+DIRECTIVE ::= ~{DIRECTIVE-PARAMETER,}[:][@]DIRECTIVE-CHARACTER
+
+DIRECTIVE-PARAMETER ::= [ [-|+]{0-9}+ | 'CHARACTER | v | # ]
+
+*** Implemented CL Format Control Directives
+
+ Documentation syntax: Uppercase characters represent the
+corresponding control directive characters. Lowercase characters
+represent control directive parameter descriptions.
+
+`~A'
+ Any (print as `display' does).
+ `~@A'
+ left pad.
+
+ `~MINCOL,COLINC,MINPAD,PADCHARA'
+ full padding.
+
+`~S'
+ S-expression (print as `write' does).
+ `~@S'
+ left pad.
+
+ `~MINCOL,COLINC,MINPAD,PADCHARS'
+ full padding.
+
+`~D'
+ Decimal.
+ `~@D'
+ print number sign always.
+
+ `~:D'
+ print comma separated.
+
+ `~MINCOL,PADCHAR,COMMACHARD'
+ padding.
+
+`~X'
+ Hexadecimal.
+ `~@X'
+ print number sign always.
+
+ `~:X'
+ print comma separated.
+
+ `~MINCOL,PADCHAR,COMMACHARX'
+ padding.
+
+`~O'
+ Octal.
+ `~@O'
+ print number sign always.
+
+ `~:O'
+ print comma separated.
+
+ `~MINCOL,PADCHAR,COMMACHARO'
+ padding.
+
+`~B'
+ Binary.
+ `~@B'
+ print number sign always.
+
+ `~:B'
+ print comma separated.
+
+ `~MINCOL,PADCHAR,COMMACHARB'
+ padding.
+
+`~NR'
+ Radix N.
+ `~N,MINCOL,PADCHAR,COMMACHARR'
+ padding.
+
+`~@R'
+ print a number as a Roman numeral.
+
+`~:@R'
+ print a number as an "old fashioned" Roman numeral.
+
+`~:R'
+ print a number as an ordinal English number.
+
+`~:@R'
+ print a number as a cardinal English number.
+
+`~P'
+ Plural.
+ `~@P'
+ prints `y' and `ies'.
+
+ `~:P'
+ as `~P but jumps 1 argument backward.'
+
+ `~:@P'
+ as `~@P but jumps 1 argument backward.'
+
+`~C'
+ Character.
+ `~@C'
+ prints a character as the reader can understand it (i.e. `#\'
+ prefixing).
+
+ `~:C'
+ prints a character as emacs does (eg. `^C' for ASCII 03).
+
+`~F'
+ Fixed-format floating-point (prints a flonum like MMM.NNN).
+ `~WIDTH,DIGITS,SCALE,OVERFLOWCHAR,PADCHARF'
+ `~@F'
+ If the number is positive a plus sign is printed.
+
+`~E'
+ Exponential floating-point (prints a flonum like MMM.NNN`E'EE).
+ `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARE'
+ `~@E'
+ If the number is positive a plus sign is printed.
+
+`~G'
+ General floating-point (prints a flonum either fixed or
+ exponential).
+ `~WIDTH,DIGITS,EXPONENTDIGITS,SCALE,OVERFLOWCHAR,PADCHAR,EXPONENTCHARG'
+ `~@G'
+ If the number is positive a plus sign is printed.
+
+`~$'
+ Dollars floating-point (prints a flonum in fixed with signs
+ separated).
+ `~DIGITS,SCALE,WIDTH,PADCHAR$'
+ `~@$'
+ If the number is positive a plus sign is printed.
+
+ `~:@$'
+ A sign is always printed and appears before the padding.
+
+ `~:$'
+ The sign appears before the padding.
+
+`~%'
+ Newline.
+ `~N%'
+ print N newlines.
+
+`~&'
+ print newline if not at the beginning of the output line.
+ `~N&'
+ prints `~&' and then N-1 newlines.
+
+`~|'
+ Page Separator.
+ `~N|'
+ print N page separators.
+
+`~~'
+ Tilde.
+ `~N~'
+ print N tildes.
+
+`~'<newline>
+ Continuation Line.
+ `~:'<newline>
+ newline is ignored, white space left.
+
+ `~@'<newline>
+ newline is left, white space ignored.
+
+`~T'
+ Tabulation.
+ `~@T'
+ relative tabulation.
+
+ `~COLNUM,COLINCT'
+ full tabulation.
+
+`~?'
+ Indirection (expects indirect arguments as a list).
+ `~@?'
+ extracts indirect arguments from format arguments.
+
+`~(STR~)'
+ Case conversion (converts by `string-downcase').
+ `~:(STR~)'
+ converts by `string-capitalize'.
+
+ `~@(STR~)'
+ converts by `string-capitalize-first'.
+
+ `~:@(STR~)'
+ converts by `string-upcase'.
+
+`~*'
+ Argument Jumping (jumps 1 argument forward).
+ `~N*'
+ jumps N arguments forward.
+
+ `~:*'
+ jumps 1 argument backward.
+
+ `~N:*'
+ jumps N arguments backward.
+
+ `~@*'
+ jumps to the 0th argument.
+
+ `~N@*'
+ jumps to the Nth argument (beginning from 0)
+
+`~[STR0~;STR1~;...~;STRN~]'
+ Conditional Expression (numerical clause conditional).
+ `~N['
+ take argument from N.
+
+ `~@['
+ true test conditional.
+
+ `~:['
+ if-else-then conditional.
+
+ `~;'
+ clause separator.
+
+ `~:;'
+ default clause follows.
+
+`~{STR~}'
+ Iteration (args come from the next argument (a list)).
+ `~N{'
+ at most N iterations.
+
+ `~:{'
+ args from next arg (a list of lists).
+
+ `~@{'
+ args from the rest of arguments.
+
+ `~:@{'
+ args from the rest args (lists).
+
+`~^'
+ Up and out.
+ `~N^'
+ aborts if N = 0
+
+ `~N,M^'
+ aborts if N = M
+
+ `~N,M,K^'
+ aborts if N <= M <= K
+
+*** Not Implemented CL Format Control Directives
+
+`~:A'
+ print `#f' as an empty list (see below).
+
+`~:S'
+ print `#f' as an empty list (see below).
+
+`~<~>'
+ Justification.
+
+`~:^'
+ (sorry I don't understand its semantics completely)
+
+*** Extended, Replaced and Additional Control Directives
+
+`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHD'
+`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHX'
+`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHO'
+`~MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHB'
+`~N,MINCOL,PADCHAR,COMMACHAR,COMMAWIDTHR'
+ COMMAWIDTH is the number of characters between two comma
+ characters.
+
+`~I'
+ print a R4RS complex number as `~F~@Fi' with passed parameters for
+ `~F'.
+
+`~Y'
+ Pretty print formatting of an argument for scheme code lists.
+
+`~K'
+ Same as `~?.'
+
+`~!'
+ Flushes the output if format DESTINATION is a port.
+
+`~_'
+ Print a `#\space' character
+ `~N_'
+ print N `#\space' characters.
+
+`~/'
+ Print a `#\tab' character
+ `~N/'
+ print N `#\tab' characters.
+
+`~NC'
+ Takes N as an integer representation for a character. No arguments
+ are consumed. N is converted to a character by `integer->char'. N
+ must be a positive decimal number.
+
+`~:S'
+ Print out readproof. Prints out internal objects represented as
+ `#<...>' as strings `"#<...>"' so that the format output can always
+ be processed by `read'.
+
+`~:A'
+ Print out readproof. Prints out internal objects represented as
+ `#<...>' as strings `"#<...>"' so that the format output can always
+ be processed by `read'.
+
+`~Q'
+ Prints information and a copyright notice on the format
+ implementation.
+ `~:Q'
+ prints format version.
+
+`~F, ~E, ~G, ~$'
+ may also print number strings, i.e. passing a number as a string
+ and format it accordingly.
+
+*** Configuration Variables
+
+ The format module exports some configuration variables to suit the
+systems and users needs. There should be no modification necessary for
+the configuration that comes with Guile. Format detects automatically
+if the running scheme system implements floating point numbers and
+complex numbers.
+
+format:symbol-case-conv
+ Symbols are converted by `symbol->string' so the case type of the
+ printed symbols is implementation dependent.
+ `format:symbol-case-conv' is a one arg closure which is either
+ `#f' (no conversion), `string-upcase', `string-downcase' or
+ `string-capitalize'. (default `#f')
+
+format:iobj-case-conv
+ As FORMAT:SYMBOL-CASE-CONV but applies for the representation of
+ implementation internal objects. (default `#f')
+
+format:expch
+ The character prefixing the exponent value in `~E' printing.
+ (default `#\E')
+
+*** Compatibility With Other Format Implementations
+
+SLIB format 2.x:
+ See `format.doc'.
+
+SLIB format 1.4:
+ Downward compatible except for padding support and `~A', `~S',
+ `~P', `~X' uppercase printing. SLIB format 1.4 uses C-style
+ `printf' padding support which is completely replaced by the CL
+ `format' padding style.
+
+MIT C-Scheme 7.1:
+ Downward compatible except for `~', which is not documented
+ (ignores all characters inside the format string up to a newline
+ character). (7.1 implements `~a', `~s', ~NEWLINE, `~~', `~%',
+ numerical and variable parameters and `:/@' modifiers in the CL
+ sense).
+
+Elk 1.5/2.0:
+ Downward compatible except for `~A' and `~S' which print in
+ uppercase. (Elk implements `~a', `~s', `~~', and `~%' (no
+ directive parameters or modifiers)).
+
+Scheme->C 01nov91:
+ Downward compatible except for an optional destination parameter:
+ S2C accepts a format call without a destination which returns a
+ formatted string. This is equivalent to a #f destination in S2C.
+ (S2C implements `~a', `~s', `~c', `~%', and `~~' (no directive
+ parameters or modifiers)).
+
+
+** Changes to string-handling functions.
+
+These functions were added to support the (ice-9 format) module, above.
+
+*** New function: string-upcase STRING
+*** New function: string-downcase STRING
+
+These are non-destructive versions of the existing string-upcase! and
+string-downcase! functions.
+
+*** New function: string-capitalize! STRING
+*** New function: string-capitalize STRING
+
+These functions convert the first letter of each word in the string to
+upper case. Thus:
+
+ (string-capitalize "howdy there")
+ => "Howdy There"
+
+As with the other functions, string-capitalize! modifies the string in
+place, while string-capitalize returns a modified copy of its argument.
+
+*** New function: string-ci->symbol STRING
+
+Return a symbol whose name is STRING, but having the same case as if
+the symbol had be read by `read'.
+
+Guile can be configured to be sensitive or insensitive to case
+differences in Scheme identifiers. If Guile is case-insensitive, all
+symbols are converted to lower case on input. The `string-ci->symbol'
+function returns a symbol whose name in STRING, transformed as Guile
+would if STRING were input.
+
+*** New function: substring-move! STRING1 START END STRING2 START
+
+Copy the substring of STRING1 from START (inclusive) to END
+(exclusive) to STRING2 at START. STRING1 and STRING2 may be the same
+string, and the source and destination areas may overlap; in all
+cases, the function behaves as if all the characters were copied
+simultanously.
+
+*** Extended functions: substring-move-left! substring-move-right!
+
+These functions now correctly copy arbitrarily overlapping substrings;
+they are both synonyms for substring-move!.
+
+
+** New module (ice-9 getopt-long), with the function `getopt-long'.
+
+getopt-long is a function for parsing command-line arguments in a
+manner consistent with other GNU programs.
+
+(getopt-long ARGS GRAMMAR)
+Parse the arguments ARGS according to the argument list grammar GRAMMAR.
+
+ARGS should be a list of strings. Its first element should be the
+name of the program; subsequent elements should be the arguments
+that were passed to the program on the command line. The
+`program-arguments' procedure returns a list of this form.
+
+GRAMMAR is a list of the form:
+((OPTION (PROPERTY VALUE) ...) ...)
+
+Each OPTION should be a symbol. `getopt-long' will accept a
+command-line option named `--OPTION'.
+Each option can have the following (PROPERTY VALUE) pairs:
+
+ (single-char CHAR) --- Accept `-CHAR' as a single-character
+ equivalent to `--OPTION'. This is how to specify traditional
+ Unix-style flags.
+ (required? BOOL) --- If BOOL is true, the option is required.
+ getopt-long will raise an error if it is not found in ARGS.
+ (value BOOL) --- If BOOL is #t, the option accepts a value; if
+ it is #f, it does not; and if it is the symbol
+ `optional', the option may appear in ARGS with or
+ without a value.
+ (predicate FUNC) --- If the option accepts a value (i.e. you
+ specified `(value #t)' for this option), then getopt
+ will apply FUNC to the value, and throw an exception
+ if it returns #f. FUNC should be a procedure which
+ accepts a string and returns a boolean value; you may
+ need to use quasiquotes to get it into GRAMMAR.
+
+The (PROPERTY VALUE) pairs may occur in any order, but each
+property may occur only once. By default, options do not have
+single-character equivalents, are not required, and do not take
+values.
+
+In ARGS, single-character options may be combined, in the usual
+Unix fashion: ("-x" "-y") is equivalent to ("-xy"). If an option
+accepts values, then it must be the last option in the
+combination; the value is the next argument. So, for example, using
+the following grammar:
+ ((apples (single-char #\a))
+ (blimps (single-char #\b) (value #t))
+ (catalexis (single-char #\c) (value #t)))
+the following argument lists would be acceptable:
+ ("-a" "-b" "bang" "-c" "couth") ("bang" and "couth" are the values
+ for "blimps" and "catalexis")
+ ("-ab" "bang" "-c" "couth") (same)
+ ("-ac" "couth" "-b" "bang") (same)
+ ("-abc" "couth" "bang") (an error, since `-b' is not the
+ last option in its combination)
+
+If an option's value is optional, then `getopt-long' decides
+whether it has a value by looking at what follows it in ARGS. If
+the next element is a string, and it does not appear to be an
+option itself, then that string is the option's value.
+
+The value of a long option can appear as the next element in ARGS,
+or it can follow the option name, separated by an `=' character.
+Thus, using the same grammar as above, the following argument lists
+are equivalent:
+ ("--apples" "Braeburn" "--blimps" "Goodyear")
+ ("--apples=Braeburn" "--blimps" "Goodyear")
+ ("--blimps" "Goodyear" "--apples=Braeburn")
+
+If the option "--" appears in ARGS, argument parsing stops there;
+subsequent arguments are returned as ordinary arguments, even if
+they resemble options. So, in the argument list:
+ ("--apples" "Granny Smith" "--" "--blimp" "Goodyear")
+`getopt-long' will recognize the `apples' option as having the
+value "Granny Smith", but it will not recognize the `blimp'
+option; it will return the strings "--blimp" and "Goodyear" as
+ordinary argument strings.
+
+The `getopt-long' function returns the parsed argument list as an
+assocation list, mapping option names --- the symbols from GRAMMAR
+--- onto their values, or #t if the option does not accept a value.
+Unused options do not appear in the alist.
+
+All arguments that are not the value of any option are returned
+as a list, associated with the empty list.
+
+`getopt-long' throws an exception if:
+- it finds an unrecognized option in ARGS
+- a required option is omitted
+- an option that requires an argument doesn't get one
+- an option that doesn't accept an argument does get one (this can
+ only happen using the long option `--opt=value' syntax)
+- an option predicate fails
+
+So, for example:
+
+(define grammar
+ `((lockfile-dir (required? #t)
+ (value #t)
+ (single-char #\k)
+ (predicate ,file-is-directory?))
+ (verbose (required? #f)
+ (single-char #\v)
+ (value #f))
+ (x-includes (single-char #\x))
+ (rnet-server (single-char #\y)
+ (predicate ,string?))))
+
+(getopt-long '("my-prog" "-vk" "/tmp" "foo1" "--x-includes=/usr/include"
+ "--rnet-server=lamprod" "--" "-fred" "foo2" "foo3")
+ grammar)
+=> ((() "foo1" "-fred" "foo2" "foo3")
+ (rnet-server . "lamprod")
+ (x-includes . "/usr/include")
+ (lockfile-dir . "/tmp")
+ (verbose . #t))
+
+** The (ice-9 getopt-gnu-style) module is obsolete; use (ice-9 getopt-long).
+
+It will be removed in a few releases.
+
+** New syntax: lambda*
+** New syntax: define*
+** New syntax: define*-public
+** New syntax: defmacro*
+** New syntax: defmacro*-public
+Guile now supports optional arguments.
+
+`lambda*', `define*', `define*-public', `defmacro*' and
+`defmacro*-public' are identical to the non-* versions except that
+they use an extended type of parameter list that has the following BNF
+syntax (parentheses are literal, square brackets indicate grouping,
+and `*', `+' and `?' have the usual meaning):
+
+ ext-param-list ::= ( [identifier]* [#&optional [ext-var-decl]+]?
+ [#&key [ext-var-decl]+ [#&allow-other-keys]?]?
+ [[#&rest identifier]|[. identifier]]? ) | [identifier]
+
+ ext-var-decl ::= identifier | ( identifier expression )
+
+The semantics are best illustrated with the following documentation
+and examples for `lambda*':
+
+ lambda* args . body
+ lambda extended for optional and keyword arguments
+
+ lambda* creates a procedure that takes optional arguments. These
+ are specified by putting them inside brackets at the end of the
+ paramater list, but before any dotted rest argument. For example,
+ (lambda* (a b #&optional c d . e) '())
+ creates a procedure with fixed arguments a and b, optional arguments c
+ and d, and rest argument e. If the optional arguments are omitted
+ in a call, the variables for them are unbound in the procedure. This
+ can be checked with the bound? macro.
+
+ lambda* can also take keyword arguments. For example, a procedure
+ defined like this:
+ (lambda* (#&key xyzzy larch) '())
+ can be called with any of the argument lists (#:xyzzy 11)
+ (#:larch 13) (#:larch 42 #:xyzzy 19) (). Whichever arguments
+ are given as keywords are bound to values.
+
+ Optional and keyword arguments can also be given default values
+ which they take on when they are not present in a call, by giving a
+ two-item list in place of an optional argument, for example in:
+ (lambda* (foo #&optional (bar 42) #&key (baz 73)) (list foo bar baz))
+ foo is a fixed argument, bar is an optional argument with default
+ value 42, and baz is a keyword argument with default value 73.
+ Default value expressions are not evaluated unless they are needed
+ and until the procedure is called.
+
+ lambda* now supports two more special parameter list keywords.
+
+ lambda*-defined procedures now throw an error by default if a
+ keyword other than one of those specified is found in the actual
+ passed arguments. However, specifying #&allow-other-keys
+ immediately after the kyword argument declarations restores the
+ previous behavior of ignoring unknown keywords. lambda* also now
+ guarantees that if the same keyword is passed more than once, the
+ last one passed is the one that takes effect. For example,
+ ((lambda* (#&key (heads 0) (tails 0)) (display (list heads tails)))
+ #:heads 37 #:tails 42 #:heads 99)
+ would result in (99 47) being displayed.
+
+ #&rest is also now provided as a synonym for the dotted syntax rest
+ argument. The argument lists (a . b) and (a #&rest b) are equivalent in
+ all respects to lambda*. This is provided for more similarity to DSSSL,
+ MIT-Scheme and Kawa among others, as well as for refugees from other
+ Lisp dialects.
+
+Further documentation may be found in the optargs.scm file itself.
+
+The optional argument module also exports the macros `let-optional',
+`let-optional*', `let-keywords', `let-keywords*' and `bound?'. These
+are not documented here because they may be removed in the future, but
+full documentation is still available in optargs.scm.
+
+** New syntax: and-let*
+Guile now supports the `and-let*' form, described in the draft SRFI-2.
+
+Syntax: (land* (<clause> ...) <body> ...)
+Each <clause> should have one of the following forms:
+ (<variable> <expression>)
+ (<expression>)
+ <bound-variable>
+Each <variable> or <bound-variable> should be an identifier. Each
+<expression> should be a valid expression. The <body> should be a
+possibly empty sequence of expressions, like the <body> of a
+lambda form.
+
+Semantics: A LAND* expression is evaluated by evaluating the
+<expression> or <bound-variable> of each of the <clause>s from
+left to right. The value of the first <expression> or
+<bound-variable> that evaluates to a false value is returned; the
+remaining <expression>s and <bound-variable>s are not evaluated.
+The <body> forms are evaluated iff all the <expression>s and
+<bound-variable>s evaluate to true values.
+
+The <expression>s and the <body> are evaluated in an environment
+binding each <variable> of the preceding (<variable> <expression>)
+clauses to the value of the <expression>. Later bindings
+shadow earlier bindings.
+
+Guile's and-let* macro was contributed by Michael Livshin.
+
+** New function: sorted? SEQUENCE LESS?
+Returns `#t' when the sequence argument is in non-decreasing order
+according to LESS? (that is, there is no adjacent pair `... x y
+...' for which `(less? y x)').
+
+Returns `#f' when the sequence contains at least one out-of-order
+pair. It is an error if the sequence is neither a list nor a
+vector.
+
+** New function: merge LIST1 LIST2 LESS?
+LIST1 and LIST2 are sorted lists.
+Returns the sorted list of all elements in LIST1 and LIST2.
+
+Assume that the elements a and b1 in LIST1 and b2 in LIST2 are "equal"
+in the sense that (LESS? x y) --> #f for x, y in {a, b1, b2},
+and that a < b1 in LIST1. Then a < b1 < b2 in the result.
+(Here "<" should read "comes before".)
+
+** New procedure: merge! LIST1 LIST2 LESS?
+Merges two lists, re-using the pairs of LIST1 and LIST2 to build
+the result. If the code is compiled, and LESS? constructs no new
+pairs, no pairs at all will be allocated. The first pair of the
+result will be either the first pair of LIST1 or the first pair of
+LIST2.
+
+** New function: sort SEQUENCE LESS?
+Accepts either a list or a vector, and returns a new sequence
+which is sorted. The new sequence is the same type as the input.
+Always `(sorted? (sort sequence less?) less?)'. The original
+sequence is not altered in any way. The new sequence shares its
+elements with the old one; no elements are copied.
+
+** New procedure: sort! SEQUENCE LESS
+Returns its sorted result in the original boxes. No new storage is
+allocated at all. Proper usage: (set! slist (sort! slist <))
+
+** New function: stable-sort SEQUENCE LESS?
+Similar to `sort' but stable. That is, if "equal" elements are
+ordered a < b in the original sequence, they will have the same order
+in the result.
+
+** New function: stable-sort! SEQUENCE LESS?
+Similar to `sort!' but stable.
+Uses temporary storage when sorting vectors.
+
+** New functions: sort-list, sort-list!
+Added for compatibility with scsh.
+
+** New function: random N [STATE]
+Accepts a positive integer or real N and returns a number of the
+same type between zero (inclusive) and N (exclusive). The values
+returned have a uniform distribution.
+
+The optional argument STATE must be of the type produced by
+`copy-random-state' or `seed->random-state'. It defaults to the value
+of the variable `*random-state*'. This object is used to maintain the
+state of the pseudo-random-number generator and is altered as a side
+effect of the `random' operation.
+
+** New variable: *random-state*
+Holds a data structure that encodes the internal state of the
+random-number generator that `random' uses by default. The nature
+of this data structure is implementation-dependent. It may be
+printed out and successfully read back in, but may or may not
+function correctly as a random-number state object in another
+implementation.
+
+** New function: copy-random-state [STATE]
+Returns a new object of type suitable for use as the value of the
+variable `*random-state*' and as a second argument to `random'.
+If argument STATE is given, a copy of it is returned. Otherwise a
+copy of `*random-state*' is returned.
+
+** New function: seed->random-state SEED
+Returns a new object of type suitable for use as the value of the
+variable `*random-state*' and as a second argument to `random'.
+SEED is a string or a number. A new state is generated and
+initialized using SEED.
+
+** New function: random:uniform [STATE]
+Returns an uniformly distributed inexact real random number in the
+range between 0 and 1.
+
+** New procedure: random:solid-sphere! VECT [STATE]
+Fills VECT with inexact real random numbers the sum of whose
+squares is less than 1.0. Thinking of VECT as coordinates in
+space of dimension N = `(vector-length VECT)', the coordinates are
+uniformly distributed within the unit N-shere. The sum of the
+squares of the numbers is returned. VECT can be either a vector
+or a uniform vector of doubles.
+
+** New procedure: random:hollow-sphere! VECT [STATE]
+Fills VECT with inexact real random numbers the sum of whose squares
+is equal to 1.0. Thinking of VECT as coordinates in space of
+dimension n = `(vector-length VECT)', the coordinates are uniformly
+distributed over the surface of the unit n-shere. VECT can be either
+a vector or a uniform vector of doubles.
+
+** New function: random:normal [STATE]
+Returns an inexact real in a normal distribution with mean 0 and
+standard deviation 1. For a normal distribution with mean M and
+standard deviation D use `(+ M (* D (random:normal)))'.
+
+** New procedure: random:normal-vector! VECT [STATE]
+Fills VECT with inexact real random numbers which are independent and
+standard normally distributed (i.e., with mean 0 and variance 1).
+VECT can be either a vector or a uniform vector of doubles.
+
+** New function: random:exp STATE
+Returns an inexact real in an exponential distribution with mean 1.
+For an exponential distribution with mean U use (* U (random:exp)).
+
+** The range of logand, logior, logxor, logtest, and logbit? have changed.
+
+These functions now operate on numbers in the range of a C unsigned
+long.
+
+These functions used to operate on numbers in the range of a C signed
+long; however, this seems inappropriate, because Guile integers don't
+overflow.
+
+** New function: make-guardian
+This is an implementation of guardians as described in
+R. Kent Dybvig, Carl Bruggeman, and David Eby (1993) "Guardians in a
+Generation-Based Garbage Collector" ACM SIGPLAN Conference on
+Programming Language Design and Implementation, June 1993
+ftp://ftp.cs.indiana.edu/pub/scheme-repository/doc/pubs/guardians.ps.gz
+
+** New functions: delq1!, delv1!, delete1!
+These procedures behave similar to delq! and friends but delete only
+one object if at all.
+
+** New function: unread-string STRING PORT
+Unread STRING to PORT, that is, push it back onto the port so that
+next read operation will work on the pushed back characters.
+
+** unread-char can now be called multiple times
+If unread-char is called multiple times, the unread characters will be
+read again in last-in first-out order.
+
+** New function: map-in-order PROC LIST1 LIST2 ...
+Version of `map' which guarantees that the procedure is applied to the
+lists in serial order.
+
+** Renamed `serial-array-copy!' and `serial-array-map!' to
+`array-copy-in-order!' and `array-map-in-order!'. The old names are
+now obsolete and will go away in release 1.5.
+
+** New syntax: collect BODY1 ...
+Version of `begin' which returns a list of the results of the body
+forms instead of the result of the last body form. In contrast to
+`begin', `collect' allows an empty body.
+
+** New functions: read-history FILENAME, write-history FILENAME
+Read/write command line history from/to file. Returns #t on success
+and #f if an error occured.
+
+** `ls' and `lls' in module (ice-9 ls) now handle no arguments.
+
+These procedures return a list of definitions available in the specified
+argument, a relative module reference. In the case of no argument,
+`(current-module)' is now consulted for definitions to return, instead
+of simply returning #f, the former behavior.
+
+* Changes to the gh_ interface
+
+** gh_scm2doubles
+
+Now takes a second argument which is the result array. If this
+pointer is NULL, a new array is malloced (the old behaviour).
+
+** gh_chars2byvect, gh_shorts2svect, gh_floats2fvect, gh_scm2chars,
+ gh_scm2shorts, gh_scm2longs, gh_scm2floats
+
+New functions.
+
+* Changes to the scm_ interface
+
+** Plug in interface for random number generators
+The variable `scm_the_rng' in random.c contains a value and three
+function pointers which together define the current random number
+generator being used by the Scheme level interface and the random
+number library functions.
+
+The user is free to replace the default generator with the generator
+of his own choice.
+
+*** Variable: size_t scm_the_rng.rstate_size
+The size of the random state type used by the current RNG
+measured in chars.
+
+*** Function: unsigned long scm_the_rng.random_bits (scm_rstate *STATE)
+Given the random STATE, return 32 random bits.
+
+*** Function: void scm_the_rng.init_rstate (scm_rstate *STATE, chars *S, int N)
+Seed random state STATE using string S of length N.
+
+*** Function: scm_rstate *scm_the_rng.copy_rstate (scm_rstate *STATE)
+Given random state STATE, return a malloced copy.
+
+** Default RNG
+The default RNG is the MWC (Multiply With Carry) random number
+generator described by George Marsaglia at the Department of
+Statistics and Supercomputer Computations Research Institute, The
+Florida State University (http://stat.fsu.edu/~geo).
+
+It uses 64 bits, has a period of 4578426017172946943 (4.6e18), and
+passes all tests in the DIEHARD test suite
+(http://stat.fsu.edu/~geo/diehard.html). The generation of 32 bits
+costs one multiply and one add on platforms which either supports long
+longs (gcc does this on most systems) or have 64 bit longs. The cost
+is four multiply on other systems but this can be optimized by writing
+scm_i_uniform32 in assembler.
+
+These functions are provided through the scm_the_rng interface for use
+by libguile and the application.
+
+*** Function: unsigned long scm_i_uniform32 (scm_i_rstate *STATE)
+Given the random STATE, return 32 random bits.
+Don't use this function directly. Instead go through the plugin
+interface (see "Plug in interface" above).
+
+*** Function: void scm_i_init_rstate (scm_i_rstate *STATE, char *SEED, int N)
+Initialize STATE using SEED of length N.
+
+*** Function: scm_i_rstate *scm_i_copy_rstate (scm_i_rstate *STATE)
+Return a malloc:ed copy of STATE. This function can easily be re-used
+in the interfaces to other RNGs.
+
+** Random number library functions
+These functions use the current RNG through the scm_the_rng interface.
+It might be a good idea to use these functions from your C code so
+that only one random generator is used by all code in your program.
+
+You can get the default random state using:
+
+*** Variable: SCM scm_var_random_state
+Contains the vcell of the Scheme variable "*random-state*" which is
+used as default state by all random number functions in the Scheme
+level interface.
+
+Example:
+
+ double x = scm_i_uniform01 (SCM_RSTATE (SCM_CDR (scm_var_random_state)));
+
+*** Function: double scm_i_uniform01 (scm_rstate *STATE)
+Return a sample from the uniform(0,1) distribution.
+
+*** Function: double scm_i_normal01 (scm_rstate *STATE)
+Return a sample from the normal(0,1) distribution.
+
+*** Function: double scm_i_exp1 (scm_rstate *STATE)
+Return a sample from the exp(1) distribution.
+
+*** Function: unsigned long scm_i_random (unsigned long M, scm_rstate *STATE)
+Return a sample from the discrete uniform(0,M) distribution.
+
+\f
+Changes in Guile 1.3 (released Monday, October 19, 1998):
* Changes to the distribution
+** We renamed the SCHEME_LOAD_PATH environment variable to GUILE_LOAD_PATH.
+To avoid conflicts, programs should name environment variables after
+themselves, except when there's a common practice establishing some
+other convention.
+
+For now, Guile supports both GUILE_LOAD_PATH and SCHEME_LOAD_PATH,
+giving the former precedence, and printing a warning message if the
+latter is set. Guile 1.4 will not recognize SCHEME_LOAD_PATH at all.
+
+** The header files related to multi-byte characters have been removed.
+They were: libguile/extchrs.h and libguile/mbstrings.h. Any C code
+which referred to these explicitly will probably need to be rewritten,
+since the support for the variant string types has been removed; see
+below.
+
+** The header files append.h and sequences.h have been removed. These
+files implemented non-R4RS operations which would encourage
+non-portable programming style and less easy-to-read code.
+
+* Changes to the stand-alone interpreter
+
+** New procedures have been added to implement a "batch mode":
+
+*** Function: batch-mode?
+
+ Returns a boolean indicating whether the interpreter is in batch
+ mode.
+
+*** Function: set-batch-mode?! ARG
+
+ If ARG is true, switches the interpreter to batch mode. The `#f'
+ case has not been implemented.
+
+** Guile now provides full command-line editing, when run interactively.
+To use this feature, you must have the readline library installed.
+The Guile build process will notice it, and automatically include
+support for it.
+
+The readline library is available via anonymous FTP from any GNU
+mirror site; the canonical location is "ftp://prep.ai.mit.edu/pub/gnu".
+
+** the-last-stack is now a fluid.
+
* Changes to the procedure for linking libguile with your programs
-** Like Guile 1.1, Guile 1.2 will now use the Rx regular expression
-library, if it is installed on your system. When you are linking
-libguile into your own programs, this means you will have to link
-against -lguile, -lqt (if you configured Guile with thread support),
-and -lrx.
+** You can now use the `guile-config' utility to build programs that use Guile.
+
+Guile now includes a command-line utility called `guile-config', which
+can provide information about how to compile and link programs that
+use Guile.
+
+*** `guile-config compile' prints any C compiler flags needed to use Guile.
+You should include this command's output on the command line you use
+to compile C or C++ code that #includes the Guile header files. It's
+usually just a `-I' flag to help the compiler find the Guile headers.
+
+
+*** `guile-config link' prints any linker flags necessary to link with Guile.
+
+This command writes to its standard output a list of flags which you
+must pass to the linker to link your code against the Guile library.
+The flags include '-lguile' itself, any other libraries the Guile
+library depends upon, and any `-L' flags needed to help the linker
+find those libraries.
+
+For example, here is a Makefile rule that builds a program named 'foo'
+from the object files ${FOO_OBJECTS}, and links them against Guile:
+
+ foo: ${FOO_OBJECTS}
+ ${CC} ${CFLAGS} ${FOO_OBJECTS} `guile-config link` -o foo
+
+Previous Guile releases recommended that you use autoconf to detect
+which of a predefined set of libraries were present on your system.
+It is more robust to use `guile-config', since it records exactly which
+libraries the installed Guile library requires.
+
+This was originally called `build-guile', but was renamed to
+`guile-config' before Guile 1.3 was released, to be consistent with
+the analogous script for the GTK+ GUI toolkit, which is called
+`gtk-config'.
+
+
+** Use the GUILE_FLAGS macro in your configure.in file to find Guile.
+
+If you are using the GNU autoconf package to configure your program,
+you can use the GUILE_FLAGS autoconf macro to call `guile-config'
+(described above) and gather the necessary values for use in your
+Makefiles.
+
+The GUILE_FLAGS macro expands to configure script code which runs the
+`guile-config' script, to find out where Guile's header files and
+libraries are installed. It sets two variables, marked for
+substitution, as by AC_SUBST.
+
+ GUILE_CFLAGS --- flags to pass to a C or C++ compiler to build
+ code that uses Guile header files. This is almost always just a
+ -I flag.
+
+ GUILE_LDFLAGS --- flags to pass to the linker to link a
+ program against Guile. This includes `-lguile' for the Guile
+ library itself, any libraries that Guile itself requires (like
+ -lqthreads), and so on. It may also include a -L flag to tell the
+ compiler where to find the libraries.
+
+GUILE_FLAGS is defined in the file guile.m4, in the top-level
+directory of the Guile distribution. You can copy it into your
+package's aclocal.m4 file, and then use it in your configure.in file.
+
+If you are using the `aclocal' program, distributed with GNU automake,
+to maintain your aclocal.m4 file, the Guile installation process
+installs guile.m4 where aclocal will find it. All you need to do is
+use GUILE_FLAGS in your configure.in file, and then run `aclocal';
+this will copy the definition of GUILE_FLAGS into your aclocal.m4
+file.
+
+
+* Changes to Scheme functions and syntax
+
+** Multi-byte strings have been removed, as have multi-byte and wide
+ports. We felt that these were the wrong approach to
+internationalization support.
+
+** New function: readline [PROMPT]
+Read a line from the terminal, and allow the user to edit it,
+prompting with PROMPT. READLINE provides a large set of Emacs-like
+editing commands, lets the user recall previously typed lines, and
+works on almost every kind of terminal, including dumb terminals.
+
+READLINE assumes that the cursor is at the beginning of the line when
+it is invoked. Thus, you can't print a prompt yourself, and then call
+READLINE; you need to package up your prompt as a string, pass it to
+the function, and let READLINE print the prompt itself. This is
+because READLINE needs to know the prompt's screen width.
+
+For Guile to provide this function, you must have the readline
+library, version 2.1 or later, installed on your system. Readline is
+available via anonymous FTP from prep.ai.mit.edu in pub/gnu, or from
+any GNU mirror site.
+
+See also ADD-HISTORY function.
+
+** New function: add-history STRING
+Add STRING as the most recent line in the history used by the READLINE
+command. READLINE does not add lines to the history itself; you must
+call ADD-HISTORY to make previous input available to the user.
+
+** The behavior of the read-line function has changed.
+
+This function now uses standard C library functions to read the line,
+for speed. This means that it doesn not respect the value of
+scm-line-incrementors; it assumes that lines are delimited with
+#\newline.
+
+(Note that this is read-line, the function that reads a line of text
+from a port, not readline, the function that reads a line from a
+terminal, providing full editing capabilities.)
+
+** New module (ice-9 getopt-gnu-style): Parse command-line arguments.
+
+This module provides some simple argument parsing. It exports one
+function:
+
+Function: getopt-gnu-style ARG-LS
+ Parse a list of program arguments into an alist of option
+ descriptions.
+
+ Each item in the list of program arguments is examined to see if
+ it meets the syntax of a GNU long-named option. An argument like
+ `--MUMBLE' produces an element of the form (MUMBLE . #t) in the
+ returned alist, where MUMBLE is a keyword object with the same
+ name as the argument. An argument like `--MUMBLE=FROB' produces
+ an element of the form (MUMBLE . FROB), where FROB is a string.
+
+ As a special case, the returned alist also contains a pair whose
+ car is the symbol `rest'. The cdr of this pair is a list
+ containing all the items in the argument list that are not options
+ of the form mentioned above.
+
+ The argument `--' is treated specially: all items in the argument
+ list appearing after such an argument are not examined, and are
+ returned in the special `rest' list.
+
+ This function does not parse normal single-character switches.
+ You will need to parse them out of the `rest' list yourself.
+
+** The read syntax for byte vectors and short vectors has changed.
+
+Instead of #bytes(...), write #y(...).
+
+Instead of #short(...), write #h(...).
+
+This may seem nutty, but, like the other uniform vectors, byte vectors
+and short vectors want to have the same print and read syntax (and,
+more basic, want to have read syntax!). Changing the read syntax to
+use multiple characters after the hash sign breaks with the
+conventions used in R5RS and the conventions used for the other
+uniform vectors. It also introduces complexity in the current reader,
+both on the C and Scheme levels. (The Right solution is probably to
+change the syntax and prototypes for uniform vectors entirely.)
+
+
+** The new module (ice-9 session) provides useful interactive functions.
+
+*** New procedure: (apropos REGEXP OPTION ...)
+
+Display a list of top-level variables whose names match REGEXP, and
+the modules they are imported from. Each OPTION should be one of the
+following symbols:
+
+ value --- Show the value of each matching variable.
+ shadow --- Show bindings shadowed by subsequently imported modules.
+ full --- Same as both `shadow' and `value'.
+
+For example:
+
+ guile> (apropos "trace" 'full)
+ debug: trace #<procedure trace args>
+ debug: untrace #<procedure untrace args>
+ the-scm-module: display-backtrace #<compiled-closure #<primitive-procedure gsubr-apply>>
+ the-scm-module: before-backtrace-hook ()
+ the-scm-module: backtrace #<primitive-procedure backtrace>
+ the-scm-module: after-backtrace-hook ()
+ the-scm-module: has-shown-backtrace-hint? #f
+ guile>
+
+** There are new functions and syntax for working with macros.
+
+Guile implements macros as a special object type. Any variable whose
+top-level binding is a macro object acts as a macro. The macro object
+specifies how the expression should be transformed before evaluation.
+
+*** Macro objects now print in a reasonable way, resembling procedures.
+
+*** New function: (macro? OBJ)
+True iff OBJ is a macro object.
+
+*** New function: (primitive-macro? OBJ)
+Like (macro? OBJ), but true only if OBJ is one of the Guile primitive
+macro transformers, implemented in eval.c rather than Scheme code.
+
+Why do we have this function?
+- For symmetry with procedure? and primitive-procedure?,
+- to allow custom print procedures to tell whether a macro is
+ primitive, and display it differently, and
+- to allow compilers and user-written evaluators to distinguish
+ builtin special forms from user-defined ones, which could be
+ compiled.
+
+*** New function: (macro-type OBJ)
+Return a value indicating what kind of macro OBJ is. Possible return
+values are:
+
+ The symbol `syntax' --- a macro created by procedure->syntax.
+ The symbol `macro' --- a macro created by procedure->macro.
+ The symbol `macro!' --- a macro created by procedure->memoizing-macro.
+ The boolean #f --- if OBJ is not a macro object.
+
+*** New function: (macro-name MACRO)
+Return the name of the macro object MACRO's procedure, as returned by
+procedure-name.
+
+*** New function: (macro-transformer MACRO)
+Return the transformer procedure for MACRO.
+
+*** New syntax: (use-syntax MODULE ... TRANSFORMER)
+
+Specify a new macro expander to use in the current module. Each
+MODULE is a module name, with the same meaning as in the `use-modules'
+form; each named module's exported bindings are added to the current
+top-level environment. TRANSFORMER is an expression evaluated in the
+resulting environment which must yield a procedure to use as the
+module's eval transformer: every expression evaluated in this module
+is passed to this function, and the result passed to the Guile
+interpreter.
+
+*** macro-eval! is removed. Use local-eval instead.
+
+** Some magic has been added to the printer to better handle user
+written printing routines (like record printers, closure printers).
+
+The problem is that these user written routines must have access to
+the current `print-state' to be able to handle fancy things like
+detection of circular references. These print-states have to be
+passed to the builtin printing routines (display, write, etc) to
+properly continue the print chain.
+
+We didn't want to change all existing print code so that it
+explicitly passes thru a print state in addition to a port. Instead,
+we extented the possible values that the builtin printing routines
+accept as a `port'. In addition to a normal port, they now also take
+a pair of a normal port and a print-state. Printing will go to the
+port and the print-state will be used to control the detection of
+circular references, etc. If the builtin function does not care for a
+print-state, it is simply ignored.
+
+User written callbacks are now called with such a pair as their
+`port', but because every function now accepts this pair as a PORT
+argument, you don't have to worry about that. In fact, it is probably
+safest to not check for these pairs.
+
+However, it is sometimes necessary to continue a print chain on a
+different port, for example to get a intermediate string
+representation of the printed value, mangle that string somehow, and
+then to finally print the mangled string. Use the new function
+
+ inherit-print-state OLD-PORT NEW-PORT
+
+for this. It constructs a new `port' that prints to NEW-PORT but
+inherits the print-state of OLD-PORT.
+
+** struct-vtable-offset renamed to vtable-offset-user
+
+** New constants: vtable-index-layout, vtable-index-vtable, vtable-index-printer
+
+** There is now a fourth (optional) argument to make-vtable-vtable and
+ make-struct when constructing new types (vtables). This argument
+ initializes field vtable-index-printer of the vtable.
+
+** The detection of circular references has been extended to structs.
+That is, a structure that -- in the process of being printed -- prints
+itself does not lead to infinite recursion.
+
+** There is now some basic support for fluids. Please read
+"libguile/fluid.h" to find out more. It is accessible from Scheme with
+the following functions and macros:
+
+Function: make-fluid
+
+ Create a new fluid object. Fluids are not special variables or
+ some other extension to the semantics of Scheme, but rather
+ ordinary Scheme objects. You can store them into variables (that
+ are still lexically scoped, of course) or into any other place you
+ like. Every fluid has a initial value of `#f'.
+
+Function: fluid? OBJ
+
+ Test whether OBJ is a fluid.
+
+Function: fluid-ref FLUID
+Function: fluid-set! FLUID VAL
+
+ Access/modify the fluid FLUID. Modifications are only visible
+ within the current dynamic root (that includes threads).
+
+Function: with-fluids* FLUIDS VALUES THUNK
+
+ FLUIDS is a list of fluids and VALUES a corresponding list of
+ values for these fluids. Before THUNK gets called the values are
+ installed in the fluids and the old values of the fluids are
+ saved in the VALUES list. When the flow of control leaves THUNK
+ or reenters it, the values get swapped again. You might think of
+ this as a `safe-fluid-excursion'. Note that the VALUES list is
+ modified by `with-fluids*'.
+
+Macro: with-fluids ((FLUID VALUE) ...) FORM ...
+
+ The same as `with-fluids*' but with a different syntax. It looks
+ just like `let', but both FLUID and VALUE are evaluated. Remember,
+ fluids are not special variables but ordinary objects. FLUID
+ should evaluate to a fluid.
+
+** Changes to system call interfaces:
+
+*** close-port, close-input-port and close-output-port now return a
+boolean instead of an `unspecified' object. #t means that the port
+was successfully closed, while #f means it was already closed. It is
+also now possible for these procedures to raise an exception if an
+error occurs (some errors from write can be delayed until close.)
+
+*** the first argument to chmod, fcntl, ftell and fseek can now be a
+file descriptor.
+
+*** the third argument to fcntl is now optional.
+
+*** the first argument to chown can now be a file descriptor or a port.
+
+*** the argument to stat can now be a port.
+
+*** The following new procedures have been added (most use scsh
+interfaces):
+
+*** procedure: close PORT/FD
+ Similar to close-port (*note close-port: Closing Ports.), but also
+ works on file descriptors. A side effect of closing a file
+ descriptor is that any ports using that file descriptor are moved
+ to a different file descriptor and have their revealed counts set
+ to zero.
+
+*** procedure: port->fdes PORT
+ Returns the integer file descriptor underlying PORT. As a side
+ effect the revealed count of PORT is incremented.
+
+*** procedure: fdes->ports FDES
+ Returns a list of existing ports which have FDES as an underlying
+ file descriptor, without changing their revealed counts.
+
+*** procedure: fdes->inport FDES
+ Returns an existing input port which has FDES as its underlying
+ file descriptor, if one exists, and increments its revealed count.
+ Otherwise, returns a new input port with a revealed count of 1.
+
+*** procedure: fdes->outport FDES
+ Returns an existing output port which has FDES as its underlying
+ file descriptor, if one exists, and increments its revealed count.
+ Otherwise, returns a new output port with a revealed count of 1.
+
+ The next group of procedures perform a `dup2' system call, if NEWFD
+(an integer) is supplied, otherwise a `dup'. The file descriptor to be
+duplicated can be supplied as an integer or contained in a port. The
+type of value returned varies depending on which procedure is used.
+
+ All procedures also have the side effect when performing `dup2' that
+any ports using NEWFD are moved to a different file descriptor and have
+their revealed counts set to zero.
+
+*** procedure: dup->fdes PORT/FD [NEWFD]
+ Returns an integer file descriptor.
+
+*** procedure: dup->inport PORT/FD [NEWFD]
+ Returns a new input port using the new file descriptor.
+
+*** procedure: dup->outport PORT/FD [NEWFD]
+ Returns a new output port using the new file descriptor.
+
+*** procedure: dup PORT/FD [NEWFD]
+ Returns a new port if PORT/FD is a port, with the same mode as the
+ supplied port, otherwise returns an integer file descriptor.
+
+*** procedure: dup->port PORT/FD MODE [NEWFD]
+ Returns a new port using the new file descriptor. MODE supplies a
+ mode string for the port (*note open-file: File Ports.).
+
+*** procedure: setenv NAME VALUE
+ Modifies the environment of the current process, which is also the
+ default environment inherited by child processes.
+
+ If VALUE is `#f', then NAME is removed from the environment.
+ Otherwise, the string NAME=VALUE is added to the environment,
+ replacing any existing string with name matching NAME.
+
+ The return value is unspecified.
+
+*** procedure: truncate-file OBJ SIZE
+ Truncates the file referred to by OBJ to at most SIZE bytes. OBJ
+ can be a string containing a file name or an integer file
+ descriptor or port open for output on the file. The underlying
+ system calls are `truncate' and `ftruncate'.
+
+ The return value is unspecified.
+
+*** procedure: setvbuf PORT MODE [SIZE]
+ Set the buffering mode for PORT. MODE can be:
+ `_IONBF'
+ non-buffered
+
+ `_IOLBF'
+ line buffered
+
+ `_IOFBF'
+ block buffered, using a newly allocated buffer of SIZE bytes.
+ However if SIZE is zero or unspecified, the port will be made
+ non-buffered.
+
+ This procedure should not be used after I/O has been performed with
+ the port.
+
+ Ports are usually block buffered by default, with a default buffer
+ size. Procedures e.g., *Note open-file: File Ports, which accept a
+ mode string allow `0' to be added to request an unbuffered port.
+
+*** procedure: fsync PORT/FD
+ Copies any unwritten data for the specified output file descriptor
+ to disk. If PORT/FD is a port, its buffer is flushed before the
+ underlying file descriptor is fsync'd. The return value is
+ unspecified.
+
+*** procedure: open-fdes PATH FLAGS [MODES]
+ Similar to `open' but returns a file descriptor instead of a port.
+
+*** procedure: execle PATH ENV [ARG] ...
+ Similar to `execl', but the environment of the new process is
+ specified by ENV, which must be a list of strings as returned by
+ the `environ' procedure.
+
+ This procedure is currently implemented using the `execve' system
+ call, but we call it `execle' because of its Scheme calling
+ interface.
+
+*** procedure: strerror ERRNO
+ Returns the Unix error message corresponding to ERRNO, an integer.
+
+*** procedure: primitive-exit [STATUS]
+ Terminate the current process without unwinding the Scheme stack.
+ This is would typically be useful after a fork. The exit status
+ is STATUS if supplied, otherwise zero.
+
+*** procedure: times
+ Returns an object with information about real and processor time.
+ The following procedures accept such an object as an argument and
+ return a selected component:
+
+ `tms:clock'
+ The current real time, expressed as time units relative to an
+ arbitrary base.
+
+ `tms:utime'
+ The CPU time units used by the calling process.
+
+ `tms:stime'
+ The CPU time units used by the system on behalf of the
+ calling process.
+
+ `tms:cutime'
+ The CPU time units used by terminated child processes of the
+ calling process, whose status has been collected (e.g., using
+ `waitpid').
+
+ `tms:cstime'
+ Similarly, the CPU times units used by the system on behalf of
+ terminated child processes.
+
+** Removed: list-length
+** Removed: list-append, list-append!
+** Removed: list-reverse, list-reverse!
+
+** array-map renamed to array-map!
+
+** serial-array-map renamed to serial-array-map!
+
+** catch doesn't take #f as first argument any longer
+
+Previously, it was possible to pass #f instead of a key to `catch'.
+That would cause `catch' to pass a jump buffer object to the procedure
+passed as second argument. The procedure could then use this jump
+buffer objekt as an argument to throw.
+
+This mechanism has been removed since its utility doesn't motivate the
+extra complexity it introduces.
+
+** The `#/' notation for lists now provokes a warning message from Guile.
+This syntax will be removed from Guile in the near future.
+
+To disable the warning message, set the GUILE_HUSH environment
+variable to any non-empty value.
+
+** The newline character now prints as `#\newline', following the
+normal Scheme notation, not `#\nl'.
+
+* Changes to the gh_ interface
+
+** The gh_enter function now takes care of loading the Guile startup files.
+gh_enter works by calling scm_boot_guile; see the remarks below.
+
+** Function: void gh_write (SCM x)
+
+Write the printed representation of the scheme object x to the current
+output port. Corresponds to the scheme level `write'.
+
+** gh_list_length renamed to gh_length.
+
+** vector handling routines
+
+Several major changes. In particular, gh_vector() now resembles
+(vector ...) (with a caveat -- see manual), and gh_make_vector() now
+exists and behaves like (make-vector ...). gh_vset() and gh_vref()
+have been renamed gh_vector_set_x() and gh_vector_ref(). Some missing
+vector-related gh_ functions have been implemented.
+
+** pair and list routines
+
+Implemented several of the R4RS pair and list functions that were
+missing.
+
+** gh_scm2doubles, gh_doubles2scm, gh_doubles2dvect
+
+New function. Converts double arrays back and forth between Scheme
+and C.
+
+* Changes to the scm_ interface
+
+** The function scm_boot_guile now takes care of loading the startup files.
+
+Guile's primary initialization function, scm_boot_guile, now takes
+care of loading `boot-9.scm', in the `ice-9' module, to initialize
+Guile, define the module system, and put together some standard
+bindings. It also loads `init.scm', which is intended to hold
+site-specific initialization code.
+
+Since Guile cannot operate properly until boot-9.scm is loaded, there
+is no reason to separate loading boot-9.scm from Guile's other
+initialization processes.
+
+This job used to be done by scm_compile_shell_switches, which didn't
+make much sense; in particular, it meant that people using Guile for
+non-shell-like applications had to jump through hoops to get Guile
+initialized properly.
+
+** The function scm_compile_shell_switches no longer loads the startup files.
+Now, Guile always loads the startup files, whenever it is initialized;
+see the notes above for scm_boot_guile and scm_load_startup_files.
+
+** Function: scm_load_startup_files
+This new function takes care of loading Guile's initialization file
+(`boot-9.scm'), and the site initialization file, `init.scm'. Since
+this is always called by the Guile initialization process, it's
+probably not too useful to call this yourself, but it's there anyway.
+
+** The semantics of smob marking have changed slightly.
+
+The smob marking function (the `mark' member of the scm_smobfuns
+structure) is no longer responsible for setting the mark bit on the
+smob. The generic smob handling code in the garbage collector will
+set this bit. The mark function need only ensure that any other
+objects the smob refers to get marked.
+
+Note that this change means that the smob's GC8MARK bit is typically
+already set upon entry to the mark function. Thus, marking functions
+which look like this:
+
+ {
+ if (SCM_GC8MARKP (ptr))
+ return SCM_BOOL_F;
+ SCM_SETGC8MARK (ptr);
+ ... mark objects to which the smob refers ...
+ }
+
+are now incorrect, since they will return early, and fail to mark any
+other objects the smob refers to. Some code in the Guile library used
+to work this way.
+
+** The semantics of the I/O port functions in scm_ptobfuns have changed.
+
+If you have implemented your own I/O port type, by writing the
+functions required by the scm_ptobfuns and then calling scm_newptob,
+you will need to change your functions slightly.
+
+The functions in a scm_ptobfuns structure now expect the port itself
+as their argument; they used to expect the `stream' member of the
+port's scm_port_table structure. This allows functions in an
+scm_ptobfuns structure to easily access the port's cell (and any flags
+it its CAR), and the port's scm_port_table structure.
+
+Guile now passes the I/O port itself as the `port' argument in the
+following scm_ptobfuns functions:
+
+ int (*free) (SCM port);
+ int (*fputc) (int, SCM port);
+ int (*fputs) (char *, SCM port);
+ scm_sizet (*fwrite) SCM_P ((char *ptr,
+ scm_sizet size,
+ scm_sizet nitems,
+ SCM port));
+ int (*fflush) (SCM port);
+ int (*fgetc) (SCM port);
+ int (*fclose) (SCM port);
+
+The interfaces to the `mark', `print', `equalp', and `fgets' methods
+are unchanged.
+
+If you have existing code which defines its own port types, it is easy
+to convert your code to the new interface; simply apply SCM_STREAM to
+the port argument to yield the value you code used to expect.
+
+Note that since both the port and the stream have the same type in the
+C code --- they are both SCM values --- the C compiler will not remind
+you if you forget to update your scm_ptobfuns functions.
+
+
+** Function: int scm_internal_select (int fds,
+ SELECT_TYPE *rfds,
+ SELECT_TYPE *wfds,
+ SELECT_TYPE *efds,
+ struct timeval *timeout);
+
+This is a replacement for the `select' function provided by the OS.
+It enables I/O blocking and sleeping to happen for one cooperative
+thread without blocking other threads. It also avoids busy-loops in
+these situations. It is intended that all I/O blocking and sleeping
+will finally go through this function. Currently, this function is
+only available on systems providing `gettimeofday' and `select'.
+
+** Function: SCM scm_internal_stack_catch (SCM tag,
+ scm_catch_body_t body,
+ void *body_data,
+ scm_catch_handler_t handler,
+ void *handler_data)
+
+A new sibling to the other two C level `catch' functions
+scm_internal_catch and scm_internal_lazy_catch. Use it if you want
+the stack to be saved automatically into the variable `the-last-stack'
+(scm_the_last_stack_var) on error. This is necessary if you want to
+use advanced error reporting, such as calling scm_display_error and
+scm_display_backtrace. (They both take a stack object as argument.)
+
+** Function: SCM scm_spawn_thread (scm_catch_body_t body,
+ void *body_data,
+ scm_catch_handler_t handler,
+ void *handler_data)
+
+Spawns a new thread. It does a job similar to
+scm_call_with_new_thread but takes arguments more suitable when
+spawning threads from application C code.
+
+** The hook scm_error_callback has been removed. It was originally
+intended as a way for the user to install his own error handler. But
+that method works badly since it intervenes between throw and catch,
+thereby changing the semantics of expressions like (catch #t ...).
+The correct way to do it is to use one of the C level catch functions
+in throw.c: scm_internal_catch/lazy_catch/stack_catch.
+
+** Removed functions:
+
+scm_obj_length, scm_list_length, scm_list_append, scm_list_append_x,
+scm_list_reverse, scm_list_reverse_x
+
+** New macros: SCM_LISTn where n is one of the integers 0-9.
+
+These can be used for pretty list creation from C. The idea is taken
+from Erick Gallesio's STk.
+
+** scm_array_map renamed to scm_array_map_x
+
+** mbstrings are now removed
+
+This means that the type codes scm_tc7_mb_string and
+scm_tc7_mb_substring has been removed.
+
+** scm_gen_putc, scm_gen_puts, scm_gen_write, and scm_gen_getc have changed.
+
+Since we no longer support multi-byte strings, these I/O functions
+have been simplified, and renamed. Here are their old names, and
+their new names and arguments:
+
+scm_gen_putc -> void scm_putc (int c, SCM port);
+scm_gen_puts -> void scm_puts (char *s, SCM port);
+scm_gen_write -> void scm_lfwrite (char *ptr, scm_sizet size, SCM port);
+scm_gen_getc -> void scm_getc (SCM port);
+
+
+** The macros SCM_TYP7D and SCM_TYP7SD has been removed.
+
+** The macro SCM_TYP7S has taken the role of the old SCM_TYP7D
+
+SCM_TYP7S now masks away the bit which distinguishes substrings from
+strings.
+
+** scm_catch_body_t: Backward incompatible change!
+
+Body functions to scm_internal_catch and friends do not any longer
+take a second argument. This is because it is no longer possible to
+pass a #f arg to catch.
+
+** Calls to scm_protect_object and scm_unprotect now nest properly.
+
+The function scm_protect_object protects its argument from being freed
+by the garbage collector. scm_unprotect_object removes that
+protection.
+
+These functions now nest properly. That is, for every object O, there
+is a counter which scm_protect_object(O) increments and
+scm_unprotect_object(O) decrements, if the counter is greater than
+zero. Every object's counter is zero when it is first created. If an
+object's counter is greater than zero, the garbage collector will not
+reclaim its storage.
+
+This allows you to use scm_protect_object in your code without
+worrying that some other function you call will call
+scm_unprotect_object, and allow it to be freed. Assuming that the
+functions you call are well-behaved, and unprotect only those objects
+they protect, you can follow the same rule and have confidence that
+objects will be freed only at appropriate times.
+
+\f
+Changes in Guile 1.2 (released Tuesday, June 24 1997):
+
+* Changes to the distribution
+
+** Nightly snapshots are now available from ftp.red-bean.com.
+The old server, ftp.cyclic.com, has been relinquished to its rightful
+owner.
+
+Nightly snapshots of the Guile development sources are now available via
+anonymous FTP from ftp.red-bean.com, as /pub/guile/guile-snap.tar.gz.
+
+Via the web, that's: ftp://ftp.red-bean.com/pub/guile/guile-snap.tar.gz
+For getit, that's: ftp.red-bean.com:/pub/guile/guile-snap.tar.gz
+
+** To run Guile without installing it, the procedure has changed a bit.
+
+If you used a separate build directory to compile Guile, you'll need
+to include the build directory in SCHEME_LOAD_PATH, as well as the
+source directory. See the `INSTALL' file for examples.
+
+* Changes to the procedure for linking libguile with your programs
+
+** The standard Guile load path for Scheme code now includes
+$(datadir)/guile (usually /usr/local/share/guile). This means that
+you can install your own Scheme files there, and Guile will find them.
+(Previous versions of Guile only checked a directory whose name
+contained the Guile version number, so you had to re-install or move
+your Scheme sources each time you installed a fresh version of Guile.)
+
+The load path also includes $(datadir)/guile/site; we recommend
+putting individual Scheme files there. If you want to install a
+package with multiple source files, create a directory for them under
+$(datadir)/guile.
+
+** Guile 1.2 will now use the Rx regular expression library, if it is
+installed on your system. When you are linking libguile into your own
+programs, this means you will have to link against -lguile, -lqt (if
+you configured Guile with thread support), and -lrx.
If you are using autoconf to generate configuration scripts for your
application, the following lines should suffice to add the appropriate
AC_CHECK_LIB(qt, main)
AC_CHECK_LIB(guile, scm_shell)
+The Guile 1.2 distribution does not contain sources for the Rx
+library, as Guile 1.0 did. If you want to use Rx, you'll need to
+retrieve it from a GNU FTP site and install it separately.
+
* Changes to Scheme functions and syntax
+** The dynamic linking features of Guile are now enabled by default.
+You can disable them by giving the `--disable-dynamic-linking' option
+to configure.
+
+ (dynamic-link FILENAME)
+
+ Find the object file denoted by FILENAME (a string) and link it
+ into the running Guile application. When everything works out,
+ return a Scheme object suitable for representing the linked object
+ file. Otherwise an error is thrown. How object files are
+ searched is system dependent.
+
+ (dynamic-object? VAL)
+
+ Determine whether VAL represents a dynamically linked object file.
+
+ (dynamic-unlink DYNOBJ)
+
+ Unlink the indicated object file from the application. DYNOBJ
+ should be one of the values returned by `dynamic-link'.
+
+ (dynamic-func FUNCTION DYNOBJ)
+
+ Search the C function indicated by FUNCTION (a string or symbol)
+ in DYNOBJ and return some Scheme object that can later be used
+ with `dynamic-call' to actually call this function. Right now,
+ these Scheme objects are formed by casting the address of the
+ function to `long' and converting this number to its Scheme
+ representation.
+
+ (dynamic-call FUNCTION DYNOBJ)
+
+ Call the C function indicated by FUNCTION and DYNOBJ. The
+ function is passed no arguments and its return value is ignored.
+ When FUNCTION is something returned by `dynamic-func', call that
+ function and ignore DYNOBJ. When FUNCTION is a string (or symbol,
+ etc.), look it up in DYNOBJ; this is equivalent to
+
+ (dynamic-call (dynamic-func FUNCTION DYNOBJ) #f)
+
+ Interrupts are deferred while the C function is executing (with
+ SCM_DEFER_INTS/SCM_ALLOW_INTS).
+
+ (dynamic-args-call FUNCTION DYNOBJ ARGS)
+
+ Call the C function indicated by FUNCTION and DYNOBJ, but pass it
+ some arguments and return its return value. The C function is
+ expected to take two arguments and return an `int', just like
+ `main':
+
+ int c_func (int argc, char **argv);
+
+ ARGS must be a list of strings and is converted into an array of
+ `char *'. The array is passed in ARGV and its size in ARGC. The
+ return value is converted to a Scheme number and returned from the
+ call to `dynamic-args-call'.
+
+When dynamic linking is disabled or not supported on your system,
+the above functions throw errors, but they are still available.
+
+Here is a small example that works on GNU/Linux:
+
+ (define libc-obj (dynamic-link "libc.so"))
+ (dynamic-args-call 'rand libc-obj '())
+
+See the file `libguile/DYNAMIC-LINKING' for additional comments.
+
** The #/ syntax for module names is depreciated, and will be removed
in a future version of Guile. Instead of
The latter syntax is more consistent with existing Lisp practice.
+** Guile now does fancier printing of structures. Structures are the
+underlying implementation for records, which in turn are used to
+implement modules, so all of these object now print differently and in
+a more informative way.
+
+The Scheme printer will examine the builtin variable *struct-printer*
+whenever it needs to print a structure object. When this variable is
+not `#f' it is deemed to be a procedure and will be applied to the
+structure object and the output port. When *struct-printer* is `#f'
+or the procedure return `#f' the structure object will be printed in
+the boring #<struct 80458270> form.
+
+This hook is used by some routines in ice-9/boot-9.scm to implement
+type specific printing routines. Please read the comments there about
+"printing structs".
+
+One of the more specific uses of structs are records. The printing
+procedure that could be passed to MAKE-RECORD-TYPE is now actually
+called. It should behave like a *struct-printer* procedure (described
+above).
+
** Guile now supports a new R4RS-compliant syntax for keywords. A
token of the form #:NAME, where NAME has the same syntax as a Scheme
symbol, is the external representation of the keyword named NAME.
functions for matching regular expressions, based on the Rx library.
In Guile 1.1, the Guile/Rx interface was removed to simplify the
distribution, and thus Guile had no regular expression support. Guile
-1.2 now adds back the most commonly used functions, and supports all
-of SCSH's regular expression functions. They are:
+1.2 again supports the most commonly used functions, and supports all
+of SCSH's regular expression functions.
+
+If your system does not include a POSIX regular expression library,
+and you have not linked Guile with a third-party regexp library such as
+Rx, these functions will not be available. You can tell whether your
+Guile installation includes regular expression support by checking
+whether the `*features*' list includes the `regex' symbol.
-*** [[get docs from Tim?]]
+*** regexp functions
+
+By default, Guile supports POSIX extended regular expressions. That
+means that the characters `(', `)', `+' and `?' are special, and must
+be escaped if you wish to match the literal characters.
+
+This regular expression interface was modeled after that implemented
+by SCSH, the Scheme Shell. It is intended to be upwardly compatible
+with SCSH regular expressions.
+
+**** Function: string-match PATTERN STR [START]
+ Compile the string PATTERN into a regular expression and compare
+ it with STR. The optional numeric argument START specifies the
+ position of STR at which to begin matching.
+
+ `string-match' returns a "match structure" which describes what,
+ if anything, was matched by the regular expression. *Note Match
+ Structures::. If STR does not match PATTERN at all,
+ `string-match' returns `#f'.
+
+ Each time `string-match' is called, it must compile its PATTERN
+argument into a regular expression structure. This operation is
+expensive, which makes `string-match' inefficient if the same regular
+expression is used several times (for example, in a loop). For better
+performance, you can compile a regular expression in advance and then
+match strings against the compiled regexp.
+
+**** Function: make-regexp STR [FLAGS]
+ Compile the regular expression described by STR, and return the
+ compiled regexp structure. If STR does not describe a legal
+ regular expression, `make-regexp' throws a
+ `regular-expression-syntax' error.
+
+ FLAGS may be the bitwise-or of one or more of the following:
+
+**** Constant: regexp/extended
+ Use POSIX Extended Regular Expression syntax when interpreting
+ STR. If not set, POSIX Basic Regular Expression syntax is used.
+ If the FLAGS argument is omitted, we assume regexp/extended.
+
+**** Constant: regexp/icase
+ Do not differentiate case. Subsequent searches using the
+ returned regular expression will be case insensitive.
+
+**** Constant: regexp/newline
+ Match-any-character operators don't match a newline.
+
+ A non-matching list ([^...]) not containing a newline matches a
+ newline.
+
+ Match-beginning-of-line operator (^) matches the empty string
+ immediately after a newline, regardless of whether the FLAGS
+ passed to regexp-exec contain regexp/notbol.
+
+ Match-end-of-line operator ($) matches the empty string
+ immediately before a newline, regardless of whether the FLAGS
+ passed to regexp-exec contain regexp/noteol.
+
+**** Function: regexp-exec REGEXP STR [START [FLAGS]]
+ Match the compiled regular expression REGEXP against `str'. If
+ the optional integer START argument is provided, begin matching
+ from that position in the string. Return a match structure
+ describing the results of the match, or `#f' if no match could be
+ found.
+
+ FLAGS may be the bitwise-or of one or more of the following:
+
+**** Constant: regexp/notbol
+ The match-beginning-of-line operator always fails to match (but
+ see the compilation flag regexp/newline above) This flag may be
+ used when different portions of a string are passed to
+ regexp-exec and the beginning of the string should not be
+ interpreted as the beginning of the line.
+
+**** Constant: regexp/noteol
+ The match-end-of-line operator always fails to match (but see the
+ compilation flag regexp/newline above)
+
+**** Function: regexp? OBJ
+ Return `#t' if OBJ is a compiled regular expression, or `#f'
+ otherwise.
+
+ Regular expressions are commonly used to find patterns in one string
+and replace them with the contents of another string.
+
+**** Function: regexp-substitute PORT MATCH [ITEM...]
+ Write to the output port PORT selected contents of the match
+ structure MATCH. Each ITEM specifies what should be written, and
+ may be one of the following arguments:
+
+ * A string. String arguments are written out verbatim.
+
+ * An integer. The submatch with that number is written.
+
+ * The symbol `pre'. The portion of the matched string preceding
+ the regexp match is written.
+
+ * The symbol `post'. The portion of the matched string
+ following the regexp match is written.
+
+ PORT may be `#f', in which case nothing is written; instead,
+ `regexp-substitute' constructs a string from the specified ITEMs
+ and returns that.
+
+**** Function: regexp-substitute/global PORT REGEXP TARGET [ITEM...]
+ Similar to `regexp-substitute', but can be used to perform global
+ substitutions on STR. Instead of taking a match structure as an
+ argument, `regexp-substitute/global' takes two string arguments: a
+ REGEXP string describing a regular expression, and a TARGET string
+ which should be matched against this regular expression.
+
+ Each ITEM behaves as in REGEXP-SUBSTITUTE, with the following
+ exceptions:
+
+ * A function may be supplied. When this function is called, it
+ will be passed one argument: a match structure for a given
+ regular expression match. It should return a string to be
+ written out to PORT.
+
+ * The `post' symbol causes `regexp-substitute/global' to recurse
+ on the unmatched portion of STR. This *must* be supplied in
+ order to perform global search-and-replace on STR; if it is
+ not present among the ITEMs, then `regexp-substitute/global'
+ will return after processing a single match.
+
+*** Match Structures
+
+ A "match structure" is the object returned by `string-match' and
+`regexp-exec'. It describes which portion of a string, if any, matched
+the given regular expression. Match structures include: a reference to
+the string that was checked for matches; the starting and ending
+positions of the regexp match; and, if the regexp included any
+parenthesized subexpressions, the starting and ending positions of each
+submatch.
+
+ In each of the regexp match functions described below, the `match'
+argument must be a match structure returned by a previous call to
+`string-match' or `regexp-exec'. Most of these functions return some
+information about the original target string that was matched against a
+regular expression; we will call that string TARGET for easy reference.
+
+**** Function: regexp-match? OBJ
+ Return `#t' if OBJ is a match structure returned by a previous
+ call to `regexp-exec', or `#f' otherwise.
+
+**** Function: match:substring MATCH [N]
+ Return the portion of TARGET matched by subexpression number N.
+ Submatch 0 (the default) represents the entire regexp match. If
+ the regular expression as a whole matched, but the subexpression
+ number N did not match, return `#f'.
+
+**** Function: match:start MATCH [N]
+ Return the starting position of submatch number N.
+
+**** Function: match:end MATCH [N]
+ Return the ending position of submatch number N.
+
+**** Function: match:prefix MATCH
+ Return the unmatched portion of TARGET preceding the regexp match.
+
+**** Function: match:suffix MATCH
+ Return the unmatched portion of TARGET following the regexp match.
+
+**** Function: match:count MATCH
+ Return the number of parenthesized subexpressions from MATCH.
+ Note that the entire regular expression match itself counts as a
+ subexpression, and failed submatches are included in the count.
+
+**** Function: match:string MATCH
+ Return the original TARGET string.
+
+*** Backslash Escapes
+
+ Sometimes you will want a regexp to match characters like `*' or `$'
+exactly. For example, to check whether a particular string represents
+a menu entry from an Info node, it would be useful to match it against
+a regexp like `^* [^:]*::'. However, this won't work; because the
+asterisk is a metacharacter, it won't match the `*' at the beginning of
+the string. In this case, we want to make the first asterisk un-magic.
+
+ You can do this by preceding the metacharacter with a backslash
+character `\'. (This is also called "quoting" the metacharacter, and
+is known as a "backslash escape".) When Guile sees a backslash in a
+regular expression, it considers the following glyph to be an ordinary
+character, no matter what special meaning it would ordinarily have.
+Therefore, we can make the above example work by changing the regexp to
+`^\* [^:]*::'. The `\*' sequence tells the regular expression engine
+to match only a single asterisk in the target string.
+
+ Since the backslash is itself a metacharacter, you may force a
+regexp to match a backslash in the target string by preceding the
+backslash with itself. For example, to find variable references in a
+TeX program, you might want to find occurrences of the string `\let\'
+followed by any number of alphabetic characters. The regular expression
+`\\let\\[A-Za-z]*' would do this: the double backslashes in the regexp
+each match a single backslash in the target string.
+
+**** Function: regexp-quote STR
+ Quote each special character found in STR with a backslash, and
+ return the resulting string.
+
+ *Very important:* Using backslash escapes in Guile source code (as
+in Emacs Lisp or C) can be tricky, because the backslash character has
+special meaning for the Guile reader. For example, if Guile encounters
+the character sequence `\n' in the middle of a string while processing
+Scheme code, it replaces those characters with a newline character.
+Similarly, the character sequence `\t' is replaced by a horizontal tab.
+Several of these "escape sequences" are processed by the Guile reader
+before your code is executed. Unrecognized escape sequences are
+ignored: if the characters `\*' appear in a string, they will be
+translated to the single character `*'.
+
+ This translation is obviously undesirable for regular expressions,
+since we want to be able to include backslashes in a string in order to
+escape regexp metacharacters. Therefore, to make sure that a backslash
+is preserved in a string in your Guile program, you must use *two*
+consecutive backslashes:
+
+ (define Info-menu-entry-pattern (make-regexp "^\\* [^:]*"))
+
+ The string in this example is preprocessed by the Guile reader before
+any code is executed. The resulting argument to `make-regexp' is the
+string `^\* [^:]*', which is what we really want.
+
+ This also means that in order to write a regular expression that
+matches a single backslash character, the regular expression string in
+the source code must include *four* backslashes. Each consecutive pair
+of backslashes gets translated by the Guile reader to a single
+backslash, and the resulting double-backslash is interpreted by the
+regexp engine as matching a single backslash character. Hence:
+
+ (define tex-variable-pattern (make-regexp "\\\\let\\\\=[A-Za-z]*"))
+
+ The reason for the unwieldiness of this syntax is historical. Both
+regular expression pattern matchers and Unix string processing systems
+have traditionally used backslashes with the special meanings described
+above. The POSIX regular expression specification and ANSI C standard
+both require these semantics. Attempting to abandon either convention
+would cause other kinds of compatibility problems, possibly more severe
+ones. Therefore, without extending the Scheme reader to support
+strings with different quoting conventions (an ungainly and confusing
+extension when implemented in other languages), we must adhere to this
+cumbersome escape syntax.
* Changes to the gh_ interface
** The value returned by `raise' is now unspecified. It throws an exception
if an error occurs.
-** A new procedure `sigaction' can be used to install signal handlers
+*** A new procedure `sigaction' can be used to install signal handlers
(sigaction signum [action] [flags])
provide solutions to the problem of consistent access to data
structures.
+*** A new procedure `flush-all-ports' is equivalent to running
+`force-output' on every port open for output.
+
+** Guile now provides information on how it was built, via the new
+global variable, %guile-build-info. This variable records the values
+of the standard GNU makefile directory variables as an assocation
+list, mapping variable names (symbols) onto directory paths (strings).
+For example, to find out where the Guile link libraries were
+installed, you can say:
+
+guile -c "(display (assq-ref %guile-build-info 'libdir)) (newline)"
+
+
+* Changes to the scm_ interface
+
+** The new function scm_handle_by_message_noexit is just like the
+existing scm_handle_by_message function, except that it doesn't call
+exit to terminate the process. Instead, it prints a message and just
+returns #f. This might be a more appropriate catch-all handler for
+new dynamic roots and threads.
+
\f
-Changes in Guile 1.1 (Fri May 16 1997):
+Changes in Guile 1.1 (released Friday, May 16 1997):
* Changes to the distribution.
date, or incomplete. As soon as we have current documentation, we
will distribute it.
+
+
* Changes to the stand-alone interpreter
** guile now accepts command-line arguments compatible with SCSH, Olin
To use the scm_shell function, first initialize any guile modules
linked into your application, and then call scm_shell with the values
-of ARGC and ARGV your `main' function received. scm_shell will adding
+of ARGC and ARGV your `main' function received. scm_shell will add
any SCSH-style meta-arguments from the top of the script file to the
argument vector, and then process the command-line arguments. This
generally means loading a script file or starting up an interactive
to a Scheme port object.
** The new function `scm_set_program_arguments' allows C code to set
-the value teruturned by the Scheme `program-arguments' function.
+the value returned by the Scheme `program-arguments' function.
\f
Older changes:
HCoop / bpt / guile.git / blobdiff