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

Last change on this file since 35372 was 35372, checked in by sjamaan, 5 months ago

man/5: Remove require-extension-for-syntax

File size: 42.0 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
9This module is used by default, unless the program is compiled with
10the {{-explicit-use}} option.
11
12=== Numeric predicates
13
14These allow you to make a more precise differentiation between number
15types and their properties, not provided by R5RS.
16
17==== fixnum?
18
19<procedure>(fixnum? X)</procedure>
20
21Returns {{#t}} if {{X}} is a fixnum, or {{#f}} otherwise.
22
23==== flonum?
24
25<procedure>(flonum? X)</procedure>
26
27Returns {{#t}} if {{X}} is a flonum, or {{#f}} otherwise.
28
29==== bignum?
30
31<procedure>(bignum? X)</procedure>
32
33Returns {{#t}} if {{X}} is a bignum (integer larger than fits in a
34fixnum), or {{#f}} otherwise.
35
36==== exact-integer?
37
38<procedure>(exact-integer? X)</procedure>
39
40Returns {{#t}} if {{X}} is an exact integer (i.e., a fixnum or a
41bignum), or {{#f}} otherwise.
42
43This procedure is compatible with the definition from the R7RS
44{{(scheme base)}} library.
45
46==== cplxnum?
47
48<procedure>(cplxnum? X)</procedure>
49
50Returns {{#t}} if {{X}} is a true complex number (it has an imaginary
51component), or {{#f}} otherwise.
52
53Please note that {{complex?}} will always return {{#t}} for any number
54type supported by CHICKEN, so you can use this predicate if you want
55to know the representational type of a number.
56
57==== ratnum?
58
59<procedure>(ratnum? X)</procedure>
60
61Returns {{#t}} if {{X}} is a true rational number (it is a fraction
62with a denominator that's not 1), or {{#f}} otherwise.
63
64Please note that {{rational?}} will always return {{#t}} for any
65number type supported by CHICKEN except complex numbers and non-finite
66flonums, so you can use this predicate if you want to know the
67representational type of a number.
68
69==== nan?
70
71<procedure>(nan? N)</procedure>
72
73Returns {{#t}} if {{N}} is not a number (a IEEE flonum NaN-value).  If
74{{N}} is a complex number, it's considered nan if it has a real or
75imaginary component that's nan.
76
77This procedure is compatible with the definition from the R7RS
78{{(scheme inexact)}} library.
79
80==== finite?
81
82<procedure>(infinite? N)</procedure>
83
84Returns {{#t}} if {{N}} is negative or positive infinity, and {{#f}}
85otherwise.  If {{N}} is a complex number, it's considered infinite if
86it has a real or imaginary component that's infinite.
87
88This procedure is compatible with the definition from the R7RS
89{{(scheme inexact)}} library.
90
91==== finite?
92
93<procedure>(finite? N)</procedure>
94
95Returns {{#t}} if {{N}} represents a finite number and {{#f}}
96otherwise.  Positive and negative infinity as well as NaNs are not
97considered finite.  If {{N}} is a complex number, it's considered
98finite if both the real and imaginary components are finite.
99
100This procedure is compatible with the definition from the R7RS
101{{(scheme inexact)}} library.
102
103==== equal=?
104
105<procedure>(equal=? X y)</procedure>
106
107Similar to the standard procedure {{equal?}}, but compares numbers
108using the {{=}} operator, so {{equal=?}} allows structural comparison
109in combination with comparison of numerical data by value.
110
111
112=== Arithmetic
113
115
117<procedure>(sub1 N)</procedure>
118
120
121
122==== exact-integer-sqrt
123
124<procedure>(exact-integer-sqrt K)</procedure>
125
126Returns two values {{s}} and {{r}}, where {{s^2 + r = K}} and {{K < (s+1)^2}}.
127In other words, {{s}} is the closest square root we can find that's equal to or
128smaller than {{K}}, and {{r}} is the rest if {{K}} isn't a neat square of two numbers.
129
130This procedure is compatible with the definition from the R7RS
131{{(scheme base)}} library.
132
133==== exact-integer-nth-root
134
135<procedure>(exact-integer-nth-root K N)</procedure>
136
137Like {{exact-integer-sqrt}}, but with any base value.  Calculates
138{{\sqrt[N]{K}}}, the {{N}}th root of {{K}} and returns two values
139{{s}} and {{r}} where {{s^N + r = K}} and {{K < (s+1)^N}}.
140
141
142==== Division with quotient and remainder
143
144<procedure>(quotient&remainder X Y)</procedure>
145<procedure>(quotient&modulo X Y)</procedure>
146
147Returns two values: the quotient and the remainder (or modulo) of
148{{X}} divided by {{Y}}.  Could be defined as {{(values (quotient X Y)
149(remainder X Y))}}, but is much more efficient when dividing very
150large numbers.
151
152==== signum
153
154<procedure>(signum N)</procedure>
155
156For real numbers, returns {{1}} if {{N}} is positive, {{-1}} if {{N}}
157is negative or {{0}} if {{N}} is zero. {{signum}} is exactness
158preserving.
159
160For complex numbers, returns a complex number of the same angle but
161with magnitude 1.
162
163
164=== Lazy evaluation
165
166==== delay-force
167
168<macro>(delay-force <expression>)</macro><br>
169
170The expression {{(delay-force expression)}} is conceptually similar to
171{{(delay (force expression))}}, with the difference that forcing the
172result of {{delay-force}} will in effect result in a tail call to
173{{(force expression)}}, while forcing the result of
174{{(delay (force expression))}} might not.
175
176Thus iterative lazy algorithms that might result in a long series of
177chains of delay and force can be rewritten using delay-force to
178prevent consuming unbounded space during evaluation.
179
180This special form is compatible with the definition from the R7RS
181{{(scheme lazy)}} library.
182
183See the description of force under
184[[Module scheme#control-features|Control features]] in the "scheme"
185module documentation for a more complete description of delayed
186evaluation.
187
189the [[http://srfi.schemers.org/srfi-45/srfi-45.html|SRFI-45]]
190rationale.
191
192==== make-promise
193
194<procedure>(make-promise obj)</procedure>
195
196The make-promise procedure returns a promise which, when forced, will
197return {{obj}} . It is similar to {{delay}}, but does not delay its
198argument: it is a procedure rather than syntax. If {{obj}} is already
199a promise, it is returned.
200
201This procedure is compatible with the definition from the R7RS
202{{(scheme lazy)}} library.
203
204
205==== promise?
206
207<procedure>(promise? X)</procedure>
208
209Returns {{#t}} if {{X}} is a promise returned by {{delay}}, or
210{{#f}} otherwise.
211
212This procedure is compatible with the definition from the R7RS
213{{(scheme lazy)}} library.
214
215
216=== Input/Output
217
218==== current-error-port
219
220<procedure>(current-error-port [PORT])</procedure>
221
222Returns default error output port. If {{PORT}} is given, then that
223port is selected as the new current error output port.
224
225Note that the default error output port is not buffered. Use
226[[Module (chicken port)#set-buffering-mode!|{{set-buffering-mode!}}]]
227if you need a different behaviour.
228
229==== print
230
231<procedure>(print [EXP1 ...])</procedure>
232
233Outputs the optional arguments {{EXP1 ...}} using {{display}} and
234writes a newline character to the port that is the value of
235{{(current-output-port)}}. Returns {{(void)}}.
236
237==== print*
238
239<procedure>(print* [EXP1 ...])</procedure>
240
241Similar to {{print}}, but does not output a terminating newline
242character and performs a {{flush-output}} after writing its arguments.
243
244
245=== Interrupts and error-handling
246
247==== enable-warnings
248
249<procedure>(enable-warnings [BOOL])</procedure>
250
251Enables or disables warnings, depending on wether {{BOOL}} is true or
252false.  If called with no arguments, this procedure returns {{#t}} if
253warnings are currently enabled, or {{#f}} otherwise. Note that this is
254not a parameter.  The current state (whether warnings are enabled or
255disabled) is global and not thread-local.
256
257
258==== error
259
260<procedure>(error [LOCATION] [STRING] EXP ...)</procedure>
261
262Prints error message, writes all extra arguments to the value of
263{{(current-error-port)}} and invokes the current
264exception-handler. This conforms to
265[[http://srfi.schemers.org/srfi-23/srfi-23.html|SRFI-23]].  If
266{{LOCATION}} is given and a symbol, it specifies the ''location'' (the
267name of the procedure) where the error occurred.
268
269
270
271==== get-call-chain
272
274
275Returns a list with the call history. Backtrace information is only
276generated in code compiled without {{-no-trace}} and evaluated code.
277If the optional argument {{START}} is given, the backtrace starts at
278this offset, i.e. when {{START}} is 1, the next to last trace-entry is
279printed, and so on. If the optional argument {{THREAD}} is given, then
280the call-chain will only be constructed for calls performed by this
282
283
284
285==== print-call-chain
286
288
289Prints a backtrace of the procedure call history to {{PORT}}, which
290defaults to {{(current-output-port)}}. The output is prefixed by the
291{{HEADER}}, which defaults to {{"\n\tCall history:\n"}}.
292
293
294==== procedure-information
295
296<procedure>(procedure-information PROC)</procedure>
297
298Returns an s-expression with debug information for the procedure
299{{PROC}}, or {{#f}}, if {{PROC}} has no associated debug information.
300
301
302==== warning
303
304<procedure>(warning STRING EXP ...)</procedure>
305
306Displays a warning message (if warnings are enabled with
307{{enable-warnings}}) and continues execution.
308
309
310=== Lists
311
312==== alist-ref
313
314<procedure>(alist-ref KEY ALIST [TEST [DEFAULT]])</procedure>
315
316Looks up {{KEY}} in {{ALIST}} using {{TEST}} as the comparison function (or {{eqv?}} if
317no test was given) and returns the cdr of the found pair, or {{DEFAULT}} (which defaults to {{#f}}).
318
319
320==== alist-update
321
322<procedure>(alist-update KEY VALUE ALIST [TEST])</procedure>
323<procedure>(alist-update! KEY VALUE ALIST [TEST])</procedure>
324
325If the list {{ALIST}} contains a pair of the form {{(KEY . X)}}, then this procedure
326replaces {{X}} with {{VALUE}} and returns {{ALIST}}. If {{ALIST}} contains no such item, then
327{{alist-update}} returns {{((KEY . VALUE) . ALIST)}}. The optional argument
328{{TEST}} specifies the comparison procedure to search a matching pair in {{ALIST}}
329and defaults to {{eqv?}}. {{alist-update!}} is the destructive version of {{alist-update}}.
330
331
332==== atom?
333
334<procedure>(atom? X)</procedure>
335
336Returns {{#t}} if {{X}} is not a pair.
337
338
339==== butlast
340
341<procedure>(butlast LIST)</procedure>
342
343Returns a fresh list with all elements but the last of {{LIST}}.
344
345
346==== chop
347
348<procedure>(chop LIST N)</procedure>
349
350Returns a new list of sublists, where each sublist contains {{N}}
351elements of {{LIST}}. If {{LIST}} has a length that is not
352a multiple of {{N}}, then the last sublist contains the remaining
353elements.
354
355<enscript highlight=scheme>
356(chop '(1 2 3 4 5 6) 2) ==> ((1 2) (3 4) (5 6))
357(chop '(a b c d) 3)     ==> ((a b c) (d))
358</enscript>
359
360
361==== compress
362
363<procedure>(compress BLIST LIST)</procedure>
364
365Returns a new list with elements taken from {{LIST}} with
366corresponding true values in the list {{BLIST}}.
367
368<enscript highlight=scheme>
369(define nums '(99 100 110 401 1234))
370(compress (map odd? nums) nums)      ==> (99 401)
371</enscript>
372
373
374==== flatten
375
376<procedure>(flatten LIST1 ...)</procedure>
377
378Returns {{LIST1 ...}} concatenated together, with nested lists
379removed (flattened).
380
381
382==== foldl
383
384<procedure>(foldl PROCEDURE INIT LIST)</procedure>
385
386Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from
387the left:
388
389<enscript hightlight=scheme>
390(foldl + 0 '(1 2 3))    ==>    (+ (+ (+ 0 1) 2) 3)
391</enscript>
392
393Note that the order of arguments taken by {{PROCEDURE}} is different
394from the {{SRFI-1}} {{fold}} procedure, but matches the more natural
395order used in Haskell and Objective Caml.
396
397
398==== foldr
399
400<procedure>(foldr PROCEDURE INIT LIST)</procedure>
401
402Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from
403the right:
404
405<enscript hightlight=scheme>
406(foldr + 0 '(1 2 3))    ==>    (+ 1 (+ 2 (+ 3 0)))
407</enscript>
408
409
410==== intersperse
411
412<procedure>(intersperse LIST X)</procedure>
413
414Returns a new list with {{X}} placed between each element.
415
416
417==== join
418
419<procedure>(join LISTOFLISTS [LIST])</procedure>
420
421Concatenates the lists in {{LISTOFLISTS}} with {{LIST}} placed
422between each sublist. {{LIST}} defaults to the empty list.
423
424<enscript highlight=scheme>
425(join '((a b) (c d) (e)) '(x y)) ==> (a b x y c d x y e)
426(join '((p q) () (r (s) t)) '(-))  ==> (p q - - r (s) t)
427</enscript>
428
429{{join}} could be implemented as follows:
430
431<enscript highlight=scheme>
432(define (join lstoflsts #!optional (lst '()))
433  (apply append (intersperse lstoflists lst)) )
434</enscript>
435
436
437==== rassoc
438
439<procedure>(rassoc KEY LIST [TEST])</procedure>
440
441Similar to {{assoc}}, but compares {{KEY}} with the {{cdr}} of each pair in {{LIST}} using
442{{TEST}} as the comparison procedures (which defaults to {{eqv?}}.
443
444
445==== tail?
446
447<procedure>(tail? X LIST)</procedure>
448
449Returns true if {{X}} is one of the tails (cdr's) of {{LIST}}.
450
451
452=== Vectors
453
454==== vector-copy!
455
456<procedure>(vector-copy! VECTOR1 VECTOR2 [COUNT])</procedure>
457
458Copies contents of {{VECTOR1}} into {{VECTOR2}}. If the
459argument {{COUNT}} is given, it specifies the maximal number of
460elements to be copied. If not given, the minimum of the lengths of the
461argument vectors is copied.
462
463Exceptions: {{(exn bounds)}}
464
465This procedure is compatible with the definition from the R7RS
466{{(scheme base)}} library.
467
468==== vector-resize
469
470<procedure>(vector-resize VECTOR N [INIT])</procedure>
471
472Creates and returns a new vector with the contents of {{VECTOR}} and
473length {{N}}. If {{N}} is greater than the original length of
474{{VECTOR}}, then all additional items are initialized to {{INIT}}. If
475{{INIT}} is not specified, the contents are initialized to some
476unspecified value.
477
478
479==== subvector
480
481<procedure>(subvector VECTOR FROM [TO])</procedure>
482
483Returns a new vector with elements taken from {{VECTOR}} in the
484given range. {{TO}} defaults to {{(vector-length VECTOR)}}.
485
486{{subvector}} was introduced in CHICKEN 4.7.3.
487
488
489=== Combinators
490
491
492==== constantly
493
494<procedure>(constantly X ...)</procedure>
495
496Returns a procedure that always returns the values {{X ...}} regardless of the number and value of its arguments.
497
498<enscript highlight=scheme>
499(constantly X) <=> (lambda args X)
500</enscript>
501
502
503==== complement
504
505<procedure>(complement PROC)</procedure>
506
507Returns a procedure that returns the boolean inverse of {{PROC}}.
508
509<enscript highlight=scheme>
510(complement PROC) <=> (lambda (x) (not (PROC x)))
511</enscript>
512
513
514==== compose
515
516<procedure>(compose PROC1 PROC2 ...)</procedure>
517
518Returns a procedure that represents the composition of the
519argument-procedures {{PROC1 PROC2 ...}}.
520
521<enscript highlight=scheme>
522(compose F G) <=> (lambda args
523                      (call-with-values
524                         (lambda () (apply G args))
525                         F))
526</enscript>
527
528{{(compose)}} is equivalent to {{values}}.
529
530
531==== conjoin
532
533<procedure>(conjoin PRED ...)</procedure>
534
535Returns a procedure that returns {{#t}} if its argument satisfies the
536predicates {{PRED ...}}.
537<enscript highlight=scheme>
538((conjoin odd? positive?) 33)   ==>  #t
539((conjoin odd? positive?) -33)  ==>  #f
540</enscript>
541
542
543==== disjoin
544
545<procedure>(disjoin PRED ...)</procedure>
546
547Returns a procedure that returns {{#t}} if its argument satisfies any
548predicate {{PRED ...}}.
549<enscript highlight=scheme>
550((disjoin odd? positive?) 32)    ==>  #t
551((disjoin odd? positive?) -32)   ==>  #f
552</enscript>
553
554
555==== each
556
557<procedure>(each PROC ...)</procedure>
558
559Returns a procedure that applies {{PROC ...}} to its arguments, and returns the result(s)
560of the last procedure application. For example
561
562<enscript highlight=scheme>
563(each pp eval)
564</enscript>
565
566is equivalent to
567
568<enscript highlight=scheme>
569(lambda args
570  (apply pp args)
571  (apply eval args) )
572</enscript>
573
574{{(each PROC)}} is equivalent to {{PROC}} and {{(each)}} is equivalent to
575{{void}}.
576
577
578==== flip
579
580<procedure>(flip PROC)</procedure>
581
582Returns a two-argument procedure that calls {{PROC}} with its
583arguments swapped:
584<enscript highlight=scheme>
585(flip PROC) <=> (lambda (x y) (PROC y x))
586</enscript>
587
588
589==== identity
590
591<procedure>(identity X)</procedure>
592
593Returns its sole argument {{X}}.
594
595
596==== list-of?
597
598<procedure>(list-of? PRED)</procedure>
599
600Returns a procedure of one argument that returns {{#t}} when
601applied to a list of elements that all satisfy the predicate procedure
602{{PRED}}, or {{#f}} otherwise.
603
604<enscript highlight=scheme>
605((list-of? even?) '(1 2 3))   ==> #f
606((list-of? number?) '(1 2 3)) ==> #t
607</enscript>
608
609
610==== o
611
612<procedure>(o PROC ...)</procedure>
613
614A single value version of {{compose}} (slightly faster). {{(o)}} is equivalent
615to {{identity}}.
616
617
618=== User-defined named characters
619
620==== char-name
621
622<procedure>(char-name SYMBOL-OR-CHAR [CHAR])</procedure>
623
624This procedure can be used to inquire about character names or to
625define new ones. With a single argument the behavior is as follows:
626If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns
627the character with this name, or {{#f}} if no character is defined
628under this name. If {{SYMBOL-OR-CHAR}} is a character, then the
629name of the character is returned as a symbol, or {{#f}} if the
630character has no associated name.
631
632If the optional argument {{CHAR}} is provided, then
633{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of
634the given character. If multiple names designate the same character,
635then the {{write}} will use the character name that was defined last.
636
637<enscript highlight=scheme>
638(char-name 'space)                  ==> #\space
639(char-name #\space)                 ==> space
640(char-name 'bell)                   ==> #f
641(char-name (integer->char 7))       ==> #f
642(char-name 'bell (integer->char 7))
643(char-name 'bell)                   ==> #\bell
644(char->integer (char-name 'bell))   ==> 7
645</enscript>
646
647
648=== The unspecified value
649
650==== void
651
652<procedure>(void ARGUMENT ...)</procedure>
653
654Ignores {{ARGUMENT ...}} and returns an unspecified value.
655
656
657=== Continuations
658
659==== call/cc
660
661<procedure>(call/cc PROCEDURE)</procedure>
662
663An alias for {{call-with-current-continuation}}.
664
665This procedure is compatible with the definition from the R7RS
666{{(scheme base)}} library.
667
668=== Symbols
669
670==== Symbol utilities
671
672===== symbol-append
673
674<procedure>(symbol-append SYMBOL1 ...)</procedure>
675
676Creates a new symbol from the concatenated names of the argument symbols
677{{(SYMBOL1 ...)}}.
678
679==== Uninterned symbols ("gensyms")
680
681Symbols may be "interned" or "uninterned". Interned symbols are
682registered in a global table, and when read back from a port are
683identical to a symbol written before:
684
685<enscript highlight=scheme>
686(define sym 'foo)
687
688(eq? sym (with-input-from-string
689            (with-output-to-string
690              (lambda () (write sym)))
692
693  => #t
694</enscript>
695
696Uninterned symbols on the other hand are not globally registered and so
697multiple symbols with the same name may coexist:
698
699<enscript highlight=scheme>
700(define sym (gensym 'foo))   ; sym is a uninterned symbol like "foo42"
701
702(eq? sym (with-input-from-string    ; the symbol read will be an interned symbol
703            (with-output-to-string
704              (lambda () (write sym)))
706
707  => #f
708
709(eq? (string->uninterned-symbol "foo") (string->uninterned-symbol "foo"))
710
711  => #f
712</enscript>
713
714Use uninterned symbols if you need to generate unique values that
715can be compared quickly, for example as keys into a hash-table
716or association list. Note that uninterned symbols lose their
717uniqueness property when written to a file and read back in, as
718in the example above.
719
720===== gensym
721
722<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
723
724Returns a newly created uninterned symbol. If an argument is provided,
725the new symbol is prefixed with that argument.
726
727
728===== string->uninterned-symbol
729
730<procedure>(string->uninterned-symbol STRING)</procedure>
731
732Returns a newly created, unique symbol with the name {{STRING}}.
733
734
735=== Setters
736
738[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
739
740==== setter
741
742<procedure>(setter PROCEDURE)</procedure>
743
744Returns the setter-procedure of {{PROCEDURE}}, or signals an error if
745{{PROCEDURE}} has no associated setter-procedure.
746
747Note that {{(set! (setter PROC) ...)}} for a procedure that has no
748associated setter procedure yet is a very slow operation (the old
749procedure is replaced by a modified copy, which involves a garbage
750collection).
751
752
753==== getter-with-setter
754
755<procedure>(getter-with-setter GETTER SETTER)</procedure>
756
757Returns a copy of the procedure {{GETTER}} with the associated setter
758procedure {{SETTER}}. Contrary to the SRFI specification, the setter
759of the returned procedure may be changed.
760
761
762=== Binding forms for optional arguments
763
764==== optional
765
766<macro>(optional ARGS DEFAULT)</macro>
767
768Use this form for procedures that take a single optional argument. If
769{{ARGS}} is the empty list {{DEFAULT}} is evaluated and
770returned, otherwise the first element of the list {{ARGS}}. It is
771an error if {{ARGS}} contains more than one value.
772
773<enscript highlight=scheme>
774(define (incr x . i) (+ x (optional i 1)))
775(incr 10)                                   ==> 11
776(incr 12 5)                                 ==> 17
777</enscript>
778
779
780==== case-lambda
781
782<macro>(case-lambda (LAMBDA-LIST1 EXP1 ...) ...)</macro>
783
784Expands into a lambda that invokes the body following the first
785matching lambda-list.
786
787<enscript highlight=scheme>
788(define plus
789  (case-lambda
790    (() 0)
791    ((x) x)
792    ((x y) (+ x y))
793    ((x y z) (+ (+ x y) z))
794    (args (apply + args))))
795
796(plus)                      ==> 0
797(plus 1)                    ==> 1
798(plus 1 2 3)                ==> 6
799</enscript>
800
802[[http://srfi.schemers.org/srfi-16/srfi-16.html|SRFI-16]]
803
804This special form is also compatible with the definition from the R7RS
805{{(scheme case-lambda)}} library.
806
807==== let-optionals
808
809<macro> (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)</macro>
810
811Binding constructs for optional procedure arguments. {{ARGS}} is
812normally a rest-parameter taken from a lambda-list. {{let-optionals}}
813binds {{VAR1 ...}} to available arguments in parallel, or to
814{{DEFAULT1 ...}} if not enough arguments were provided.
815{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable
816sees the previous ones. it is an error if any excess arguments are
817provided.
818
819<enscript highlight=scheme>
820(let-optionals '(one two) ((a 1) (b 2) (c 3))
821  (list a b c) )                               ==> (one two 3)
822</enscript>
823
824==== let-optionals*
825
826<macro> (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)</macro>
827
828Binding constructs for optional procedure arguments. {{ARGS}} is
829normally a rest-parameter taken from a lambda-list. {{let-optionals}}
830binds {{VAR1 ...}} to available arguments in parallel, or to
831{{DEFAULT1 ...}} if not enough arguments were provided.
832{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable
833sees the previous ones. If a single variable {{RESTVAR}} is given,
834then it is bound to any remaining arguments, otherwise it is an error
835if any excess arguments are provided.
836
837<enscript highlight=scheme>
838(let-optionals* '(one two) ((a 1) (b 2) (c a))
839  (list a b c) )                               ==> (one two one)
840</enscript>
841
842=== Other binding forms
843
844==== and-let*
845
846<macro>(and-let* (BINDING ...) EXP1 EXP2 ...)</macro>
847
848Bind sequentially and execute body. {{BINDING}} can
849be a list of a variable and an expression, a list with a single
850expression, or a single variable. If the value of an expression
851bound to a variable is {{#f}}, the {{and-let*}} form
852evaluates to {{#f}} (and the subsequent bindings and the body
853are not executed).  Otherwise the next binding is performed. If
854all bindings/expressions evaluate to a true result, the body is
855executed normally and the result of the last expression is the
857[[http://srfi.schemers.org/srfi-2/srfi-2.html|SRFI-2]].
858
859==== letrec*
860
861<macro>(letrec* ((VARIABLE EXPRESSION) ...) BODY ...)</macro>
862
863Implements R6RS/R7RS {{letrec*}}. {{letrec*}} is similar to {{letrec}}
864but binds the variables sequentially and is to {{letrec}} what
865{{let*}} is to {{let}}.
866
867This special form is compatible with the definition from the R7RS
868{{(scheme base)}} library.
869
870==== rec
871
872<macro>(rec NAME EXPRESSION)</macro><br>
873<macro>(rec (NAME VARIABLE ...) BODY ...)</macro>
874
875Allows simple definition of recursive definitions. {{(rec NAME EXPRESSION)}} is
876equivalent to {{(letrec ((NAME EXPRESSION)) NAME)}} and {{(rec (NAME VARIABLE ...) BODY ...)}}
877is the same as {{(letrec ((NAME (lambda (VARIABLE ...) BODY ...))) NAME)}}.
878
879==== cut
880
881<macro>(cut SLOT ...)</macro><br>
882<macro>(cute SLOT ...)</macro>
883
884[[http://srfi.schemers.org/srfi-26/srfi-26.html|Syntactic sugar for specializing parameters]].
885
886==== define-values
887
888<macro>(define-values (NAME ...) VALUEEXP)</macro>
889<macro>(define-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>
890<macro>(define-values NAME VALUEEXP)</macro>
891
892Defines several variables at once, with the result values of expression
893{{VALUEEXP}}, similar to {{set!-values}}.
894
895This special form is compatible with the definition from the R7RS
896{{(scheme base)}} library.
897
898==== fluid-let
899
900<macro>(fluid-let ((VAR1 X1) ...) BODY ...)</macro>
901
902Binds the variables {{VAR1 ...}} dynamically to the values {{X1 ...}}
903during execution of {{BODY ...}}.  This implements
904[[http://srfi.schemers.org/srfi-15/srfi-15.html|SRFI-15]].
905
906==== let-values
907
908<macro>(let-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
909
910Binds multiple variables to the result values of {{VALUEEXP ...}}.
911All variables are bound simultaneously.  Like {{define-values}}, the
912{{(NAME ...)}} expression can be any basic lambda list (dotted tail
913notation is supported).
914
915This special form implements
916[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]], and it is
917also compatible with the definition from the R7RS {{(scheme base)}}
918library.
919
920
921==== let*-values
922
923<macro>(let*-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
924
925Binds multiple variables to the result values of {{VALUEEXP ...}}.
926The variables are bound sequentially.  Like {{let-values}}, the
927{{(NAME ...)}} expression can be any basic lambda list (dotted tail
928notation is supported).
929
930This is also part of
931[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]] and is also
932compatible with the definition from the R7RS {{(scheme base)}}
933library.
934
935<enscript highlight=scheme>
936(let*-values (((a b) (values 2 3))
937              ((p) (+ a b)) )
938  p)                               ==> 5
939</enscript>
940
941==== letrec-values
942
943<macro>(letrec-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
944
945Binds the result values of {{VALUEEXP ...}} to multiple variables at
946once.  All variables are mutually recursive.  Like {{let-values}}, the
947{{(NAME ...)}} expression can be any basic lambda list (dotted tail
948notation is supported).
949
950<enscript highlight=scheme>
951(letrec-values (((odd even)
952                   (values
953                     (lambda (n) (if (zero? n) #f (even (sub1 n))))
954                     (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )
955  (odd 17) )                           ==> #t
956</enscript>
957
958
960
961<macro>(receive (NAME ...) VALUEEXP BODY ...)</macro><br>
962<macro>(receive (NAME1 ... NAMEn . NAMEn+1) VALUEEXP BODY ...)</macro><br>
965
966[[http://srfi.schemers.org/srfi-8/srfi-8.html|SRFI-8]].
967Syntactic sugar for {{call-with-values}}. Binds variables
968to the result values of {{VALUEEXP}} and evaluates {{BODY ...}},
969similar {{define-values}} but lexically scoped.
970
972This shortened form is not described by SRFI-8.
973
974==== set!-values
975
976<macro>(set!-values (NAME ...) VALUEEXP)</macro>
977<macro>(set!-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>
978<macro>(set!-values NAME VALUEEXP)</macro>
979
980Assigns the result values of expression {{VALUEEXP}} to multiple
981variables, similar to {{define-values}}.
982
983==== nth-value
984
985<macro>(nth-value N EXP)</macro>
986
987Returns the {{N}}th value (counting from zero) of the values returned
988by expression {{EXP}}.
989
990
991=== Parameters
992
993Parameters are CHICKEN's form of dynamic variables, except that they are
994procedures rather than actual variables.  A parameter is a procedure of
995zero or one arguments. To retrieve the value of a parameter call the
996parameter-procedure with zero arguments. To change the setting of the
997parameter, call the parameter-procedure with the new value as argument:
998
999<enscript highlight=scheme>
1000(define foo (make-parameter 123))
1001(foo)                             ==> 123
1002(foo 99)
1003(foo)                             ==> 99
1004</enscript>
1005
1007owns a local copy of a parameters' value.
1008
1009CHICKEN implements
1010[[http://srfi.schemers.org/srfi-39/srfi-39.html|SRFI-39]], which
1011is also standardized by R7RS.
1012
1013
1014==== parameterize
1015
1016<macro>(parameterize ((PARAMETER1 X1) ...) BODY ...)</macro>
1017
1018Binds the parameters {{PARAMETER1 ...}} dynamically to the values
1020{{make-parameter}} in [[Parameters]]). Note that {{PARAMETER}} may
1021be any expression that evaluates to a parameter procedure.
1022
1023This special form is compatible with the definition from the R7RS
1024{{(scheme base)}} library.
1025
1026==== make-parameter
1027
1028<procedure>(make-parameter VALUE [GUARD])</procedure>
1029
1030Returns a procedure that accepts zero or one argument. Invoking the
1031procedure with zero arguments returns {{VALUE}}. Invoking the
1032procedure with one argument changes its value to the value of that
1033argument and returns the new value (subsequent invocations with zero
1034parameters return the new value). {{GUARD}} should be a procedure of a
1035single argument. Any new values of the parameter (even the initial
1036value) are passed to this procedure. The guard procedure should check
1037the value and/or convert it to an appropriate form.
1038
1039This special form is compatible with the definition from the R7RS
1040{{(scheme base)}} library.
1041
1042=== Substitution forms and macros
1043
1044==== define-constant
1045
1046<macro>(define-constant NAME CONST)</macro>
1047
1048Defines a variable with a constant value, evaluated at compile-time.
1049Any reference to such a constant should appear textually '''after'''
1050its definition. This construct is equivalent to {{define}} when
1051evaluated or interpreted.  Constant definitions should only appear at
1052toplevel. Note that constants are local to the current compilation
1053unit and are not available outside of the source file in which they
1054are defined. Names of constants still exist in the Scheme namespace
1055and can be lexically shadowed.  If the value is mutable, then the
1056compiler is careful to preserve its identity.  {{CONST}} may be any
1057constant expression, and may also refer to constants defined via
1058{{define-constant}} previously, but it must be possible to
1059evaluate the expression at compile-time.
1060
1061==== define-inline
1062
1063<macro>(define-inline (NAME VAR ...) BODY ...)</macro><br>
1064<macro>(define-inline (NAME VAR ... . VAR) BODY ...)</macro><br>
1065<macro>(define-inline NAME EXP)</macro>
1066
1067Defines an inline procedure. Any occurrence of {{NAME}} will be replaced
1068by {{EXP}} or {{(lambda (VAR ... [. VAR]) BODY ...)}}. This is similar
1069to a macro, but variable names and scope are handled correctly.
1070
1071Inline substitutions take place '''after''' macro-expansion, and any
1072reference to {{NAME}} should appear textually '''after''' its
1073definition. Inline procedures are local to the current compilation unit
1074and are not available outside of the source file in which they are
1075defined. Names of inline procedures still exist in the Scheme namespace
1076and can be lexically shadowed. Inline definitions should only appear at
1077the toplevel.
1078
1079Note that the {{inline-limit}} compiler option does not affect inline
1080procedure expansion, and self-referential inline procedures may cause
1081the compiler to enter an infinite loop.
1082
1083In the third form, {{EXP}} must be a lambda expression.
1084
1085This construct is equivalent to {{define}} when evaluated or
1086interpreted.
1087
1088
1089=== Conditional forms
1090
1091==== select
1092
1093<macro>(select EXP ((KEY ...) EXP1 ...) ... [(else EXPn ...)])</macro>
1094
1095This is similar to {{case}}, but the keys are evaluated.
1096
1097==== unless
1098
1099<macro>(unless TEST EXP1 EXP2 ...)</macro>
1100
1101Equivalent to:
1102
1103<enscript highlight=scheme>
1104(if (not TEST) (begin EXP1 EXP2 ...))
1105</enscript>
1106
1107==== when
1108
1109<macro>(when TEST EXP1 EXP2 ...)</macro>
1110
1111Equivalent to:
1112
1113<enscript highlight=scheme>
1114(if TEST (begin EXP1 EXP2 ...))
1115</enscript>
1116
1117
1118=== Record structures
1119
1120==== define-record
1121
1122<macro>(define-record NAME SLOTNAME ...)</macro>
1123
1124Defines a record type. This defines a number of procedures for
1125creating, accessing, and modifying record members.
1126
1127Call {{make-NAME}} to create an instance
1128of the structure (with one initialization-argument for each slot, in
1129the listed order).
1130
1131{{(NAME? STRUCT)}} tests any object for being an instance of this
1132structure.
1133
1134Slots are accessed via {{(NAME-SLOTNAME STRUCT)}}
1135and updated using {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
1136
1137<enscript highlight=scheme>
1138(define-record point x y)
1139(define p1 (make-point 123 456))
1140(point? p1)                      ==> #t
1141(point-x p1)                     ==> 123
1142(point-y-set! p1 99)
1143(point-y p1)                     ==> 99
1144</enscript>
1145
1146===== SRFI-17 setters
1147
1148{{SLOTNAME}} may alternatively also be of the form
1149
1150  (setter SLOTNAME)
1151
1152In this case the slot can be read with {{(NAME-SLOTNAME STRUCT)}} as usual,
1153and modified with {{(set! (NAME-SLOTNAME STRUCT) VALUE)}} (the slot-accessor
1154has an associated SRFI-17 "setter" procedure) instead of
1155the usual {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
1156
1157
1158<enscript highlight=scheme>
1159(define-record point (setter x) (setter y))
1160(define p1 (make-point 123 456))
1161(point? p1)                      ==> #t
1162(point-x p1)                     ==> 123
1163(set! (point-y p1) 99)
1164(point-y p1)                     ==> 99
1165</enscript>
1166
1167==== define-record-type
1168
1169<macro>(define-record-type NAME (CONSTRUCTOR TAG ...) PREDICATE (FIELD ACCESSOR [MODIFIER]) ...)</macro>
1170
1172[[http://srfi.schemers.org/srfi-9/srfi-9.html|SRFI-9]].
1173
1174As an extension the {{MODIFIER}} may have the form
1175{{(setter PROCEDURE)}}, which will define a SRFI-17 setter-procedure
1176for the given {{PROCEDURE}} that sets the field value.
1177Usually {{PROCEDURE}} has the same name is {{ACCESSOR}} (but it
1178doesn't have to).
1179
1180This special form is also compatible with the definition from the R7RS
1181{{(scheme base)}} library.
1182
1183
1184==== define-record-printer
1185
1186<macro>(define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)</macro><br>
1187<macro>(define-record-printer NAME PROCEDURE)</macro>
1188
1189Defines a printing method for record of the type {{NAME}} by
1190associating a procedure with the record type. When a record of this
1191type is written using {{display, write}} or {{print}}, then
1192the procedure is called with two arguments: the record to be printed
1193and an output-port.
1194
1195<enscript highlight=scheme>
1196(define-record-type foo (make-foo x y z) foo?
1197  (x foo-x)
1198  (y foo-y)
1199  (z foo-z))
1200(define f (make-foo 1 2 3))
1201(define-record-printer (foo x out)
1202  (fprintf out "#,(foo ~S ~S ~S)"
1203           (foo-x x) (foo-y x) (foo-z x)) )
1205(define s (with-output-to-string
1206              (lambda () (write f))))
1207s                                   ==> "#,(foo 1 2 3)"
1208(equal? f (with-input-from-string
1210</enscript>
1211
1212=== Other forms
1213
1214==== include
1215
1216<macro>(include STRING)</macro>
1217
1218Include toplevel-expressions from the given source file in the currently
1219compiled/interpreted program.  If the included file has the extension
1220{{.scm}}, then it may be omitted. The file is searched for in the
1221current directory and all directories specified by the {{-include-path}}
1222option.
1223
1224==== include-relative
1225
1226<macro>(include-relative STRING)</macro>
1227
1228Works like {{include}}, but the filename is searched for relative to the
1229including file rather than the current directory.
1230
1231
1232=== Making extra libraries and extensions available
1233
1234==== require-extension
1235
1236<macro>(require-extension ID ...)</macro>
1237
1238This is equivalent to {{(require-library ID ...)}} but performs an implicit
1239{{import}}, if necessary. Since version 4.4.0, {{ID}} may also be an import specification
1240(using {{rename}}, {{only}}, {{except}} or {{prefix}}).
1241
1242To make long matters short - just use {{require-extension}} and it will normally figure everything out for dynamically
1243loadable extensions and core library units.
1244
1245This implementation of {{require-extension}} is compliant with [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]]
1247
1248
1249==== require-library
1250
1251<macro>(require-library ID ...)</macro>
1252
1253This form does all the necessary steps to make the libraries or extensions given
1254in {{ID ...}} available. It loads syntactic extensions, if needed and generates
1256extensions.
1257
1258During interpretation/evaluation {{require-library}} performs one of the
1259following:
1260
1261* 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.
1262* If {{ID}} names one of the syntactic extensions {{chicken-syntax chicken-ffi-syntax}}, then this extension will be loaded.
1263* If {{ID}} names one of the core library units shipped with CHICKEN, then a {{(load-library 'ID)}} will be performed.
1264* 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.
1265* Otherwise, {{(require-library ID)}} is equivalent to {{(require 'ID)}}.
1266
1267During compilation, one of the following happens instead:
1268
1269* 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.
1270* 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.
1271* 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.
1272* 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.
1273* Otherwise {{(require-library ID)}} is equivalent to {{(require 'ID)}}.
1274
1275{{ID}} should be a pure extension name and should not contain any path prefixes (for example {{dir/lib...}} is illegal).
1276
1277{{ID}} may also be a list that designates an extension-specifier. Currently the following extension specifiers are
1278defined:
1279
1280* {{(srfi NUMBER ...)}} is required for SRFI-55 compatibility and is fully implemented
1281* {{(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>=?}}).
1282
1283TODO: Document declare (keep the "declarations" section?)
1284
1285=== Process shutdown
1286
1287==== emergency-exit
1288
1289<procedure>(emergency-exit [CODE])</procedure>
1290
1291Exits the current process without flushing any buffered output (using
1292the C function {{_exit}}).  Note that the {{exit-handler}} is not called
1293when this procedure is invoked. The optional exit status code {{CODE}}
1294defaults to {{0}}.
1295
1296
1297==== exit
1298
1299<procedure>(exit [CODE])</procedure>
1300
1301Exit the running process and return exit-code, which defaults to 0
1302(Invokes {{exit-handler}}).
1303
1304Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
1305
1306
1307=== exit-handler
1308
1309<parameter>(exit-handler)</parameter>
1310
1311A procedure of a single optional argument. When {{exit}} is called,
1312then this procedure will be invoked with the exit-code as argument. The
1313default behavior is to terminate the program.
1314
1315Note that this handler is ''not'' invoked when {{emergency-exit}} is
1316used.
1317
1318
1319=== implicit-exit-handler
1320
1321<parameter>(implicit-exit-handler)</parameter>
1322
1323A procedure of no arguments. When the last toplevel expression of the
1324program has executed, then the value of this parameter is called. The
1325default behaviour is to invoke all pending finalizers.
1326
1327
1328==== on-exit
1329
1330<procedure>(on-exit THUNK)</procedure>
1331
1332Schedules the zero-argument procedures {{THUNK}} to be executed before
1333the process exits, either explicitly via {{exit}} or implicitly after
1334execution of the last top-level form. Note that finalizers for
1335unreferenced finalized data are run before exit procedures.
1336
1337
1338=== System interface
1339
1340
1341==== sleep
1342
1343<procedure>(sleep SECONDS)</procedure>
1344
1345Puts the program to sleep for {{SECONDS}}. If the scheduler is loaded
1346(for example when srfi-18 is in use) then only the calling thread is put
1347to sleep and other threads may continue executing. Otherwise, the whole
1348process is put to sleep.
1349
1350
1351=== Ports
1352
1353==== String ports
1354
1355===== get-output-string
1356
1357<procedure>(get-output-string PORT)</procedure>
1358
1359Returns accumulated output of a port created with
1360{{(open-output-string)}}.
1361
1362
1363===== open-input-string
1364
1365<procedure>(open-input-string STRING)</procedure>
1366
1367Returns a port for reading from {{STRING}}.
1368
1369
1370===== open-output-string
1371
1372<procedure>(open-output-string)</procedure>
1373
1374Returns a port for accumulating output in a string.
1375
1376
1377=== File Input/Output
1378
1379==== flush-output
1380
1381<procedure>(flush-output [PORT])</procedure>
1382
1383Write buffered output to the given output-port. {{PORT}} defaults
1384to the value of {{(current-output-port)}}.
1385
1386=== Port predicates
1387
1388==== input-port-open?
1389
1390<procedure>(input-port-open? PORT)</procedure>
1391
1392Is the given {{PORT}} open for input?
1393
1394<procedure>(output-port-open? PORT)</procedure>
1395
1396Is the given {{PORT}} open for output?
1397
1398==== port-closed?
1399
1400<procedure>(port-closed? PORT)</procedure>
1401
1402Is the given {{PORT}} closed (in all directions)?
1403
1404==== port?
1405
1406<procedure>(port? X)</procedure>
1407
1408Returns {{#t}} if {{X}} is a port object or {{#f}}
1409otherwise.
1410
1411
1412=== Built-in parameters
1413
1414Certain behavior of the interpreter and compiled programs can be
1415customized via the following built-in parameters:
1416
1417==== case-sensitive
1418
1419<parameter>(case-sensitive)</parameter>
1420
1422case-sensitive mode and uppercase characters in symbols are printed
1423escaped. Defaults to {{#t}}.
1424
1425
1426==== keyword-style
1427
1428<parameter>(keyword-style)</parameter>
1429
1430Enables alternative keyword syntax, where {{STYLE}} may be either
1431{{#:prefix}} (as in Common Lisp), which recognizes symbols beginning
1432with a colon as keywords, or {{#:suffix}} (as in DSSSL), which recognizes
1433symbols ending with a colon as keywords.
1434Any other value disables the alternative syntaxes.  In the interpreter
1435the default is {{#:suffix}}.
1436
1437
1438==== parenthesis-synonyms
1439
1440<parameter>(parenthesis-synonyms)</parameter>
1441
1442If true, then the list delimiter synonyms {{#$}} {{#$}} and {{#\{}} {{#\}}} are enabled. Defaults to {{#t}}.
1443
1444
1445==== symbol-escape
1446
1447<parameter>(symbol-escape)</parameter>
1448
1449If true, then the symbol escape {{#\|}} {{#\|}} is enabled. Defaults to {{#t}}.
1450
1451
1452---
1453Previous: [[Module srfi-4]]
1454
1455Next: [[Module (chicken bitwise)]]
Note: See TracBrowser for help on using the repository browser.