source: project/wiki/man/5/Module (chicken base) @ 34904

Last change on this file since 34904 was 34904, checked in by sjamaan, 4 years ago

man/5: Move the "exit" family of procedures from (chicken process-context) to (chicken base)

File size: 34.1 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Module (chicken base)
5
6Core procedures and macros, acting as basic extensions to the R5RS
7standard and other essential features.
8
9=== Numeric predicates
10
11These allow you to make a more precise differentiation between number
12types and their properties, not provided by R5RS.
13
14==== fixnum?
15
16<procedure>(fixnum? X)</procedure>
17
18Returns {{#t}} if {{X}} is a fixnum, or {{#f}} otherwise.
19
20==== flonum?
21
22<procedure>(flonum? X)</procedure>
23
24Returns {{#t}} if {{X}} is a flonum, or {{#f}} otherwise.
25
26==== bignum?
27
28<procedure>(bignum? X)</procedure>
29
30Returns {{#t}} if {{X}} is a bignum (integer larger than fits in a
31fixnum), or {{#f}} otherwise.
32
33==== exact-integer?
34
35<procedure>(exact-integer? X)</procedure>
36
37Returns {{#t}} if {{X}} is an exact integer (i.e., a fixnum or a
38bignum), or {{#f}} otherwise.
39
40This procedure is compatible with the definition from the R7RS
41{{(scheme base)}} library.
42
43==== cplxnum?
44
45<procedure>(cplxnum? X)</procedure>
46
47Returns {{#t}} if {{X}} is a true complex number (it has an imaginary
48component), or {{#f}} otherwise.
49
50Please note that {{complex?}} will always return {{#t}} for any number
51type supported by CHICKEN, so you can use this predicate if you want
52to know the representational type of a number.
53
54==== ratnum?
55
56<procedure>(ratnum? X)</procedure>
57
58Returns {{#t}} if {{X}} is a true rational number (it is a fraction
59with a denominator that's not 1), or {{#f}} otherwise.
60
61Please note that {{rational?}} will always return {{#t}} for any
62number type supported by CHICKEN except complex numbers and non-finite
63flonums, so you can use this predicate if you want to know the
64representational type of a number.
65
66==== nan?
67
68<procedure>(nan? N)</procedure>
69
70Returns {{#t}} if {{N}} is not a number (a IEEE flonum NaN-value).  If
71{{N}} is a complex number, it's considered nan if it has a real or
72imaginary component that's nan.
73
74This procedure is compatible with the definition from the R7RS
75{{(scheme inexact)}} library.
76
77==== finite?
78
79<procedure>(infinite? N)</procedure>
80
81Returns {{#t}} if {{N}} is negative or positive infinity, and {{#f}}
82otherwise.  If {{N}} is a complex number, it's considered infinite if
83it has a real or imaginary component that's infinite.
84
85This procedure is compatible with the definition from the R7RS
86{{(scheme inexact)}} library.
87
88==== finite?
89
90<procedure>(finite? N)</procedure>
91
92Returns {{#t}} if {{N}} represents a finite number and {{#f}}
93otherwise.  Positive and negative infinity as well as NaNs are not
94considered finite.  If {{N}} is a complex number, it's considered
95finite if both the real and imaginary components are finite.
96
97This procedure is compatible with the definition from the R7RS
98{{(scheme inexact)}} library.
99
100==== equal=?
101
102<procedure>(equal=? X y)</procedure>
103
104Similar to the standard procedure {{equal?}}, but compares numbers
105using the {{=}} operator, so {{equal=?}} allows structural comparison
106in combination with comparison of numerical data by value.
107
108
109=== Arithmetic
110
111==== add1/sub1
112
113<procedure>(add1 N)</procedure>
114<procedure>(sub1 N)</procedure>
115
116Adds/subtracts 1 from {{N}}.
117
118
119==== exact-integer-sqrt
120
121<procedure>(exact-integer-sqrt K)</procedure>
122
123Returns two values {{s}} and {{r}}, where {{s^2 + r = K}} and {{K < (s+1)^2}}.
124In other words, {{s}} is the closest square root we can find that's equal to or
125smaller than {{K}}, and {{r}} is the rest if {{K}} isn't a neat square of two numbers.
126
127This procedure is compatible with the definition from the R7RS
128{{(scheme base)}} library.
129
130==== exact-integer-nth-root
131
132<procedure>(exact-integer-nth-root K N)</procedure>
133
134Like {{exact-integer-sqrt}}, but with any base value.  Calculates
135{{\sqrt[N]{K}}}, the {{N}}th root of {{K}} and returns two values
136{{s}} and {{r}} where {{s^N + r = K}} and {{K < (s+1)^N}}.
137
138
139==== Division with quotient and remainder
140
141<procedure>(quotient&remainder X Y)</procedure>
142<procedure>(quotient&modulo X Y)</procedure>
143
144Returns two values: the quotient and the remainder (or modulo) of
145{{X}} divided by {{Y}}.  Could be defined as {{(values (quotient X Y)
146(remainder X Y))}}, but is much more efficient when dividing very
147large numbers.
148
149==== signum
150
151<procedure>(signum N)</procedure>
152
153For real numbers, returns {{1}} if {{N}} is positive, {{-1}} if {{N}}
154is negative or {{0}} if {{N}} is zero. {{signum}} is exactness
155preserving.
156
157For complex numbers, returns a complex number of the same angle but
158with magnitude 1.
159
160
161=== Lazy evaluation
162
163==== delay-force
164
165<macro>(delay-force <expression>)</macro><br>
166
167The expression {{(delay-force expression)}} is conceptually similar to
168{{(delay (force expression))}}, with the difference that forcing the
169result of {{delay-force}} will in effect result in a tail call to
170{{(force expression)}}, while forcing the result of
171{{(delay (force expression))}} might not.
172
173Thus iterative lazy algorithms that might result in a long series of
174chains of delay and force can be rewritten using delay-force to
175prevent consuming unbounded space during evaluation.
176
177This special form is compatible with the definition from the R7RS
178{{(scheme lazy)}} library.
179
180See the description of force under
181[[Module scheme#control-features|Control features]] in the "scheme"
182module documentation for a more complete description of delayed
183evaluation.
184
185For more information regarding the unbounded build-up of space, see
186the [[http://srfi.schemers.org/srfi-45/srfi-45.html|SRFI-45]]
187rationale.
188
189==== make-promise
190
191<procedure>(make-promise obj)</procedure>
192
193The make-promise procedure returns a promise which, when forced, will
194return {{obj}} . It is similar to {{delay}}, but does not delay its
195argument: it is a procedure rather than syntax. If {{obj}} is already
196a promise, it is returned.
197
198This procedure is compatible with the definition from the R7RS
199{{(scheme lazy)}} library.
200
201
202==== promise?
203
204<procedure>(promise? X)</procedure>
205
206Returns {{#t}} if {{X}} is a promise returned by {{delay}}, or
207{{#f}} otherwise.
208
209This procedure is compatible with the definition from the R7RS
210{{(scheme lazy)}} library.
211
212
213=== Input/Output
214
215==== current-error-port
216
217<procedure>(current-error-port [PORT])</procedure>
218
219Returns default error output port. If {{PORT}} is given, then that
220port is selected as the new current error output port.
221
222Note that the default error output port is not buffered. Use
223[[Module (chicken port)#set-buffering-mode!|{{set-buffering-mode!}}]]
224if you need a different behaviour.
225
226==== print
227
228<procedure>(print [EXP1 ...])</procedure>
229
230Outputs the optional arguments {{EXP1 ...}} using {{display}} and
231writes a newline character to the port that is the value of
232{{(current-output-port)}}. Returns {{(void)}}.
233
234==== print*
235
236<procedure>(print* [EXP1 ...])</procedure>
237
238Similar to {{print}}, but does not output a terminating newline
239character and performs a {{flush-output}} after writing its arguments.
240
241
242=== Interrupts and error-handling
243
244==== enable-warnings
245
246<procedure>(enable-warnings [BOOL])</procedure>
247
248Enables or disables warnings, depending on wether {{BOOL}} is true or
249false.  If called with no arguments, this procedure returns {{#t}} if
250warnings are currently enabled, or {{#f}} otherwise. Note that this is
251not a parameter.  The current state (whether warnings are enabled or
252disabled) is global and not thread-local.
253
254
255==== error
256
257<procedure>(error [LOCATION] [STRING] EXP ...)</procedure>
258
259Prints error message, writes all extra arguments to the value of
260{{(current-error-port)}} and invokes the current
261exception-handler. This conforms to
262[[http://srfi.schemers.org/srfi-23/srfi-23.html|SRFI-23]].  If
263{{LOCATION}} is given and a symbol, it specifies the ''location'' (the
264name of the procedure) where the error occurred.
265
266
267
268==== get-call-chain
269
270<procedure>(get-call-chain [START [THREAD]])</procedure>
271
272Returns a list with the call history. Backtrace information is only
273generated in code compiled without {{-no-trace}} and evaluated code.
274If the optional argument {{START}} is given, the backtrace starts at
275this offset, i.e. when {{START}} is 1, the next to last trace-entry is
276printed, and so on. If the optional argument {{THREAD}} is given, then
277the call-chain will only be constructed for calls performed by this
278thread.
279
280
281
282==== print-call-chain
283
284<procedure>(print-call-chain [PORT [START [THREAD [HEADER]]]])</procedure>
285
286Prints a backtrace of the procedure call history to {{PORT}}, which
287defaults to {{(current-output-port)}}. The output is prefixed by the
288{{HEADER}}, which defaults to {{"\n\tCall history:\n"}}.
289
290
291==== procedure-information
292
293<procedure>(procedure-information PROC)</procedure>
294
295Returns an s-expression with debug information for the procedure
296{{PROC}}, or {{#f}}, if {{PROC}} has no associated debug information.
297
298
299==== warning
300
301<procedure>(warning STRING EXP ...)</procedure>
302
303Displays a warning message (if warnings are enabled with
304{{enable-warnings}}) and continues execution.
305
306
307=== Lists
308
309==== foldl
310
311<procedure>(foldl PROCEDURE INIT LIST)</procedure>
312
313Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from
314the left:
315
316<enscript hightlight=scheme>
317(foldl + 0 '(1 2 3))    ==>    (+ (+ (+ 0 1) 2) 3)
318</enscript>
319
320Note that the order of arguments taken by {{PROCEDURE}} is different
321from the {{SRFI-1}} {{fold}} procedure, but matches the more natural
322order used in Haskell and Objective Caml.
323
324
325==== foldr
326
327<procedure>(foldr PROCEDURE INIT LIST)</procedure>
328
329Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from
330the right:
331
332<enscript hightlight=scheme>
333(foldr + 0 '(1 2 3))    ==>    (+ 1 (+ 2 (+ 3 0)))
334</enscript>
335
336
337=== Vectors
338
339==== vector-copy!
340
341<procedure>(vector-copy! VECTOR1 VECTOR2 [COUNT])</procedure>
342
343Copies contents of {{VECTOR1}} into {{VECTOR2}}. If the
344argument {{COUNT}} is given, it specifies the maximal number of
345elements to be copied. If not given, the minimum of the lengths of the
346argument vectors is copied.
347
348Exceptions: {{(exn bounds)}}
349
350This procedure is compatible with the definition from the R7RS
351{{(scheme base)}} library.
352
353==== vector-resize
354
355<procedure>(vector-resize VECTOR N [INIT])</procedure>
356
357Creates and returns a new vector with the contents of {{VECTOR}} and
358length {{N}}. If {{N}} is greater than the original length of
359{{VECTOR}}, then all additional items are initialized to {{INIT}}. If
360{{INIT}} is not specified, the contents are initialized to some
361unspecified value.
362
363
364==== subvector
365
366<procedure>(subvector VECTOR FROM [TO])</procedure>
367
368Returns a new vector with elements taken from {{VECTOR}} in the
369given range. {{TO}} defaults to {{(vector-length VECTOR)}}.
370
371{{subvector}} was introduced in CHICKEN 4.7.3.
372
373
374=== User-defined named characters
375
376==== char-name
377
378<procedure>(char-name SYMBOL-OR-CHAR [CHAR])</procedure>
379
380This procedure can be used to inquire about character names or to
381define new ones. With a single argument the behavior is as follows:
382If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns
383the character with this name, or {{#f}} if no character is defined
384under this name. If {{SYMBOL-OR-CHAR}} is a character, then the
385name of the character is returned as a symbol, or {{#f}} if the
386character has no associated name.
387
388If the optional argument {{CHAR}} is provided, then
389{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of
390the given character. If multiple names designate the same character,
391then the {{write}} will use the character name that was defined last.
392
393<enscript highlight=scheme>
394(char-name 'space)                  ==> #\space
395(char-name #\space)                 ==> space
396(char-name 'bell)                   ==> #f
397(char-name (integer->char 7))       ==> #f
398(char-name 'bell (integer->char 7))
399(char-name 'bell)                   ==> #\bell
400(char->integer (char-name 'bell))   ==> 7
401</enscript>
402
403
404=== The unspecified value
405
406==== void
407
408<procedure>(void ARGUMENT ...)</procedure>
409
410Ignores {{ARGUMENT ...}} and returns an unspecified value.
411
412
413=== Continuations
414
415==== call/cc
416
417<procedure>(call/cc PROCEDURE)</procedure>
418
419An alias for {{call-with-current-continuation}}.
420
421This procedure is compatible with the definition from the R7RS
422{{(scheme base)}} library.
423
424=== Symbols
425
426==== Symbol utilities
427
428===== symbol-append
429
430<procedure>(symbol-append SYMBOL1 ...)</procedure>
431
432Creates a new symbol from the concatenated names of the argument symbols
433{{(SYMBOL1 ...)}}.
434
435==== Uninterned symbols ("gensyms")
436
437Symbols may be "interned" or "uninterned". Interned symbols are
438registered in a global table, and when read back from a port are
439identical to a symbol written before:
440
441<enscript highlight=scheme>
442(define sym 'foo)
443
444(eq? sym (with-input-from-string
445            (with-output-to-string
446              (lambda () (write sym)))
447            read))
448
449  => #t
450</enscript>
451
452Uninterned symbols on the other hand are not globally registered and so
453multiple symbols with the same name may coexist:
454
455<enscript highlight=scheme>
456(define sym (gensym 'foo))   ; sym is a uninterned symbol like "foo42"
457
458(eq? sym (with-input-from-string    ; the symbol read will be an interned symbol
459            (with-output-to-string
460              (lambda () (write sym)))
461            read))
462
463  => #f
464
465(eq? (string->uninterned-symbol "foo") (string->uninterned-symbol "foo"))
466
467  => #f
468</enscript>
469
470Use uninterned symbols if you need to generate unique values that
471can be compared quickly, for example as keys into a hash-table
472or association list. Note that uninterned symbols lose their
473uniqueness property when written to a file and read back in, as
474in the example above.
475
476===== gensym
477
478<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
479
480Returns a newly created uninterned symbol. If an argument is provided,
481the new symbol is prefixed with that argument.
482
483
484===== string->uninterned-symbol
485
486<procedure>(string->uninterned-symbol STRING)</procedure>
487
488Returns a newly created, unique symbol with the name {{STRING}}.
489
490
491=== Setters
492
493SRFI-17 is fully implemented. For more information see:
494[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
495
496==== setter
497
498<procedure>(setter PROCEDURE)</procedure>
499
500Returns the setter-procedure of {{PROCEDURE}}, or signals an error if
501{{PROCEDURE}} has no associated setter-procedure.
502
503Note that {{(set! (setter PROC) ...)}} for a procedure that has no
504associated setter procedure yet is a very slow operation (the old
505procedure is replaced by a modified copy, which involves a garbage
506collection).
507
508
509==== getter-with-setter
510
511<procedure>(getter-with-setter GETTER SETTER)</procedure>
512
513Returns a copy of the procedure {{GETTER}} with the associated setter
514procedure {{SETTER}}. Contrary to the SRFI specification, the setter
515of the returned procedure may be changed.
516
517
518=== Binding forms for optional arguments
519
520==== optional
521
522<macro>(optional ARGS DEFAULT)</macro>
523
524Use this form for procedures that take a single optional argument. If
525{{ARGS}} is the empty list {{DEFAULT}} is evaluated and
526returned, otherwise the first element of the list {{ARGS}}. It is
527an error if {{ARGS}} contains more than one value.
528
529<enscript highlight=scheme>
530(define (incr x . i) (+ x (optional i 1)))
531(incr 10)                                   ==> 11
532(incr 12 5)                                 ==> 17
533</enscript>
534
535
536==== case-lambda
537
538<macro>(case-lambda (LAMBDA-LIST1 EXP1 ...) ...)</macro>
539
540Expands into a lambda that invokes the body following the first
541matching lambda-list.
542
543<enscript highlight=scheme>
544(define plus
545  (case-lambda
546    (() 0)
547    ((x) x)
548    ((x y) (+ x y))
549    ((x y z) (+ (+ x y) z))
550    (args (apply + args))))
551
552(plus)                      ==> 0
553(plus 1)                    ==> 1
554(plus 1 2 3)                ==> 6
555</enscript>
556
557For more information see the documentation for
558[[http://srfi.schemers.org/srfi-16/srfi-16.html|SRFI-16]]
559
560This special form is also compatible with the definition from the R7RS
561{{(scheme case-lambda)}} library.
562
563==== let-optionals
564
565<macro> (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)</macro>
566
567Binding constructs for optional procedure arguments. {{ARGS}} is
568normally a rest-parameter taken from a lambda-list. {{let-optionals}}
569binds {{VAR1 ...}} to available arguments in parallel, or to
570{{DEFAULT1 ...}} if not enough arguments were provided.
571{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable
572sees the previous ones. it is an error if any excess arguments are
573provided.
574
575<enscript highlight=scheme>
576(let-optionals '(one two) ((a 1) (b 2) (c 3))
577  (list a b c) )                               ==> (one two 3)
578</enscript>
579
580==== let-optionals*
581
582<macro> (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)</macro>
583
584Binding constructs for optional procedure arguments. {{ARGS}} is
585normally a rest-parameter taken from a lambda-list. {{let-optionals}}
586binds {{VAR1 ...}} to available arguments in parallel, or to
587{{DEFAULT1 ...}} if not enough arguments were provided.
588{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable
589sees the previous ones. If a single variable {{RESTVAR}} is given,
590then it is bound to any remaining arguments, otherwise it is an error
591if any excess arguments are provided.
592
593<enscript highlight=scheme>
594(let-optionals* '(one two) ((a 1) (b 2) (c a))
595  (list a b c) )                               ==> (one two one)
596</enscript>
597
598=== Other binding forms
599
600==== and-let*
601
602<macro>(and-let* (BINDING ...) EXP1 EXP2 ...)</macro>
603
604Bind sequentially and execute body. {{BINDING}} can
605be a list of a variable and an expression, a list with a single
606expression, or a single variable. If the value of an expression
607bound to a variable is {{#f}}, the {{and-let*}} form
608evaluates to {{#f}} (and the subsequent bindings and the body
609are not executed).  Otherwise the next binding is performed. If
610all bindings/expressions evaluate to a true result, the body is
611executed normally and the result of the last expression is the
612result of the {{and-let*}} form. See also the documentation for
613[[http://srfi.schemers.org/srfi-2/srfi-2.html|SRFI-2]].
614
615==== letrec*
616
617<macro>(letrec* ((VARIABLE EXPRESSION) ...) BODY ...)</macro>
618
619Implements R6RS/R7RS {{letrec*}}. {{letrec*}} is similar to {{letrec}}
620but binds the variables sequentially and is to {{letrec}} what
621{{let*}} is to {{let}}.
622
623This special form is compatible with the definition from the R7RS
624{{(scheme base)}} library.
625
626==== rec
627
628<macro>(rec NAME EXPRESSION)</macro><br>
629<macro>(rec (NAME VARIABLE ...) BODY ...)</macro>
630
631Allows simple definition of recursive definitions. {{(rec NAME EXPRESSION)}} is
632equivalent to {{(letrec ((NAME EXPRESSION)) NAME)}} and {{(rec (NAME VARIABLE ...) BODY ...)}}
633is the same as {{(letrec ((NAME (lambda (VARIABLE ...) BODY ...))) NAME)}}.
634
635==== cut
636
637<macro>(cut SLOT ...)</macro><br>
638<macro>(cute SLOT ...)</macro>
639
640[[http://srfi.schemers.org/srfi-26/srfi-26.html|Syntactic sugar for specializing parameters]].
641
642==== define-values
643
644<macro>(define-values (NAME ...) VALUEEXP)</macro>
645<macro>(define-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>
646<macro>(define-values NAME VALUEEXP)</macro>
647
648Defines several variables at once, with the result values of expression
649{{VALUEEXP}}, similar to {{set!-values}}.
650
651This special form is compatible with the definition from the R7RS
652{{(scheme base)}} library.
653
654==== fluid-let
655
656<macro>(fluid-let ((VAR1 X1) ...) BODY ...)</macro>
657
658Binds the variables {{VAR1 ...}} dynamically to the values {{X1 ...}}
659during execution of {{BODY ...}}.  This implements
660[[http://srfi.schemers.org/srfi-15/srfi-15.html|SRFI-15]].
661
662==== let-values
663
664<macro>(let-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
665
666Binds multiple variables to the result values of {{VALUEEXP ...}}.
667All variables are bound simultaneously.  Like {{define-values}}, the
668{{(NAME ...)}} expression can be any basic lambda list (dotted tail
669notation is supported).
670
671This special form implements
672[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]], and it is
673also compatible with the definition from the R7RS {{(scheme base)}}
674library.
675
676
677==== let*-values
678
679<macro>(let*-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
680
681Binds multiple variables to the result values of {{VALUEEXP ...}}.
682The variables are bound sequentially.  Like {{let-values}}, the
683{{(NAME ...)}} expression can be any basic lambda list (dotted tail
684notation is supported).
685
686This is also part of
687[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]] and is also
688compatible with the definition from the R7RS {{(scheme base)}}
689library.
690
691<enscript highlight=scheme>
692(let*-values (((a b) (values 2 3))
693              ((p) (+ a b)) )
694  p)                               ==> 5
695</enscript>
696
697==== letrec-values
698
699<macro>(letrec-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
700
701Binds the result values of {{VALUEEXP ...}} to multiple variables at
702once.  All variables are mutually recursive.  Like {{let-values}}, the
703{{(NAME ...)}} expression can be any basic lambda list (dotted tail
704notation is supported).
705
706<enscript highlight=scheme>
707(letrec-values (((odd even)
708                   (values
709                     (lambda (n) (if (zero? n) #f (even (sub1 n))))
710                     (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )
711  (odd 17) )                           ==> #t
712</enscript>
713
714
715==== receive
716
717<macro>(receive (NAME ...) VALUEEXP BODY ...)</macro><br>
718<macro>(receive (NAME1 ... NAMEn . NAMEn+1) VALUEEXP BODY ...)</macro><br>
719<macro>(receive NAME VALUEEXP BODY ...)</macro><br>
720<macro>(receive VALUEEXP)</macro>
721
722[[http://srfi.schemers.org/srfi-8/srfi-8.html|SRFI-8]].
723Syntactic sugar for {{call-with-values}}. Binds variables
724to the result values of {{VALUEEXP}} and evaluates {{BODY ...}},
725similar {{define-values}} but lexically scoped.
726
727{{(receive VALUEEXP)}} is equivalent to {{(receive _ VALUEEXP _)}}.
728This shortened form is not described by SRFI-8.
729
730==== set!-values
731
732<macro>(set!-values (NAME ...) VALUEEXP)</macro>
733<macro>(set!-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>
734<macro>(set!-values NAME VALUEEXP)</macro>
735
736Assigns the result values of expression {{VALUEEXP}} to multiple
737variables, similar to {{define-values}}.
738
739==== nth-value
740
741<macro>(nth-value N EXP)</macro>
742
743Returns the {{N}}th value (counting from zero) of the values returned
744by expression {{EXP}}.
745
746
747=== Parameters
748
749Parameters are CHICKEN's form of dynamic variables, except that they are
750procedures rather than actual variables.  A parameter is a procedure of
751zero or one arguments. To retrieve the value of a parameter call the
752parameter-procedure with zero arguments. To change the setting of the
753parameter, call the parameter-procedure with the new value as argument:
754
755<enscript highlight=scheme>
756(define foo (make-parameter 123))
757(foo)                             ==> 123
758(foo 99)
759(foo)                             ==> 99
760</enscript>
761
762Parameters are fully thread-local, each thread of execution
763owns a local copy of a parameters' value.
764
765CHICKEN implements
766[[http://srfi.schemers.org/srfi-39/srfi-39.html|SRFI-39]], which
767is also standardized by R7RS.
768
769
770==== parameterize
771
772<macro>(parameterize ((PARAMETER1 X1) ...) BODY ...)</macro>
773
774Binds the parameters {{PARAMETER1 ...}} dynamically to the values
775{{X1 ...}} during execution of {{BODY ...}}.  (see also:
776{{make-parameter}} in [[Parameters]]). Note that {{PARAMETER}} may
777be any expression that evaluates to a parameter procedure.
778
779This special form is compatible with the definition from the R7RS
780{{(scheme base)}} library.
781
782==== make-parameter
783
784<procedure>(make-parameter VALUE [GUARD])</procedure>
785
786Returns a procedure that accepts zero or one argument. Invoking the
787procedure with zero arguments returns {{VALUE}}. Invoking the
788procedure with one argument changes its value to the value of that
789argument and returns the new value (subsequent invocations with zero
790parameters return the new value). {{GUARD}} should be a procedure of a
791single argument. Any new values of the parameter (even the initial
792value) are passed to this procedure. The guard procedure should check
793the value and/or convert it to an appropriate form.
794
795This special form is compatible with the definition from the R7RS
796{{(scheme base)}} library.
797
798=== Substitution forms and macros
799
800==== define-constant
801
802<macro>(define-constant NAME CONST)</macro>
803
804Defines a variable with a constant value, evaluated at compile-time.
805Any reference to such a constant should appear textually '''after'''
806its definition. This construct is equivalent to {{define}} when
807evaluated or interpreted.  Constant definitions should only appear at
808toplevel. Note that constants are local to the current compilation
809unit and are not available outside of the source file in which they
810are defined. Names of constants still exist in the Scheme namespace
811and can be lexically shadowed.  If the value is mutable, then the
812compiler is careful to preserve its identity.  {{CONST}} may be any
813constant expression, and may also refer to constants defined via
814{{define-constant}} previously, but it must be possible to
815evaluate the expression at compile-time.
816
817==== define-inline
818
819<macro>(define-inline (NAME VAR ...) BODY ...)</macro><br>
820<macro>(define-inline (NAME VAR ... . VAR) BODY ...)</macro><br>
821<macro>(define-inline NAME EXP)</macro>
822
823Defines an inline procedure. Any occurrence of {{NAME}} will be replaced
824by {{EXP}} or {{(lambda (VAR ... [. VAR]) BODY ...)}}. This is similar
825to a macro, but variable names and scope are handled correctly.
826
827Inline substitutions take place '''after''' macro-expansion, and any
828reference to {{NAME}} should appear textually '''after''' its
829definition. Inline procedures are local to the current compilation unit
830and are not available outside of the source file in which they are
831defined. Names of inline procedures still exist in the Scheme namespace
832and can be lexically shadowed. Inline definitions should only appear at
833the toplevel.
834
835Note that the {{inline-limit}} compiler option does not affect inline
836procedure expansion, and self-referential inline procedures may cause
837the compiler to enter an infinite loop.
838
839In the third form, {{EXP}} must be a lambda expression.
840
841This construct is equivalent to {{define}} when evaluated or
842interpreted.
843
844
845=== Conditional forms
846
847==== select
848
849<macro>(select EXP ((KEY ...) EXP1 ...) ... [(else EXPn ...)])</macro>
850
851This is similar to {{case}}, but the keys are evaluated.
852
853==== unless
854
855<macro>(unless TEST EXP1 EXP2 ...)</macro>
856
857Equivalent to:
858
859<enscript highlight=scheme>
860(if (not TEST) (begin EXP1 EXP2 ...))
861</enscript>
862
863==== when
864
865<macro>(when TEST EXP1 EXP2 ...)</macro>
866
867Equivalent to:
868
869<enscript highlight=scheme>
870(if TEST (begin EXP1 EXP2 ...))
871</enscript>
872
873
874=== Record structures
875
876==== define-record
877
878<macro>(define-record NAME SLOTNAME ...)</macro>
879
880Defines a record type. This defines a number of procedures for
881creating, accessing, and modifying record members.
882
883Call {{make-NAME}} to create an instance
884of the structure (with one initialization-argument for each slot, in
885the listed order).
886
887{{(NAME? STRUCT)}} tests any object for being an instance of this
888structure.
889
890Slots are accessed via {{(NAME-SLOTNAME STRUCT)}}
891and updated using {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
892
893<enscript highlight=scheme>
894(define-record point x y)
895(define p1 (make-point 123 456))
896(point? p1)                      ==> #t
897(point-x p1)                     ==> 123
898(point-y-set! p1 99)
899(point-y p1)                     ==> 99
900</enscript>
901
902===== SRFI-17 setters
903
904{{SLOTNAME}} may alternatively also be of the form
905
906  (setter SLOTNAME)
907
908In this case the slot can be read with {{(NAME-SLOTNAME STRUCT)}} as usual,
909and modified with {{(set! (NAME-SLOTNAME STRUCT) VALUE)}} (the slot-accessor
910has an associated SRFI-17 "setter" procedure) instead of
911the usual {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
912
913
914<enscript highlight=scheme>
915(define-record point (setter x) (setter y))
916(define p1 (make-point 123 456))
917(point? p1)                      ==> #t
918(point-x p1)                     ==> 123
919(set! (point-y p1) 99)
920(point-y p1)                     ==> 99
921</enscript>
922
923==== define-record-type
924
925<macro>(define-record-type NAME (CONSTRUCTOR TAG ...) PREDICATE (FIELD ACCESSOR [MODIFIER]) ...)</macro>
926
927SRFI-9 record types. For more information see the documentation for
928[[http://srfi.schemers.org/srfi-9/srfi-9.html|SRFI-9]].
929
930As an extension the {{MODIFIER}} may have the form
931{{(setter PROCEDURE)}}, which will define a SRFI-17 setter-procedure
932for the given {{PROCEDURE}} that sets the field value.
933Usually {{PROCEDURE}} has the same name is {{ACCESSOR}} (but it
934doesn't have to).
935
936This special form is also compatible with the definition from the R7RS
937{{(scheme base)}} library.
938
939
940==== define-record-printer
941
942<macro>(define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)</macro><br>
943<macro>(define-record-printer NAME PROCEDURE)</macro>
944
945Defines a printing method for record of the type {{NAME}} by
946associating a procedure with the record type. When a record of this
947type is written using {{display, write}} or {{print}}, then
948the procedure is called with two arguments: the record to be printed
949and an output-port.
950
951<enscript highlight=scheme>
952(define-record-type foo (make-foo x y z) foo?
953  (x foo-x)
954  (y foo-y)
955  (z foo-z))
956(define f (make-foo 1 2 3))
957(define-record-printer (foo x out)
958  (fprintf out "#,(foo ~S ~S ~S)"
959           (foo-x x) (foo-y x) (foo-z x)) )
960(define-reader-ctor 'foo make-foo)
961(define s (with-output-to-string
962              (lambda () (write f))))
963s                                   ==> "#,(foo 1 2 3)"
964(equal? f (with-input-from-string
965              s read)))             ==> #t
966</enscript>
967
968=== Other forms
969
970==== include
971
972<macro>(include STRING)</macro>
973
974Include toplevel-expressions from the given source file in the currently
975compiled/interpreted program.  If the included file has the extension
976{{.scm}}, then it may be omitted. The file is searched for in the
977current directory and all directories specified by the {{-include-path}}
978option.
979
980==== include-relative
981
982<macro>(include-relative STRING)</macro>
983
984Works like {{include}}, but the filename is searched for relative to the
985including file rather than the current directory.
986
987
988=== Making extra libraries and extensions available
989
990==== require-extension
991
992<macro>(require-extension ID ...)</macro>
993
994This is equivalent to {{(require-library ID ...)}} but performs an implicit
995{{import}}, if necessary. Since version 4.4.0, {{ID}} may also be an import specification
996(using {{rename}}, {{only}}, {{except}} or {{prefix}}).
997
998To make long matters short - just use {{require-extension}} and it will normally figure everything out for dynamically
999loadable extensions and core library units.
1000
1001This implementation of {{require-extension}} is compliant with [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]]
1002(see the [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]] document for more information).
1003
1004==== require-library
1005
1006<macro>(require-library ID ...)</macro>
1007
1008This form does all the necessary steps to make the libraries or extensions given
1009in {{ID ...}} available. It loads syntactic extensions, if needed and generates
1010code for loading/linking with core library modules or separately installed
1011extensions.
1012
1013During interpretation/evaluation {{require-library}} performs one of the
1014following:
1015
1016* If {{ID}} names a built-in feature {{chicken srfi-0 srfi-2 srfi-6 srfi-8 srfi-9 srfi-10 srfi-17 srfi-23 srfi-30 srfi-39 srfi-55}}, then nothing is done.
1017* If {{ID}} names one of the syntactic extensions {{chicken-syntax chicken-ffi-syntax}}, then this extension will be loaded.
1018* If {{ID}} names one of the core library units shipped with CHICKEN, then a {{(load-library 'ID)}} will be performed.
1019* If {{ID}} names an installed extension with the {{syntax}} or {{require-at-runtime}} attribute, then the extensions is loaded at compile-time, probably doing a run-time {{(require ...)}} for any run-time requirements.
1020* Otherwise, {{(require-library ID)}} is equivalent to {{(require 'ID)}}.
1021
1022During compilation, one of the following happens instead:
1023
1024* If {{ID}} names a built-in feature {{chicken srfi-0 srfi-2 srfi-6 srfi-8 srfi-9 srfi-10 srfi-17 srfi-23 srfi-30 srfi-39 srfi-55}}, then nothing is done.
1025* If {{ID}} names one of the syntactic extensions {{chicken-syntax chicken-ffi-syntax}}, then this extension will be loaded at compile-time, making the syntactic extensions available in compiled code.
1026* If {{ID}} names one of the core library units shipped with CHICKEN, or if the option {{-uses ID}} has been passed to the compiler, then a {{(declare (uses ID))}} is generated.
1027* If {{ID}} names an installed extension with the {{syntax}} or {{require-at-runtime}} attribute, then the extension is loaded at compile-time, and code is emitted to {{(require ...)}} any needed run-time requirements.
1028* Otherwise {{(require-library ID)}} is equivalent to {{(require 'ID)}}.
1029
1030{{ID}} should be a pure extension name and should not contain any path prefixes (for example {{dir/lib...}} is illegal).
1031
1032{{ID}} may also be a list that designates an extension-specifier. Currently the following extension specifiers are
1033defined:
1034
1035* {{(srfi NUMBER ...)}} is required for SRFI-55 compatibility and is fully implemented
1036* {{(version ID NUMBER)}} is equivalent to {{ID}}, but checks at compile-time whether the extension named {{ID}} is installed and whether its version is equal or higher than {{NUMBER}}. {{NUMBER}} may be a string or a number, the comparison is done lexicographically (using {{string>=?}}).
1037
1038TODO: Document declare (keep the "declarations" section?)
1039
1040=== Process shutdown
1041
1042==== emergency-exit
1043
1044<procedure>(emergency-exit [CODE])</procedure>
1045
1046Exits the current process without flushing any buffered output (using
1047the C function {{_exit}}).  Note that the {{exit-handler}} is not called
1048when this procedure is invoked. The optional exit status code {{CODE}}
1049defaults to {{0}}.
1050
1051
1052==== exit
1053
1054<procedure>(exit [CODE])</procedure>
1055
1056Exit the running process and return exit-code, which defaults to 0
1057(Invokes {{exit-handler}}).
1058
1059Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
1060
1061
1062=== exit-handler
1063
1064<parameter>(exit-handler)</parameter>
1065
1066A procedure of a single optional argument. When {{exit}} is called,
1067then this procedure will be invoked with the exit-code as argument. The
1068default behavior is to terminate the program.
1069
1070Note that this handler is ''not'' invoked when {{emergency-exit}} is
1071used.
1072
1073
1074=== implicit-exit-handler
1075
1076<parameter>(implicit-exit-handler)</parameter>
1077
1078A procedure of no arguments. When the last toplevel expression of the
1079program has executed, then the value of this parameter is called. The
1080default behaviour is to invoke all pending finalizers.
1081
1082
1083==== on-exit
1084
1085<procedure>(on-exit THUNK)</procedure>
1086
1087Schedules the zero-argument procedures {{THUNK}} to be executed before
1088the process exits, either explicitly via {{exit}} or implicitly after
1089execution of the last top-level form. Note that finalizers for
1090unreferenced finalized data are run before exit procedures.
1091
1092---
1093Previous: [[Module srfi-4]]
1094
1095Next: [[Module (chicken bitwise)]]
Note: See TracBrowser for help on using the repository browser.