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

Last change on this file since 35113 was 35113, checked in by sjamaan, 4 months ago

man/5: Move port procedure documentation. Unit library is now empty!

File size: 40.8 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==== alist-ref
310
311<procedure>(alist-ref KEY ALIST [TEST [DEFAULT]])</procedure>
312
313Looks up {{KEY}} in {{ALIST}} using {{TEST}} as the comparison function (or {{eqv?}} if
314no test was given) and returns the cdr of the found pair, or {{DEFAULT}} (which defaults to {{#f}}).
315
316
317==== alist-update
318
319<procedure>(alist-update KEY VALUE ALIST [TEST])</procedure>
320<procedure>(alist-update! KEY VALUE ALIST [TEST])</procedure>
321
322If the list {{ALIST}} contains a pair of the form {{(KEY . X)}}, then this procedure
323replaces {{X}} with {{VALUE}} and returns {{ALIST}}. If {{ALIST}} contains no such item, then
324{{alist-update}} returns {{((KEY . VALUE) . ALIST)}}. The optional argument
325{{TEST}} specifies the comparison procedure to search a matching pair in {{ALIST}}
326and defaults to {{eqv?}}. {{alist-update!}} is the destructive version of {{alist-update}}.
327
328
329==== atom?
330
331<procedure>(atom? X)</procedure>
332
333Returns {{#t}} if {{X}} is not a pair.
334
335
336==== butlast
337
338<procedure>(butlast LIST)</procedure>
339
340Returns a fresh list with all elements but the last of {{LIST}}.
341
342
343==== chop
344
345<procedure>(chop LIST N)</procedure>
346
347Returns a new list of sublists, where each sublist contains {{N}}
348elements of {{LIST}}. If {{LIST}} has a length that is not
349a multiple of {{N}}, then the last sublist contains the remaining
350elements.
351
352<enscript highlight=scheme>
353(chop '(1 2 3 4 5 6) 2) ==> ((1 2) (3 4) (5 6))
354(chop '(a b c d) 3)     ==> ((a b c) (d))
355</enscript>
356
357
358==== compress
359
360<procedure>(compress BLIST LIST)</procedure>
361
362Returns a new list with elements taken from {{LIST}} with
363corresponding true values in the list {{BLIST}}.
364
365<enscript highlight=scheme>
366(define nums '(99 100 110 401 1234))
367(compress (map odd? nums) nums)      ==> (99 401)
368</enscript>
369
370
371==== flatten
372
373<procedure>(flatten LIST1 ...)</procedure>
374
375Returns {{LIST1 ...}} concatenated together, with nested lists
376removed (flattened).
377
378
379==== foldl
380
381<procedure>(foldl PROCEDURE INIT LIST)</procedure>
382
383Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from
384the left:
385
386<enscript hightlight=scheme>
387(foldl + 0 '(1 2 3))    ==>    (+ (+ (+ 0 1) 2) 3)
388</enscript>
389
390Note that the order of arguments taken by {{PROCEDURE}} is different
391from the {{SRFI-1}} {{fold}} procedure, but matches the more natural
392order used in Haskell and Objective Caml.
393
394
395==== foldr
396
397<procedure>(foldr PROCEDURE INIT LIST)</procedure>
398
399Applies {{PROCEDURE}} to the elements from {{LIST}}, beginning from
400the right:
401
402<enscript hightlight=scheme>
403(foldr + 0 '(1 2 3))    ==>    (+ 1 (+ 2 (+ 3 0)))
404</enscript>
405
406
407==== intersperse
408
409<procedure>(intersperse LIST X)</procedure>
410
411Returns a new list with {{X}} placed between each element.
412
413
414==== join
415
416<procedure>(join LISTOFLISTS [LIST])</procedure>
417
418Concatenates the lists in {{LISTOFLISTS}} with {{LIST}} placed
419between each sublist. {{LIST}} defaults to the empty list.
420
421<enscript highlight=scheme>
422(join '((a b) (c d) (e)) '(x y)) ==> (a b x y c d x y e)
423(join '((p q) () (r (s) t)) '(-))  ==> (p q - - r (s) t)
424</enscript>
425
426{{join}} could be implemented as follows:
427
428<enscript highlight=scheme>
429(define (join lstoflsts #!optional (lst '()))
430  (apply append (intersperse lstoflists lst)) )
431</enscript>
432
433
434==== rassoc
435
436<procedure>(rassoc KEY LIST [TEST])</procedure>
437
438Similar to {{assoc}}, but compares {{KEY}} with the {{cdr}} of each pair in {{LIST}} using
439{{TEST}} as the comparison procedures (which defaults to {{eqv?}}.
440
441
442==== tail?
443
444<procedure>(tail? X LIST)</procedure>
445
446Returns true if {{X}} is one of the tails (cdr's) of {{LIST}}.
447
448
449=== Vectors
450
451==== vector-copy!
452
453<procedure>(vector-copy! VECTOR1 VECTOR2 [COUNT])</procedure>
454
455Copies contents of {{VECTOR1}} into {{VECTOR2}}. If the
456argument {{COUNT}} is given, it specifies the maximal number of
457elements to be copied. If not given, the minimum of the lengths of the
458argument vectors is copied.
459
460Exceptions: {{(exn bounds)}}
461
462This procedure is compatible with the definition from the R7RS
463{{(scheme base)}} library.
464
465==== vector-resize
466
467<procedure>(vector-resize VECTOR N [INIT])</procedure>
468
469Creates and returns a new vector with the contents of {{VECTOR}} and
470length {{N}}. If {{N}} is greater than the original length of
471{{VECTOR}}, then all additional items are initialized to {{INIT}}. If
472{{INIT}} is not specified, the contents are initialized to some
473unspecified value.
474
475
476==== subvector
477
478<procedure>(subvector VECTOR FROM [TO])</procedure>
479
480Returns a new vector with elements taken from {{VECTOR}} in the
481given range. {{TO}} defaults to {{(vector-length VECTOR)}}.
482
483{{subvector}} was introduced in CHICKEN 4.7.3.
484
485
486=== Combinators
487
488
489==== constantly
490
491<procedure>(constantly X ...)</procedure>
492
493Returns a procedure that always returns the values {{X ...}} regardless of the number and value of its arguments.
494
495<enscript highlight=scheme>
496(constantly X) <=> (lambda args X)
497</enscript>
498
499
500==== complement
501
502<procedure>(complement PROC)</procedure>
503
504Returns a procedure that returns the boolean inverse of {{PROC}}.
505
506<enscript highlight=scheme>
507(complement PROC) <=> (lambda (x) (not (PROC x)))
508</enscript>
509
510
511==== compose
512
513<procedure>(compose PROC1 PROC2 ...)</procedure>
514
515Returns a procedure that represents the composition of the
516argument-procedures {{PROC1 PROC2 ...}}.
517
518<enscript highlight=scheme>
519(compose F G) <=> (lambda args
520                      (call-with-values
521                         (lambda () (apply G args))
522                         F))
523</enscript>
524
525{{(compose)}} is equivalent to {{values}}.
526
527
528==== conjoin
529
530<procedure>(conjoin PRED ...)</procedure>
531
532Returns a procedure that returns {{#t}} if its argument satisfies the
533predicates {{PRED ...}}.
534<enscript highlight=scheme>
535((conjoin odd? positive?) 33)   ==>  #t
536((conjoin odd? positive?) -33)  ==>  #f
537</enscript>
538
539
540==== disjoin
541
542<procedure>(disjoin PRED ...)</procedure>
543
544Returns a procedure that returns {{#t}} if its argument satisfies any
545predicate {{PRED ...}}.
546<enscript highlight=scheme>
547((disjoin odd? positive?) 32)    ==>  #t
548((disjoin odd? positive?) -32)   ==>  #f
549</enscript>
550
551
552==== each
553
554<procedure>(each PROC ...)</procedure>
555
556Returns a procedure that applies {{PROC ...}} to its arguments, and returns the result(s)
557of the last procedure application. For example
558
559<enscript highlight=scheme>
560(each pp eval)
561</enscript>
562
563is equivalent to
564
565<enscript highlight=scheme>
566(lambda args
567  (apply pp args)
568  (apply eval args) )
569</enscript>
570
571{{(each PROC)}} is equivalent to {{PROC}} and {{(each)}} is equivalent to
572{{void}}.
573
574
575==== flip
576
577<procedure>(flip PROC)</procedure>
578
579Returns a two-argument procedure that calls {{PROC}} with its
580arguments swapped:
581<enscript highlight=scheme>
582(flip PROC) <=> (lambda (x y) (PROC y x))
583</enscript>
584
585
586==== identity
587
588<procedure>(identity X)</procedure>
589
590Returns its sole argument {{X}}.
591
592
593==== list-of?
594
595<procedure>(list-of? PRED)</procedure>
596
597Returns a procedure of one argument that returns {{#t}} when
598applied to a list of elements that all satisfy the predicate procedure
599{{PRED}}, or {{#f}} otherwise.
600
601<enscript highlight=scheme>
602((list-of? even?) '(1 2 3))   ==> #f
603((list-of? number?) '(1 2 3)) ==> #t
604</enscript>
605
606
607==== o
608
609<procedure>(o PROC ...)</procedure>
610
611A single value version of {{compose}} (slightly faster). {{(o)}} is equivalent
612to {{identity}}.
613
614
615=== User-defined named characters
616
617==== char-name
618
619<procedure>(char-name SYMBOL-OR-CHAR [CHAR])</procedure>
620
621This procedure can be used to inquire about character names or to
622define new ones. With a single argument the behavior is as follows:
623If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns
624the character with this name, or {{#f}} if no character is defined
625under this name. If {{SYMBOL-OR-CHAR}} is a character, then the
626name of the character is returned as a symbol, or {{#f}} if the
627character has no associated name.
628
629If the optional argument {{CHAR}} is provided, then
630{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of
631the given character. If multiple names designate the same character,
632then the {{write}} will use the character name that was defined last.
633
634<enscript highlight=scheme>
635(char-name 'space)                  ==> #\space
636(char-name #\space)                 ==> space
637(char-name 'bell)                   ==> #f
638(char-name (integer->char 7))       ==> #f
639(char-name 'bell (integer->char 7))
640(char-name 'bell)                   ==> #\bell
641(char->integer (char-name 'bell))   ==> 7
642</enscript>
643
644
645=== The unspecified value
646
647==== void
648
649<procedure>(void ARGUMENT ...)</procedure>
650
651Ignores {{ARGUMENT ...}} and returns an unspecified value.
652
653
654=== Continuations
655
656==== call/cc
657
658<procedure>(call/cc PROCEDURE)</procedure>
659
660An alias for {{call-with-current-continuation}}.
661
662This procedure is compatible with the definition from the R7RS
663{{(scheme base)}} library.
664
665=== Symbols
666
667==== Symbol utilities
668
669===== symbol-append
670
671<procedure>(symbol-append SYMBOL1 ...)</procedure>
672
673Creates a new symbol from the concatenated names of the argument symbols
674{{(SYMBOL1 ...)}}.
675
676==== Uninterned symbols ("gensyms")
677
678Symbols may be "interned" or "uninterned". Interned symbols are
679registered in a global table, and when read back from a port are
680identical to a symbol written before:
681
682<enscript highlight=scheme>
683(define sym 'foo)
684
685(eq? sym (with-input-from-string
686            (with-output-to-string
687              (lambda () (write sym)))
688            read))
689
690  => #t
691</enscript>
692
693Uninterned symbols on the other hand are not globally registered and so
694multiple symbols with the same name may coexist:
695
696<enscript highlight=scheme>
697(define sym (gensym 'foo))   ; sym is a uninterned symbol like "foo42"
698
699(eq? sym (with-input-from-string    ; the symbol read will be an interned symbol
700            (with-output-to-string
701              (lambda () (write sym)))
702            read))
703
704  => #f
705
706(eq? (string->uninterned-symbol "foo") (string->uninterned-symbol "foo"))
707
708  => #f
709</enscript>
710
711Use uninterned symbols if you need to generate unique values that
712can be compared quickly, for example as keys into a hash-table
713or association list. Note that uninterned symbols lose their
714uniqueness property when written to a file and read back in, as
715in the example above.
716
717===== gensym
718
719<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
720
721Returns a newly created uninterned symbol. If an argument is provided,
722the new symbol is prefixed with that argument.
723
724
725===== string->uninterned-symbol
726
727<procedure>(string->uninterned-symbol STRING)</procedure>
728
729Returns a newly created, unique symbol with the name {{STRING}}.
730
731
732=== Setters
733
734SRFI-17 is fully implemented. For more information see:
735[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
736
737==== setter
738
739<procedure>(setter PROCEDURE)</procedure>
740
741Returns the setter-procedure of {{PROCEDURE}}, or signals an error if
742{{PROCEDURE}} has no associated setter-procedure.
743
744Note that {{(set! (setter PROC) ...)}} for a procedure that has no
745associated setter procedure yet is a very slow operation (the old
746procedure is replaced by a modified copy, which involves a garbage
747collection).
748
749
750==== getter-with-setter
751
752<procedure>(getter-with-setter GETTER SETTER)</procedure>
753
754Returns a copy of the procedure {{GETTER}} with the associated setter
755procedure {{SETTER}}. Contrary to the SRFI specification, the setter
756of the returned procedure may be changed.
757
758
759=== Binding forms for optional arguments
760
761==== optional
762
763<macro>(optional ARGS DEFAULT)</macro>
764
765Use this form for procedures that take a single optional argument. If
766{{ARGS}} is the empty list {{DEFAULT}} is evaluated and
767returned, otherwise the first element of the list {{ARGS}}. It is
768an error if {{ARGS}} contains more than one value.
769
770<enscript highlight=scheme>
771(define (incr x . i) (+ x (optional i 1)))
772(incr 10)                                   ==> 11
773(incr 12 5)                                 ==> 17
774</enscript>
775
776
777==== case-lambda
778
779<macro>(case-lambda (LAMBDA-LIST1 EXP1 ...) ...)</macro>
780
781Expands into a lambda that invokes the body following the first
782matching lambda-list.
783
784<enscript highlight=scheme>
785(define plus
786  (case-lambda
787    (() 0)
788    ((x) x)
789    ((x y) (+ x y))
790    ((x y z) (+ (+ x y) z))
791    (args (apply + args))))
792
793(plus)                      ==> 0
794(plus 1)                    ==> 1
795(plus 1 2 3)                ==> 6
796</enscript>
797
798For more information see the documentation for
799[[http://srfi.schemers.org/srfi-16/srfi-16.html|SRFI-16]]
800
801This special form is also compatible with the definition from the R7RS
802{{(scheme case-lambda)}} library.
803
804==== let-optionals
805
806<macro> (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)</macro>
807
808Binding constructs for optional procedure arguments. {{ARGS}} is
809normally a rest-parameter taken from a lambda-list. {{let-optionals}}
810binds {{VAR1 ...}} to available arguments in parallel, or to
811{{DEFAULT1 ...}} if not enough arguments were provided.
812{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable
813sees the previous ones. it is an error if any excess arguments are
814provided.
815
816<enscript highlight=scheme>
817(let-optionals '(one two) ((a 1) (b 2) (c 3))
818  (list a b c) )                               ==> (one two 3)
819</enscript>
820
821==== let-optionals*
822
823<macro> (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)</macro>
824
825Binding constructs for optional procedure arguments. {{ARGS}} is
826normally a rest-parameter taken from a lambda-list. {{let-optionals}}
827binds {{VAR1 ...}} to available arguments in parallel, or to
828{{DEFAULT1 ...}} if not enough arguments were provided.
829{{let-optionals*}} binds {{VAR1 ...}} sequentially, so every variable
830sees the previous ones. If a single variable {{RESTVAR}} is given,
831then it is bound to any remaining arguments, otherwise it is an error
832if any excess arguments are provided.
833
834<enscript highlight=scheme>
835(let-optionals* '(one two) ((a 1) (b 2) (c a))
836  (list a b c) )                               ==> (one two one)
837</enscript>
838
839=== Other binding forms
840
841==== and-let*
842
843<macro>(and-let* (BINDING ...) EXP1 EXP2 ...)</macro>
844
845Bind sequentially and execute body. {{BINDING}} can
846be a list of a variable and an expression, a list with a single
847expression, or a single variable. If the value of an expression
848bound to a variable is {{#f}}, the {{and-let*}} form
849evaluates to {{#f}} (and the subsequent bindings and the body
850are not executed).  Otherwise the next binding is performed. If
851all bindings/expressions evaluate to a true result, the body is
852executed normally and the result of the last expression is the
853result of the {{and-let*}} form. See also the documentation for
854[[http://srfi.schemers.org/srfi-2/srfi-2.html|SRFI-2]].
855
856==== letrec*
857
858<macro>(letrec* ((VARIABLE EXPRESSION) ...) BODY ...)</macro>
859
860Implements R6RS/R7RS {{letrec*}}. {{letrec*}} is similar to {{letrec}}
861but binds the variables sequentially and is to {{letrec}} what
862{{let*}} is to {{let}}.
863
864This special form is compatible with the definition from the R7RS
865{{(scheme base)}} library.
866
867==== rec
868
869<macro>(rec NAME EXPRESSION)</macro><br>
870<macro>(rec (NAME VARIABLE ...) BODY ...)</macro>
871
872Allows simple definition of recursive definitions. {{(rec NAME EXPRESSION)}} is
873equivalent to {{(letrec ((NAME EXPRESSION)) NAME)}} and {{(rec (NAME VARIABLE ...) BODY ...)}}
874is the same as {{(letrec ((NAME (lambda (VARIABLE ...) BODY ...))) NAME)}}.
875
876==== cut
877
878<macro>(cut SLOT ...)</macro><br>
879<macro>(cute SLOT ...)</macro>
880
881[[http://srfi.schemers.org/srfi-26/srfi-26.html|Syntactic sugar for specializing parameters]].
882
883==== define-values
884
885<macro>(define-values (NAME ...) VALUEEXP)</macro>
886<macro>(define-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>
887<macro>(define-values NAME VALUEEXP)</macro>
888
889Defines several variables at once, with the result values of expression
890{{VALUEEXP}}, similar to {{set!-values}}.
891
892This special form is compatible with the definition from the R7RS
893{{(scheme base)}} library.
894
895==== fluid-let
896
897<macro>(fluid-let ((VAR1 X1) ...) BODY ...)</macro>
898
899Binds the variables {{VAR1 ...}} dynamically to the values {{X1 ...}}
900during execution of {{BODY ...}}.  This implements
901[[http://srfi.schemers.org/srfi-15/srfi-15.html|SRFI-15]].
902
903==== let-values
904
905<macro>(let-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
906
907Binds multiple variables to the result values of {{VALUEEXP ...}}.
908All variables are bound simultaneously.  Like {{define-values}}, the
909{{(NAME ...)}} expression can be any basic lambda list (dotted tail
910notation is supported).
911
912This special form implements
913[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]], and it is
914also compatible with the definition from the R7RS {{(scheme base)}}
915library.
916
917
918==== let*-values
919
920<macro>(let*-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
921
922Binds multiple variables to the result values of {{VALUEEXP ...}}.
923The variables are bound sequentially.  Like {{let-values}}, the
924{{(NAME ...)}} expression can be any basic lambda list (dotted tail
925notation is supported).
926
927This is also part of
928[[http://srfi.schemers.org/srfi-11/srfi-11.html|SRFI-11]] and is also
929compatible with the definition from the R7RS {{(scheme base)}}
930library.
931
932<enscript highlight=scheme>
933(let*-values (((a b) (values 2 3))
934              ((p) (+ a b)) )
935  p)                               ==> 5
936</enscript>
937
938==== letrec-values
939
940<macro>(letrec-values (((NAME ...) VALUEEXP) ...) BODY ...)</macro>
941
942Binds the result values of {{VALUEEXP ...}} to multiple variables at
943once.  All variables are mutually recursive.  Like {{let-values}}, the
944{{(NAME ...)}} expression can be any basic lambda list (dotted tail
945notation is supported).
946
947<enscript highlight=scheme>
948(letrec-values (((odd even)
949                   (values
950                     (lambda (n) (if (zero? n) #f (even (sub1 n))))
951                     (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )
952  (odd 17) )                           ==> #t
953</enscript>
954
955
956==== receive
957
958<macro>(receive (NAME ...) VALUEEXP BODY ...)</macro><br>
959<macro>(receive (NAME1 ... NAMEn . NAMEn+1) VALUEEXP BODY ...)</macro><br>
960<macro>(receive NAME VALUEEXP BODY ...)</macro><br>
961<macro>(receive VALUEEXP)</macro>
962
963[[http://srfi.schemers.org/srfi-8/srfi-8.html|SRFI-8]].
964Syntactic sugar for {{call-with-values}}. Binds variables
965to the result values of {{VALUEEXP}} and evaluates {{BODY ...}},
966similar {{define-values}} but lexically scoped.
967
968{{(receive VALUEEXP)}} is equivalent to {{(receive _ VALUEEXP _)}}.
969This shortened form is not described by SRFI-8.
970
971==== set!-values
972
973<macro>(set!-values (NAME ...) VALUEEXP)</macro>
974<macro>(set!-values (NAME1 ... NAMEn . NAMEn+1) VALUEEXP)</macro>
975<macro>(set!-values NAME VALUEEXP)</macro>
976
977Assigns the result values of expression {{VALUEEXP}} to multiple
978variables, similar to {{define-values}}.
979
980==== nth-value
981
982<macro>(nth-value N EXP)</macro>
983
984Returns the {{N}}th value (counting from zero) of the values returned
985by expression {{EXP}}.
986
987
988=== Parameters
989
990Parameters are CHICKEN's form of dynamic variables, except that they are
991procedures rather than actual variables.  A parameter is a procedure of
992zero or one arguments. To retrieve the value of a parameter call the
993parameter-procedure with zero arguments. To change the setting of the
994parameter, call the parameter-procedure with the new value as argument:
995
996<enscript highlight=scheme>
997(define foo (make-parameter 123))
998(foo)                             ==> 123
999(foo 99)
1000(foo)                             ==> 99
1001</enscript>
1002
1003Parameters are fully thread-local, each thread of execution
1004owns a local copy of a parameters' value.
1005
1006CHICKEN implements
1007[[http://srfi.schemers.org/srfi-39/srfi-39.html|SRFI-39]], which
1008is also standardized by R7RS.
1009
1010
1011==== parameterize
1012
1013<macro>(parameterize ((PARAMETER1 X1) ...) BODY ...)</macro>
1014
1015Binds the parameters {{PARAMETER1 ...}} dynamically to the values
1016{{X1 ...}} during execution of {{BODY ...}}.  (see also:
1017{{make-parameter}} in [[Parameters]]). Note that {{PARAMETER}} may
1018be any expression that evaluates to a parameter procedure.
1019
1020This special form is compatible with the definition from the R7RS
1021{{(scheme base)}} library.
1022
1023==== make-parameter
1024
1025<procedure>(make-parameter VALUE [GUARD])</procedure>
1026
1027Returns a procedure that accepts zero or one argument. Invoking the
1028procedure with zero arguments returns {{VALUE}}. Invoking the
1029procedure with one argument changes its value to the value of that
1030argument and returns the new value (subsequent invocations with zero
1031parameters return the new value). {{GUARD}} should be a procedure of a
1032single argument. Any new values of the parameter (even the initial
1033value) are passed to this procedure. The guard procedure should check
1034the value and/or convert it to an appropriate form.
1035
1036This special form is compatible with the definition from the R7RS
1037{{(scheme base)}} library.
1038
1039=== Substitution forms and macros
1040
1041==== define-constant
1042
1043<macro>(define-constant NAME CONST)</macro>
1044
1045Defines a variable with a constant value, evaluated at compile-time.
1046Any reference to such a constant should appear textually '''after'''
1047its definition. This construct is equivalent to {{define}} when
1048evaluated or interpreted.  Constant definitions should only appear at
1049toplevel. Note that constants are local to the current compilation
1050unit and are not available outside of the source file in which they
1051are defined. Names of constants still exist in the Scheme namespace
1052and can be lexically shadowed.  If the value is mutable, then the
1053compiler is careful to preserve its identity.  {{CONST}} may be any
1054constant expression, and may also refer to constants defined via
1055{{define-constant}} previously, but it must be possible to
1056evaluate the expression at compile-time.
1057
1058==== define-inline
1059
1060<macro>(define-inline (NAME VAR ...) BODY ...)</macro><br>
1061<macro>(define-inline (NAME VAR ... . VAR) BODY ...)</macro><br>
1062<macro>(define-inline NAME EXP)</macro>
1063
1064Defines an inline procedure. Any occurrence of {{NAME}} will be replaced
1065by {{EXP}} or {{(lambda (VAR ... [. VAR]) BODY ...)}}. This is similar
1066to a macro, but variable names and scope are handled correctly.
1067
1068Inline substitutions take place '''after''' macro-expansion, and any
1069reference to {{NAME}} should appear textually '''after''' its
1070definition. Inline procedures are local to the current compilation unit
1071and are not available outside of the source file in which they are
1072defined. Names of inline procedures still exist in the Scheme namespace
1073and can be lexically shadowed. Inline definitions should only appear at
1074the toplevel.
1075
1076Note that the {{inline-limit}} compiler option does not affect inline
1077procedure expansion, and self-referential inline procedures may cause
1078the compiler to enter an infinite loop.
1079
1080In the third form, {{EXP}} must be a lambda expression.
1081
1082This construct is equivalent to {{define}} when evaluated or
1083interpreted.
1084
1085
1086=== Conditional forms
1087
1088==== select
1089
1090<macro>(select EXP ((KEY ...) EXP1 ...) ... [(else EXPn ...)])</macro>
1091
1092This is similar to {{case}}, but the keys are evaluated.
1093
1094==== unless
1095
1096<macro>(unless TEST EXP1 EXP2 ...)</macro>
1097
1098Equivalent to:
1099
1100<enscript highlight=scheme>
1101(if (not TEST) (begin EXP1 EXP2 ...))
1102</enscript>
1103
1104==== when
1105
1106<macro>(when TEST EXP1 EXP2 ...)</macro>
1107
1108Equivalent to:
1109
1110<enscript highlight=scheme>
1111(if TEST (begin EXP1 EXP2 ...))
1112</enscript>
1113
1114
1115=== Record structures
1116
1117==== define-record
1118
1119<macro>(define-record NAME SLOTNAME ...)</macro>
1120
1121Defines a record type. This defines a number of procedures for
1122creating, accessing, and modifying record members.
1123
1124Call {{make-NAME}} to create an instance
1125of the structure (with one initialization-argument for each slot, in
1126the listed order).
1127
1128{{(NAME? STRUCT)}} tests any object for being an instance of this
1129structure.
1130
1131Slots are accessed via {{(NAME-SLOTNAME STRUCT)}}
1132and updated using {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
1133
1134<enscript highlight=scheme>
1135(define-record point x y)
1136(define p1 (make-point 123 456))
1137(point? p1)                      ==> #t
1138(point-x p1)                     ==> 123
1139(point-y-set! p1 99)
1140(point-y p1)                     ==> 99
1141</enscript>
1142
1143===== SRFI-17 setters
1144
1145{{SLOTNAME}} may alternatively also be of the form
1146
1147  (setter SLOTNAME)
1148
1149In this case the slot can be read with {{(NAME-SLOTNAME STRUCT)}} as usual,
1150and modified with {{(set! (NAME-SLOTNAME STRUCT) VALUE)}} (the slot-accessor
1151has an associated SRFI-17 "setter" procedure) instead of
1152the usual {{(NAME-SLOTNAME-set!}} {{STRUCT}} {{VALUE)}}.
1153
1154
1155<enscript highlight=scheme>
1156(define-record point (setter x) (setter y))
1157(define p1 (make-point 123 456))
1158(point? p1)                      ==> #t
1159(point-x p1)                     ==> 123
1160(set! (point-y p1) 99)
1161(point-y p1)                     ==> 99
1162</enscript>
1163
1164==== define-record-type
1165
1166<macro>(define-record-type NAME (CONSTRUCTOR TAG ...) PREDICATE (FIELD ACCESSOR [MODIFIER]) ...)</macro>
1167
1168SRFI-9 record types. For more information see the documentation for
1169[[http://srfi.schemers.org/srfi-9/srfi-9.html|SRFI-9]].
1170
1171As an extension the {{MODIFIER}} may have the form
1172{{(setter PROCEDURE)}}, which will define a SRFI-17 setter-procedure
1173for the given {{PROCEDURE}} that sets the field value.
1174Usually {{PROCEDURE}} has the same name is {{ACCESSOR}} (but it
1175doesn't have to).
1176
1177This special form is also compatible with the definition from the R7RS
1178{{(scheme base)}} library.
1179
1180
1181==== define-record-printer
1182
1183<macro>(define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)</macro><br>
1184<macro>(define-record-printer NAME PROCEDURE)</macro>
1185
1186Defines a printing method for record of the type {{NAME}} by
1187associating a procedure with the record type. When a record of this
1188type is written using {{display, write}} or {{print}}, then
1189the procedure is called with two arguments: the record to be printed
1190and an output-port.
1191
1192<enscript highlight=scheme>
1193(define-record-type foo (make-foo x y z) foo?
1194  (x foo-x)
1195  (y foo-y)
1196  (z foo-z))
1197(define f (make-foo 1 2 3))
1198(define-record-printer (foo x out)
1199  (fprintf out "#,(foo ~S ~S ~S)"
1200           (foo-x x) (foo-y x) (foo-z x)) )
1201(define-reader-ctor 'foo make-foo)
1202(define s (with-output-to-string
1203              (lambda () (write f))))
1204s                                   ==> "#,(foo 1 2 3)"
1205(equal? f (with-input-from-string
1206              s read)))             ==> #t
1207</enscript>
1208
1209=== Other forms
1210
1211==== include
1212
1213<macro>(include STRING)</macro>
1214
1215Include toplevel-expressions from the given source file in the currently
1216compiled/interpreted program.  If the included file has the extension
1217{{.scm}}, then it may be omitted. The file is searched for in the
1218current directory and all directories specified by the {{-include-path}}
1219option.
1220
1221==== include-relative
1222
1223<macro>(include-relative STRING)</macro>
1224
1225Works like {{include}}, but the filename is searched for relative to the
1226including file rather than the current directory.
1227
1228
1229=== Making extra libraries and extensions available
1230
1231==== require-extension
1232
1233<macro>(require-extension ID ...)</macro>
1234
1235This is equivalent to {{(require-library ID ...)}} but performs an implicit
1236{{import}}, if necessary. Since version 4.4.0, {{ID}} may also be an import specification
1237(using {{rename}}, {{only}}, {{except}} or {{prefix}}).
1238
1239To make long matters short - just use {{require-extension}} and it will normally figure everything out for dynamically
1240loadable extensions and core library units.
1241
1242This implementation of {{require-extension}} is compliant with [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]]
1243(see the [[http://srfi.schemers.org/srfi-55/srfi-55.html|SRFI-55]] document for more information).
1244
1245==== require-library
1246
1247<macro>(require-library ID ...)</macro>
1248
1249This form does all the necessary steps to make the libraries or extensions given
1250in {{ID ...}} available. It loads syntactic extensions, if needed and generates
1251code for loading/linking with core library modules or separately installed
1252extensions.
1253
1254During interpretation/evaluation {{require-library}} performs one of the
1255following:
1256
1257* 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.
1258* If {{ID}} names one of the syntactic extensions {{chicken-syntax chicken-ffi-syntax}}, then this extension will be loaded.
1259* If {{ID}} names one of the core library units shipped with CHICKEN, then a {{(load-library 'ID)}} will be performed.
1260* 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.
1261* Otherwise, {{(require-library ID)}} is equivalent to {{(require 'ID)}}.
1262
1263During compilation, one of the following happens instead:
1264
1265* 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.
1266* 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.
1267* 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.
1268* 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.
1269* Otherwise {{(require-library ID)}} is equivalent to {{(require 'ID)}}.
1270
1271{{ID}} should be a pure extension name and should not contain any path prefixes (for example {{dir/lib...}} is illegal).
1272
1273{{ID}} may also be a list that designates an extension-specifier. Currently the following extension specifiers are
1274defined:
1275
1276* {{(srfi NUMBER ...)}} is required for SRFI-55 compatibility and is fully implemented
1277* {{(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>=?}}).
1278
1279TODO: Document declare (keep the "declarations" section?)
1280
1281=== Process shutdown
1282
1283==== emergency-exit
1284
1285<procedure>(emergency-exit [CODE])</procedure>
1286
1287Exits the current process without flushing any buffered output (using
1288the C function {{_exit}}).  Note that the {{exit-handler}} is not called
1289when this procedure is invoked. The optional exit status code {{CODE}}
1290defaults to {{0}}.
1291
1292
1293==== exit
1294
1295<procedure>(exit [CODE])</procedure>
1296
1297Exit the running process and return exit-code, which defaults to 0
1298(Invokes {{exit-handler}}).
1299
1300Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
1301
1302
1303=== exit-handler
1304
1305<parameter>(exit-handler)</parameter>
1306
1307A procedure of a single optional argument. When {{exit}} is called,
1308then this procedure will be invoked with the exit-code as argument. The
1309default behavior is to terminate the program.
1310
1311Note that this handler is ''not'' invoked when {{emergency-exit}} is
1312used.
1313
1314
1315=== implicit-exit-handler
1316
1317<parameter>(implicit-exit-handler)</parameter>
1318
1319A procedure of no arguments. When the last toplevel expression of the
1320program has executed, then the value of this parameter is called. The
1321default behaviour is to invoke all pending finalizers.
1322
1323
1324==== on-exit
1325
1326<procedure>(on-exit THUNK)</procedure>
1327
1328Schedules the zero-argument procedures {{THUNK}} to be executed before
1329the process exits, either explicitly via {{exit}} or implicitly after
1330execution of the last top-level form. Note that finalizers for
1331unreferenced finalized data are run before exit procedures.
1332
1333
1334=== System interface
1335
1336
1337==== sleep
1338
1339<procedure>(sleep SECONDS)</procedure>
1340
1341Puts the program to sleep for {{SECONDS}}. If the scheduler is loaded
1342(for example when srfi-18 is in use) then only the calling thread is put
1343to sleep and other threads may continue executing. Otherwise, the whole
1344process is put to sleep.
1345
1346
1347=== Ports
1348
1349==== String ports
1350
1351===== get-output-string
1352
1353<procedure>(get-output-string PORT)</procedure>
1354
1355Returns accumulated output of a port created with
1356{{(open-output-string)}}.
1357
1358
1359===== open-input-string
1360
1361<procedure>(open-input-string STRING)</procedure>
1362
1363Returns a port for reading from {{STRING}}.
1364
1365
1366===== open-output-string
1367
1368<procedure>(open-output-string)</procedure>
1369
1370Returns a port for accumulating output in a string.
1371
1372
1373=== File Input/Output
1374
1375==== flush-output
1376
1377<procedure>(flush-output [PORT])</procedure>
1378
1379Write buffered output to the given output-port. {{PORT}} defaults
1380to the value of {{(current-output-port)}}.
1381
1382=== Port predicates
1383
1384==== input-port-open?
1385
1386<procedure>(input-port-open? PORT)</procedure>
1387
1388Is the given {{PORT}} open for input?
1389
1390<procedure>(output-port-open? PORT)</procedure>
1391
1392Is the given {{PORT}} open for output?
1393
1394==== port-closed?
1395
1396<procedure>(port-closed? PORT)</procedure>
1397
1398Is the given {{PORT}} closed (in all directions)?
1399
1400==== port?
1401
1402<procedure>(port? X)</procedure>
1403
1404Returns {{#t}} if {{X}} is a port object or {{#f}}
1405otherwise.
1406
1407---
1408Previous: [[Module srfi-4]]
1409
1410Next: [[Module (chicken bitwise)]]
Note: See TracBrowser for help on using the repository browser.