\f
Changes since Guile 1.3:
-* Changes to the stand-alone interpreter
-
-** Command-line editing is enhanced.
-
-If you have a sufficiently recent version of the GNU readline library
-installed on your system, Guile will use it to read expressions
-interactively.
+* Changes to the distribution
-You can now use the readline-options interface to control readline's
-behavior. You can now control the readline library's behavior by
-changing the options listed below.
+** Readline support is no longer included with Guile by default.
- (readline-enable 'history-file)
- Tell readline to record your commands in a file when you exit
- Guile, and restore them when you restart Guile. By default, Guile
- saves commands to `$HOME/.guile_history', but if the
- `GUILE_HISTORY' environment variable is set, Guile will use its
- value as the name of the history file.
+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.
- If Guile is unable to save or restore lines from the history file,
- the operation is simply not performed; the user is not notified.
+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.
- (readline-disable 'history-file)
- Tell Guile not to save or restore command history.
+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.
- (readline-set! history-length N)
- Tell Guile to save at most N lines of command history.
+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.
- (readline-set! bounce-parens N)
- Tell Guile to indicate the matching opening parenthesis when you
- type a closing parenthesis, by resting the cursor on it for N
- milliseconds. If N is zero, do not highlight opening parethesis.
+* Changes to the stand-alone interpreter
** All builtins now print as primitives.
Previously builtin procedures not belonging to the fundamental subr
* Changes to Scheme functions and syntax
+** 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.
+
+** 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
HCoop / bpt / guile.git / blobdiff