Changeset 34685 in project


Ignore:
Timestamp:
10/09/17 19:13:05 (9 days ago)
Author:
sjamaan
Message:

man/5: Move information from "extensions to the standard" into "Module scheme"

Fixes (mostly) #1314

Location:
wiki/man/5
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • wiki/man/5/Module scheme

    r34257 r34685  
    170170and eq? work on procedures.
    171171
     172As an extension to R5RS, CHICKEN also supports "extended" DSSSL style
     173parameter lists, which allows embedded special keywords.  Such a
     174keyword gives a special meaning to the {{<formal>}} it precedes.
     175DSSSL parameter lists are defined by the following grammar:
     176
     177 <parameter-list> ==> <required-parameter>*
     178                      [#!optional <optional-parameter>*]
     179                      [#!rest <rest-parameter>]
     180                      [#!key <keyword-parameter>*]
     181 <required-parameter> ==> <ident>
     182 <optional-parameter> ==> <ident>
     183                          | (<ident> <initializer>)
     184 <rest-parameter> ==> <ident>
     185 <keyword-parameter> ==> <ident>
     186                         | (<ident> <initializer>)
     187 <initializer> ==> <expr>
     188
     189When a procedure is applied to a list of arguments, the parameters and arguments are processed from left to right as follows:
     190
     191* Required-parameters are bound to successive arguments starting with the first argument. It shall be an error if there are fewer arguments than required-parameters.
     192* Next, the optional-parameters are bound with the remaining arguments. If there are fewer arguments than optional-parameters, then the remaining optional-parameters are bound to the result of the evaluation of their corresponding <initializer>, if one was specified, otherwise {{#f}}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound.
     193* If there is a rest-parameter, then it is bound to a list containing all the remaining arguments left over after the argument bindings with required-parameters and optional-parameters have been made.
     194* If {{#!key}} was specified in the parameter-list, there should be an even number of remaining arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the parameter name, and the second member is the corresponding value. If the same keyword occurs more than once in the list of arguments, then the corresponding value of the first keyword is the binding value. If there is no argument for a particular keyword-parameter, then the variable is bound to the result of evaluating <initializer>, if one was specified, otherwise {{#f}}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound.
     195
     196Needing a special mention is the close relationship between the
     197rest-parameter and possible keyword-parameters.  Declaring a
     198rest-parameter binds up all remaining arguments in a list, as
     199described above. These same remaining arguments are also used for
     200attempted matches with declared keyword-parameters, as described
     201above, in which case a matching keyword-parameter binds to the
     202corresponding value argument at the same time that both the keyword
     203and value arguments are added to the rest parameter list.  Note that
     204for efficiency reasons, the keyword-parameter matching does nothing
     205more than simply attempt to match with pairs that may exist in the
     206remaining arguments.  Extra arguments that don't match are simply
     207unused and forgotten if no rest-parameter has been declared.  Because
     208of this, the caller of a procedure containing one or more
     209keyword-parameters cannot rely on any kind of system error to report
     210wrong keywords being passed in.
     211
     212It shall be an error for an {{<ident>}} to appear more than once in a
     213parameter-list.
     214
     215If there is no rest-parameter and no keyword-parameters in the parameter-list, then it shall be an error for any extra arguments to be passed to the procedure.
     216
     217
     218Example:
     219
     220 ((lambda x x) 3 4 5 6)       => (3 4 5 6)
     221 ((lambda (x y #!rest z) z)
     222  3 4 5 6)                    => (5 6)
     223 ((lambda (x y #!optional z #!rest r #!key i (j 1))
     224     (list x y z i: i j: j))
     225  3 4 5 i: 6 i: 7)            => (3 4 5 i: 6 j: 1)
     226
     227
     228
    172229==== Conditionals
    173230
     
    205262 (set! x 4)                      ===>  unspecified
    206263 (+ x 1)                         ===>  5
     264
     265As an extension to R5RS, {{set!}} for unbound toplevel variables is
     266allowed.  Also, {{set! (PROCEDURE ...) ...)}} is supported, as CHICKEN
     267implements [[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
    207268
    208269=== Derived expression types
     
    257318       (else #f))                 ===>  2
    258319
     320
     321As an extension to R5RS, CHICKEN also supports the
     322[[http://srfi.schemers.org/srfi-61|SRFI-61]] syntax:
     323
     324 (<generator> <guard> => <expression>)
     325
     326In this situation, {{generator}} is ''always'' evaluated.  Its
     327resulting value(s) are used as argument(s) for the {{guard}}
     328procedure.  Finally, if {{guard}} returns a non-{{#f}} value, the
     329{{expression}} is evaluated by calling it with the result of
     330{{guard}}.  Otherwise, evaluation procedes to the next clause.
     331
    259332<macro>(case <key> <clause[1]> <clause[2]> ...)</macro><br>
    260333
     
    442515        (display (+ 4 1)))                ===>  unspecified
    443516   and prints  4 plus 1 equals 5
     517
     518As an extension to R5RS, CHICKEN also allows {{(begin)}} without body
     519expressions in any context, not just at toplevel.  This simply
     520evaluates to the unspecified value.
     521
    444522
    445523==== Iteration
     
    914992   (lambda (<formals>) <body>)).
    915993
     994<macro>(define <variable>)</macro>
     995
     996This form is a CHICKEN extension to R5RS, and is equivalent to
     997
     998 (define <variable> (void))
     999
    9161000<macro>(define (<variable> . <formal>) <body>)</macro><br>
    9171001
     
    9201004 (define <variable>
    9211005   (lambda <formal> <body>)).
     1006
     1007<macro>(define ((<variable> <formal> ...) ...) <body>)</macro><br>
     1008
     1009As an extension to R5RS, CHICKEN allows ''curried'' definitions, where
     1010the variable name may also be a list specifying a name and a nested
     1011lambda list. For example,
     1012
     1013 (define ((make-adder x) y) (+ x y))
     1014
     1015is equivalent to
     1016
     1017 (define (make-adder x) (lambda (y) (+ x y))).
     1018
     1019This type of curried definition can be nested arbitrarily and combined
     1020with dotted tail notation or DSSSL keywords.
    9221021
    9231022==== Top level definitions
     
    9341033definition will bind <variable> to a new location before performing
    9351034the assignment, whereas it would be an error to perform a set! on an
    936 unbound variable.
     1035unbound variable in standard Scheme.  In CHICKEN, {{set!}} at toplevel
     1036has the same effect as a definition, unless inside a module, in which
     1037case it is an error.
    9371038
    9381039 (define add3
     
    9451046possible variables are bound to locations, most of which contain
    9461047undefined values. Top level definitions in such an implementation are
    947 truly equivalent to assignments.
     1048truly equivalent to assignments.  In CHICKEN, attempting to evaluate
     1049an unbound identifier will result in an error, but you ''can'' use
     1050{{set!}} to bind an initial value to it.
    9481051
    9491052==== Internal definitions
     
    9801083equivalent to the sequence of definitions that form the body of the
    9811084begin.
     1085
     1086CHICKEN extends the R5RS semantics by allowing internal definitions
     1087everywhere, and not only at the beginning of a body. A set of internal
     1088definitions is equivalent to a {{letrec}} form enclosing all following
     1089expressions in the body:
     1090
     1091 (let ((foo 123))
     1092   (bar)
     1093   (define foo 456)
     1094   (baz foo) )
     1095
     1096expands into
     1097
     1098 (let ((foo 123))
     1099   (bar)
     1100   (letrec ((foo 456))
     1101     (baz foo) ) )
     1102
     1103Local sequences of {{define-syntax}} forms are translated into
     1104equivalent {{letrec-syntax}} forms that enclose the following forms as
     1105the body of the expression.
     1106
    9821107
    9831108=== Syntax definitions
     
    18131938==== Numerical input and output
    18141939
    1815 <procedure>(number->string z)</procedure><br>
    1816 <procedure>(number->string z radix)</procedure><br>
    1817 
    1818 Radix must be an exact integer, either 2, 8, 10, or 16. If omitted, radix
    1819 defaults to 10. The procedure number->string takes a number and a
    1820 radix and returns as a string an external representation of the given
    1821 number in the given radix such that
     1940<procedure>(number->string z [radix])</procedure>
     1941
     1942Radix must be an exact integer.  The R5RS standard only requires
     1943implementations to support 2, 8, 10, or 16, but CHICKEN allows any
     1944radix between 2 and 36, inclusive.  If omitted, radix defaults to
     194510. The procedure number->string takes a number and a radix and
     1946returns as a string an external representation of the given number in
     1947the given radix such that
    18221948
    18231949 (let ((number number)
     
    18501976case allows for infinities, NaNs, and non-flonum representations.
    18511977
     1978As an extension to R5RS, CHICKEN supports reading and writing the
     1979special IEEE floating-point numbers ''+nan'', ''+inf'' and ''-inf'',
     1980as well as negative zero.
     1981
    18521982<procedure>(string->number string)</procedure><br>
    18531983<procedure>(string->number string radix)</procedure><br>
    18541984
    18551985Returns a number of the maximally precise representation expressed by
    1856 the given string. Radix must be an exact integer, either 2, 8, 10, or
    1857 16. If supplied, radix is a default radix that may be overridden by an
    1858 explicit radix prefix in string (e.g. "#o177"). If radix is not
    1859 supplied, then the default radix is 10. If string is not a
    1860 syntactically valid notation for a number, then string->number
    1861 returns #f.
     1986the given string.  Radix must be an exact integer.  The R5RS standard
     1987only requires implementations to support 2, 8, 10, or 16, but CHICKEN
     1988allows any radix between 2 and 36, inclusive.  If supplied, radix is a
     1989default radix that may be overridden by an explicit radix prefix in
     1990string (e.g. "#o177"). If radix is not supplied, then the default
     1991radix is 10. If string is not a syntactically valid notation for a
     1992number, then string->number returns #f.
    18621993
    18631994 (string->number "100")                ===>  100
     
    18782009numbers are integers, then string->number may return #f whenever a
    18792010decimal point is used.
     2011
     2012As an extension to R5RS, CHICKEN supports reading and writing the
     2013special IEEE floating-point numbers ''+nan'', ''+inf'' and ''-inf'',
     2014as well as negative zero.
    18802015
    18812016=== Other data types
     
    28242959
    28252960*   Calling force on an object that is not a promise may simply return
    2826     the object.
     2961    the object (this is the case in CHICKEN).
    28272962
    28282963*   It may be the case that there is no means by which a promise can be
     
    28342969    (pair? (delay (cons 1 2)))          ===>  unspecified
    28352970
     2971    In CHICKEN, promises are separate objects, so the above expressions
     2972    will both evaluate to {{#f}}.
     2973
    28362974*   Some implementations may implement "implicit forcing," where the
    28372975    value of a promise is forced by primitive procedures like cdr and
     
    28392977
    28402978    (+ (delay (* 3 7)) 13)          ===>  34
     2979
     2980    This is '''not''' the case in CHICKEN.
     2981
    28412982
    28422983<procedure>(call-with-current-continuation proc)</procedure><br>
     
    29983139
    29993140The effect of using a captured continuation to enter or exit the
    3000 dynamic extent of a call to before or after is undefined.
     3141dynamic extent of a call to before or after is undefined.  However,
     3142in CHICKEN it is safe to do this, and they will execute in the outer
     3143dynamic context of the {{dynamic-wind}} form.
    30013144
    30023145 (let ((path '())
     
    30453188common among Scheme implementations.
    30463189
    3047 <procedure>(scheme-report-environment version)</procedure><br>
    3048 <procedure>(null-environment version)</procedure><br>
     3190<procedure>(scheme-report-environment version [mutable])</procedure><br>
     3191<procedure>(null-environment version [mutable])</procedure><br>
    30493192
    30503193Version must be either the exact integer 4 or 5, corresponding to the
     
    30583201both optional and supported by the implementation.
    30593202
    3060 The environments specified by scheme-report-environment and
    3061 null-environment are immutable.
     3203The environments specified by scheme-report-environment and
     3204null-environment are immutable by default.  In CHICKEN, as an
     3205extension to R5RS, an extra {{mutable}} argument can be passed, which
     3206makes the environments mutable when non-{{#f}}.  Mutability means new
     3207top-level definitions are accepted and the values of existing
     3208top-level bindings can be mutated.
    30623209
    30633210<procedure>(interaction-environment)</procedure><br>
     
    30773224port is a Scheme object that can accept characters.
    30783225
    3079 <procedure>(call-with-input-file string proc)</procedure><br>
    3080 <procedure>(call-with-output-file string proc)</procedure><br>
     3226<procedure>(call-with-input-file string proc [mode ...])</procedure><br>
     3227<procedure>(call-with-output-file string proc [mode ...])</procedure><br>
    30813228
    30823229String should be a string naming a file, and proc should be a procedure
     
    30993246call-with-output-file.
    31003247
     3248Additional {{mode}} arguments can be passed in, which should be any of
     3249the keywords {{#:text}}, {{#:binary}} or {{#:append}}.  {{#:text}} and
     3250{{#:binary}} indicate the mode in which to open the file (this has an
     3251effect on non-UNIX platforms only), while {{#:append}} indicates that
     3252instead of truncating the file on open, data written to it should be
     3253appended at the end (only for output files).  The extra {{mode}}
     3254arguments are CHICKEN extensions to the R5RS standard.
     3255
    31013256<procedure>(input-port? obj)</procedure><br>
    31023257<procedure>(output-port? obj)</procedure><br>
     
    31053260otherwise returns #f.
    31063261
    3107 <procedure>(current-input-port)</procedure><br>
    3108 <procedure>(current-output-port)</procedure><br>
     3262<procedure>(current-input-port [port])</procedure><br>
     3263<procedure>(current-output-port [port])</procedure><br>
    31093264
    31103265Returns the current default input or output port.
    31113266
    3112 <procedure>(with-input-from-file string thunk)</procedure><br>
    3113 <procedure>(with-output-to-file string thunk)</procedure><br>
     3267If the optional {{port}} argument is passed, the current input or
     3268output port is changed to the provided port.  It can also be used with
     3269{{parameterize}} to temporarily bind the port to another value.  This
     3270is a CHICKEN extension to the R5RS standard.
     3271
     3272<procedure>(with-input-from-file string thunk [mode ...])</procedure><br>
     3273<procedure>(with-output-to-file string thunk [mode ...])</procedure><br>
    31143274
    31153275String should be a string naming a file, and proc should be a procedure
     
    31263286implementation dependent.
    31273287
    3128 <procedure>(open-input-file filename)</procedure><br>
     3288Additional {{mode}} arguments can be passed in, which should be any of
     3289the keywords {{#:text}}, {{#:binary}} or {{#:append}}.  {{#:text}} and
     3290{{#:binary}} indicate the mode in which to open the file (this has an
     3291effect on non-UNIX platforms only), while {{#:append}} indicates that
     3292instead of truncating the file on open, data written to it should be
     3293appended at the end (only for output files).  The extra {{mode}}
     3294arguments are CHICKEN extensions to the R5RS standard.
     3295
     3296<procedure>(open-input-file filename [mode ...])</procedure><br>
    31293297
    31303298Takes a string naming an existing file and returns an input port
     
    31323300opened, an error is signalled.
    31333301
    3134 <procedure>(open-output-file filename)</procedure><br>
     3302Additional {{mode}} arguments can be passed in, which should be any of
     3303the keywords {{#:text}} or {{#:binary}}.  These indicate the mode in
     3304which to open the file (this has an effect on non-UNIX platforms
     3305only).  The extra {{mode}} arguments are CHICKEN extensions to the
     3306R5RS standard.
     3307
     3308<procedure>(open-output-file filename [mode ...])</procedure><br>
    31353309
    31363310Takes a string naming an output file to be created and returns an
     
    31383312If the file cannot be opened, an error is signalled. If a file with the
    31393313given name already exists, the effect is unspecified.
     3314
     3315Additional {{mode}} arguments can be passed in, which should be any of
     3316the keywords {{#:text}}, {{#:binary}} or {{#:append}}.  {{#:text}} and
     3317{{#:binary}} indicate the mode in which to open the file (this has an
     3318effect on non-UNIX platforms only), while {{#:append}} indicates that
     3319instead of truncating the file on open, data written to it should be
     3320appended at the end.  The extra {{mode}} arguments are CHICKEN
     3321extensions to the R5RS standard.
    31403322
    31413323<procedure>(close-input-port port)</procedure><br>
  • wiki/man/5/TODO/Extensions to the standard

    r34258 r34685  
    2121[[Non-standard macros and special forms]] for more information.
    2222
    23 === Extended DSSSL style lambda lists
    24 
    25 Extended DSSSL style lambda lists are supported. DSSSL parameter lists are defined by the following grammar:
    26 
    27  <parameter-list> ==> <required-parameter>*
    28                       [#!optional <optional-parameter>*]
    29                       [#!rest <rest-parameter>]
    30                       [#!key <keyword-parameter>*]
    31  <required-parameter> ==> <ident>
    32  <optional-parameter> ==> <ident>
    33                           | (<ident> <initializer>)
    34  <rest-parameter> ==> <ident>
    35  <keyword-parameter> ==> <ident>
    36                          | (<ident> <initializer>)
    37  <initializer> ==> <expr>
    38 
    39 When a procedure is applied to a list of arguments, the parameters and arguments are processed from left to right as follows:
    40 
    41 * Required-parameters are bound to successive arguments starting with the first argument. It shall be an error if there are fewer arguments than required-parameters.
    42 * Next, the optional-parameters are bound with the remaining arguments. If there are fewer arguments than optional-parameters, then the remaining optional-parameters are bound to the result of the evaluation of their corresponding <initializer>, if one was specified, otherwise {{#f}}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound.
    43 * If there is a rest-parameter, then it is bound to a list containing all the remaining arguments left over after the argument bindings with required-parameters and optional-parameters have been made.
    44 * If {{#!key}} was specified in the parameter-list, there should be an even number of remaining arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the parameter name, and the second member is the corresponding value. If the same keyword occurs more than once in the list of arguments, then the corresponding value of the first keyword is the binding value. If there is no argument for a particular keyword-parameter, then the variable is bound to the result of evaluating <initializer>, if one was specified, otherwise {{#f}}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound.
    45 
    46 Needing a special mention is the close relationship between the rest-parameter and possible keyword-parameters.  Declaring a rest-parameter binds up all remaining arguments in a list, as described above. These same remaining arguments are also used for attempted matches with declared keyword-parameters, as described above, in which case a matching keyword-parameter binds to the corresponding value argument at the same time that both the keyword and value arguments are added to the rest parameter list.
    47 Note that for efficiency reasons, the keyword-parameter matching does nothing more than simply attempt to match with pairs that may exist in the remaining arguments.  Extra arguments that don't match are simply unused and forgotten if no rest-parameter has been declared.  Because of this, the caller of a procedure containing one or more keyword-parameters cannot rely on any kind of system error to report wrong keywords being passed in.
    48 
    49 It shall be an error for an {{<ident>}} to appear more than once in a parameter-list.
    50 
    51 If there is no rest-parameter and no keyword-parameters in the parameter-list, then it shall be an error for any extra arguments to be passed to the procedure.
    52 
    53 
    54 Example:
    55 
    56  ((lambda x x) 3 4 5 6)       => (3 4 5 6)
    57  ((lambda (x y #!rest z) z)
    58   3 4 5 6)                    => (5 6)
    59  ((lambda (x y #!optional z #!rest r #!key i (j 1))
    60      (list x y z i: i j: j))
    61   3 4 5 i: 6 i: 7)            => (3 4 5 i: 6 j: 1)
    62 
    63 === {{set!}}
    64 
    65 {{set!}} for unbound toplevel variables is allowed. {{set! (PROCEDURE ...) ...)}}
    66 is supported, as CHICKEN implements [[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
    67 
    68 === {{cond}}
    69 
    70 The {{cond}} form supports [[http://srfi.schemers.org/srfi-61|SRFI-61]].
    71 
    72 === {{begin}}
    73 
    74 {{(begin)}} is allowed in non-toplevel contexts and evaluates
    75 to an unspecified value.
    76 
    77 === Delayed expressions
    78 
    79 Delayed expressions may return multiple values.
    80 
    81 === Internal definitions
    82 
    83 CHICKEN extends standard semantics by allowing internal definitions
    84 everywhere, and not only at the beginning of a body. A set of internal definitions
    85 is equivalent to a {{letrec}} form enclosing all following expressions
    86 in the body:
    87 
    88  (let ((foo 123))
    89    (bar)
    90    (define foo 456)
    91    (baz foo) )
    92 
    93 expands into
    94 
    95  (let ((foo 123))
    96    (bar)
    97    (letrec ((foo 456))
    98      (baz foo) ) )
    99 
    100 Local sequences of {{define-syntax}} forms are translated into equivalent
    101 {{letrec-syntax}} forms that enclose the following forms as the body of
    102 the expression.
    103 
    104 === Curried definitions
    105 
    106 {{define}} with a single argument is allowed and initializes the toplevel or local binding
    107 to an unspecified value. CHICKEN supports ''curried'' definitions, where the variable name
    108 may also be a list specifying a name and a nested lambda list. So
    109 
    110  (define ((make-adder x) y) (+ x y))
    111 
    112 is equivalent to
    113 
    114  (define (make-adder x) (lambda (y) (+ x y)))
    115 
    11623=== Non-standard procedures
    11724
    11825CHICKEN provides numerous non-standard procedures. See the manual
    11926sections on library units for more information.
    120 
    121 === Special IEEE floating-point numbers
    122 
    123 The special IEEE floating-point numbers ''+nan'', ''+inf'' and ''-inf''
    124 are supported, as is negative zero.
    12527
    12628=== User defined character names
     
    14951of the string.
    15052
    151 === Number/String conversions
    152 
    153 The optional "base" argument to {{string->number}} and {{number->string}}
    154 may be any integral value from 2 to 36.
    155 
    156 === {{force}}
    157 
    158 {{force}} called with an argument that is not a promise returns
    159 that object unchanged.  Captured continuations can be safely invoked
    160 inside before- and after-thunks of a {{dynamic-wind}} form and
    161 execute in the outer dynamic context of the {{dynamic-wind}} form.
    162 
    163 '''Implicit''' non-multival continuations accept multiple values by discarding all
    164 but the first result. Zero values result in the continuation receiving an
    165 unspecified value. Note that this slight relaxation of the behaviour of
    166 returning mulitple values to non-multival continuations does not apply to
    167 explicit continuations (created with {{call-with-current-continuation}}).
    168 
    169 === {{eval}}
    170 
    171 The second argument to {{eval}} is optional and
    172 defaults to the value of {{(interaction-environment)}}.
    173 {{scheme-report-environment}} and {{null-environment}} accept
    174 an optional 2nd parameter: if not {{#f}} (which is the default),
    175 toplevel bindings to standard procedures are mutable and new toplevel
    176 bindings may be introduced.
    177 
    178 === {{load}}
    179 
    180 CHICKEN allows for loading compiled shared objects on some platforms.
    181 An extra second argument is added to allow specifying a custom
    182 evaluation procedure that will be used when loading source files.
    183 
    184 === Optional arguments for port-related procedures
    185 
    186 If the procedures {{current-input-port}} and
    187 {{current-output-port}} are called with an argument (which should
    188 be a port), then that argument is selected as the new current input- and
    189 output-port, respectively.  The procedures {{open-input-file}},
    190 {{open-output-file}}, {{with-input-from-file}},
    191 {{with-output-to-file}}, {{call-with-input-file}} and
    192 {{call-with-output-file}} accept an optional second (or third)
    193 argument which should be one or more keywords, if supplied. These
    194 arguments specify the mode in which the file is opened. Possible
    195 values are the keywords {{#:text}}, {{#:binary}} or
    196 {{#:append}}.
    197 
    19853=== {{exit}}
    19954
Note: See TracChangeset for help on using the changeset viewer.