source: project/chicken/trunk/manual/Unit library @ 15896

Last change on this file since 15896 was 15896, checked in by Ivan Raikov, 10 years ago

merged manual from wiki

File size: 32.0 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit library
5
6This unit contains basic Scheme definitions. This unit is used by default,
7unless the program is compiled with the {{-explicit-use}} option.
8
9=== Arithmetic
10
11
12==== add1/sub1
13
14<procedure>(add1 N)</procedure>
15<procedure>(sub1 N)</procedure>
16
17Adds/subtracts 1 from {{N}}.
18
19
20==== Binary integer operations
21
22Binary integer operations. {{arithmetic-shift}} shifts the argument {{N1}} by
23{{N2}} bits to the left. If {{N2}} is negative, than {{N1}} is shifted to the
24right. These operations only accept exact integers or inexact integers in word
25range (32 bit signed on 32-bit platforms, or 64 bit signed on 64-bit
26platforms).
27
28<procedure>(bitwise-and N1 ...)</procedure>
29<procedure>(bitwise-ior N1 ...)</procedure>
30<procedure>(bitwise-xor N1 ...)</procedure>
31<procedure>(bitwise-not N)</procedure>
32<procedure>(arithmetic-shift N1 N2)</procedure>
33
34==== bit-set?
35
36<procedure>(bit-set? N INDEX)</procedure>
37
38Returns {{#t}} if the bit at the position {{INDEX}} in the integer {{N}} is
39set, or {{#f}} otherwise. The rightmost/least-significant bit is bit 0.
40
41
42==== Arithmetic fixnum operations
43
44These procedures do not check their arguments, so non-fixnum parameters will
45result in incorrect results. {{fxneg}} negates its argument.
46
47On division by zero, {{fx/}} and {{fxmod}} signal a condition of kind
48{{(exn arithmetic)}}.
49
50{{fxshl}} and {{fxshr}} perform arithmetic shift left and right,
51respectively.
52
53<procedure>(fx+ N1 N2)</procedure>
54<procedure>(fx- N1 N2)</procedure>
55<procedure>(fx* N1 N2)</procedure>
56<procedure>(fx/ N1 N2)</procedure>
57<procedure>(fxmod N1 N2)</procedure>
58<procedure>(fxneg N)</procedure>
59<procedure>(fxmin N1 N2)</procedure>
60<procedure>(fxmax N1 N2)</procedure>
61<procedure>(fx= N1 N2)</procedure>
62<procedure>(fx> N1 N2)</procedure>
63<procedure>(fx< N1 N2)</procedure>
64<procedure>(fx>= N1 N2)</procedure>
65<procedure>(fx<= N1 N2)</procedure>
66<procedure>(fxand N1 N2)</procedure>
67<procedure>(fxior N1 N2)</procedure>
68<procedure>(fxxor N1 N2)</procedure>
69<procedure>(fxnot N)</procedure>
70<procedure>(fxshl N1 N2)</procedure>
71<procedure>(fxshr N1 N2)</procedure>
72
73==== fixnum?
74
75 [procedure] (fixnum? X)
76
77Returns {{#t}} if {{X}} is a fixnum, or {{#f}} otherwise.
78
79==== Fixnum limits
80
81{{most-positive-fixnum}}
82
83{{most-negative-fixnum}}
84
85{{fixnum-bits}}
86
87{{fixnum-precision}}
88
89
90==== Arithmetic floating-point operations
91
92arguments (except {{flonum?}}, which returns {{#f}}). In unsafe mode,
93these procedures do not check their arguments. A non-flonum argument
94in unsafe mode can crash the system.
95
96<procedure>(flonum? X)</procedure>
97<procedure>(fp+ X Y)</procedure>
98<procedure>(fp- X Y)</procedure>
99<procedure>(fp* X Y)</procedure>
100<procedure>(fp/ X Y)</procedure>
101<procedure>(fpneg X)</procedure>
102<procedure>(fpmin X Y)</procedure>
103<procedure>(fpmax X Y)</procedure>
104<procedure>(fp= X Y)</procedure>
105<procedure>(fp> X Y)</procedure>
106<procedure>(fp< X Y)</procedure>
107<procedure>(fp>= X Y)</procedure>
108<procedure>(fp<= X Y)</procedure>
109
110==== flonum?
111
112 [procedure] (flonum? X)
113
114Returns {{#t}} if {{X}} is a flonum, or {{#f}} otherwise.
115
116==== Flonum limits
117
118{{maximum-flonum}}
119
120{{minimum-flonum}}
121
122{{flonum-radix}}
123
124{{flonum-epsilon}}
125
126{{flonum-precision}}
127
128{{flonum-decimal-precision}}
129
130{{flonum-maximum-exponent}}
131
132{{flonum-minimum-exponent}}
133
134{{flonum-maximum-decimal-exponent}}
135
136{{flonum-minimum-decimal-exponent}}
137
138==== finite?
139
140<procedure>(finite? N)</procedure>
141
142Returns {{#f}} if {{N}} is negative or positive infinity, and {{#t}} otherwise.
143
144==== signum
145
146 [procedure] (signum N)
147
148Returns {{1}} if {{N}} is positive, {{-1}} if {{N}}
149is negative or {{0}} if {{N}} is zero. {{signum}} is exactness preserving.
150
151
152
153=== File Input/Output
154
155==== current-output-port
156
157<procedure>(current-output-port [PORT])</procedure>
158
159Returns default output port. If {{PORT}} is given, then that port is selected
160as the new current output port.
161
162Note that the default output port is not buffered. Use [[Unit posix#Setting the
163file buffering mode|{{set-buffering-mode!}}]] if you need a different behavior.
164
165==== current-error-port
166
167<procedure>(current-error-port [PORT])</procedure>
168
169Returns default error output port. If {{PORT}} is given, then that port is
170selected as the new current error output port.
171
172Note that the default error output port is not buffered. Use [[Unit
173posix#Setting the file buffering mode|{{set-buffering-mode!}}]] if you need a
174different behavior.
175
176==== flush-output
177
178<procedure>(flush-output [PORT])</procedure>
179
180Write buffered output to the given output-port. {{PORT}} defaults
181to the value of {{(current-output-port)}}.
182
183
184==== port-name
185
186<procedure>(port-name [PORT])</procedure>
187
188Fetch filename from {{PORT}}. This returns the filename that was used to open
189this file. Returns a special tag string, enclosed into parentheses for
190non-file ports. {{PORT}} defaults to the value of {{(current-input-port)}}.
191
192
193==== port-position
194
195<procedure>(port-position [PORT])</procedure>
196
197Returns the current position of {{PORT}} as two values: row and column number.
198If the port does not support such an operation an error is signaled. This
199procedure is currently only available for input ports. {{PORT}} defaults to the
200value of {{(current-input-port)}}.
201
202
203==== set-port-name!
204
205<procedure>(set-port-name! PORT STRING)</procedure>
206
207Sets the name of {{PORT}} to {{STRING}}.
208
209
210
211=== Files
212
213==== delete-file
214
215<procedure>(delete-file STRING)</procedure>
216
217Deletes the file with the pathname {{STRING}}. If the file does
218not exist, an error is signaled.
219
220
221==== directory-exists?
222
223<procedure>(directory-exists? STRING)</procedure>
224
225Returns {{STRING}} if a directory with the given pathname exists, or
226{{#f}} otherwise.
227
228
229==== file-exists?
230
231<procedure>(file-exists? STRING)</procedure>
232
233Returns {{STRING}} if a file or directory with the given pathname exists, or
234{{#f}} otherwise.
235
236
237==== rename-file
238
239<procedure>(rename-file OLD NEW)</procedure>
240
241Renames the file or directory with the pathname {{OLD}} to
242{{NEW}}. If the operation does not succeed, an error is signaled.
243
244
245=== String ports
246
247==== get-output-string
248
249<procedure>(get-output-string PORT)</procedure>
250
251Returns accumulated output of a port created with
252{{(open-output-string)}}.
253
254
255==== open-input-string
256
257<procedure>(open-input-string STRING)</procedure>
258
259Returns a port for reading from {{STRING}}.
260
261
262==== open-output-string
263
264<procedure>(open-output-string)</procedure>
265
266Returns a port for accumulating output in a string.
267
268
269
270
271
272=== Feature identifiers
273
274
275CHICKEN maintains a global list of ''features'' naming functionality available
276in the current system. Additionally the {{cond-expand}} form accesses this
277feature list to infer what features are provided. Predefined features are
278{{chicken}}, and the SRFIs (Scheme Request For Implementation) provided by the
279base system: {{srfi-23, srfi-30, srfi-39}}. If the {{eval}} unit
280is used (the default), the features {{srfi-0, srfi-2, srfi-6, srfi-8, srfi-9}}
281and {{srfi-10}} are defined. When compiling code (during compile-time) the
282feature {{compiling}} is registered. When evaluating code in the interpreter
283(csi), the feature {{csi}} is registered.
284
285
286==== features
287
288<procedure>(features)</procedure>
289
290Returns a list of all registered features that will be accepted as valid
291feature-identifiers by {{cond-expand}}.
292
293
294==== feature?
295
296<procedure>(feature? ID ...)</procedure>
297
298Returns {{#t}} if all features with the given feature-identifiers {{ID ...}}
299are registered.
300
301
302==== register-feature!
303
304<procedure>(register-feature! FEATURE ...)</procedure>
305
306Register one or more features that will be accepted as valid
307feature-identifiers by {{cond-expand}}. {{FEATURE ...}} may
308be a keyword, string or symbol.
309
310
311==== unregister-feature!
312
313<procedure>(unregister-feature! FEATURE ...)</procedure>
314
315Unregisters the specified feature-identifiers. {{FEATURE ...}}
316may be a keyword, string or symbol.
317
318
319
320
321
322=== Keywords
323
324Keywords are special symbols prefixed with {{#:}} that evaluate
325to themselves. Procedures can use keywords to accept optional named
326parameters in addition to normal required parameters. Assignment to
327and bindings of keyword symbols is not allowed.
328The parameter {{keyword-style}} and the compiler/interpreter option
329{{-keyword-style}} can be used to allow an additional keyword
330syntax, either compatible to Common LISP, or to DSSSL.  As long as this
331parameter is set to {{#:suffix}}, Chicken conforms to
332[[http://srfi.schemers.org/srfi-88/srfi-88.html|SRFI-88]].
333
334
335==== get-keyword
336
337<procedure>(get-keyword KEYWORD ARGLIST [THUNK])</procedure>
338
339Returns the argument from {{ARGLIST}} specified under the keyword
340{{KEYWORD}}. If the keyword is not found, then the zero-argument
341procedure {{THUNK}} is invoked and the result value is returned. If
342{{THUNK}} is not given, {{#f}} is returned.
343
344<enscript highlight=scheme>
345(define (increase x . args)
346  (+ x (get-keyword #:amount args (lambda () 1))) )
347(increase 123)                                      ==> 124
348(increase 123 #:amount 10)                          ==> 133
349</enscript>
350
351Note: the {{KEYWORD}} may actually be any kind of object.
352
353
354==== keyword?
355
356<procedure>(keyword? X)</procedure>
357
358Returns {{#t}} if {{X}} is a keyword symbol, or {{#f}}
359otherwise.
360
361
362==== keyword->string
363
364<procedure>(keyword->string KEYWORD)</procedure>
365
366Transforms {{KEYWORD}} into a string.
367
368
369==== string->keyword
370
371<procedure>(string->keyword STRING)</procedure>
372
373Returns a keyword with the name {{STRING}}.
374
375
376
377
378
379=== Exceptions
380
381
382CHICKEN implements the (currently withdrawn)
383[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] exception system. For
384more information, see the
385[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] document.
386
387
388
389==== condition-case
390
391 [syntax] (condition-case EXPRESSION CLAUSE ...)
392
393Evaluates {{EXPRESSION}} and handles any exceptions that are covered by
394{{CLAUSE ...}}, where {{CLAUSE}} should be of the following form:
395
396<enscript highlight=scheme>
397CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
398</enscript>
399
400If provided, {{VARIABLE}} will be bound to the signaled exception
401object. {{BODY ...}} is executed when the exception is a property-
402or composite condition with the kinds given {{KIND ...}} (unevaluated).
403If no clause applies, the exception is re-signaled in the same dynamic
404context as the {{condition-case}} form.
405
406<enscript highlight=scheme>
407(define (check thunk)
408  (condition-case (thunk)
409    [(exn file) (print "file error")]
410    [(exn) (print "other error")]
411    [var () (print "something else")] ) )
412
413(check (lambda () (open-input-file "")))   ; -> "file error"
414(check (lambda () some-unbound-variable))  ; -> "othererror"
415(check (lambda () (signal 99)))            ; -> "something else"
416
417(condition-case some-unbound-variable
418  [(exn file) (print "ignored")] )      ; -> signals error
419
420</enscript>
421
422
423==== breakpoint
424
425<procedure>(breakpoint [NAME])</procedure>
426
427Programmatically triggers a breakpoint (similar to the {{,br}} top-level csi
428command).
429
430
431==== get-condition-property
432
433<procedure>(get-condition-property CONDITION KIND PROPERTY [DEFAULT])</procedure>
434
435A slightly more convenient condition property accessor, equivalent to
436
437  ((condition-property-accessor KIND PROPERTY [DEFAULT]) CONDITION)
438
439
440==== System conditions
441
442All error-conditions signaled by the system are of kind {{exn}}.
443The following composite conditions are additionally defined:
444
445<table>
446
447<tr><td> (exn arity)
448
449Signaled when a procedure is called with the wrong number of arguments.
450
451</td></tr><tr><td> (exn type)
452
453Signaled on type-mismatch errors, for example when an argument of the wrong
454type is passed to a built-in procedure.
455
456</td></tr><tr><td> (exn arithmetic)
457
458Signaled on arithmetic errors, like division by zero.
459
460</td></tr><tr><td> (exn i/o)
461
462Signaled on input/output errors.
463
464</td></tr><tr><td> (exn i/o file)
465
466Signaled on file-related errors.
467
468</td></tr><tr><td> (exn i/o net)
469
470Signaled on network errors.
471
472</td></tr><tr><td> (exn bounds)
473
474Signaled on errors caused by accessing non-existent elements of a collection.
475
476</td></tr><tr><td> (exn runtime)
477
478Signaled on low-level runtime-system error-situations.
479
480</td></tr><tr><td> (exn runtime limit)
481
482Signaled when an internal limit is exceeded (like running out of memory).
483
484</td></tr><tr><td> (exn match)
485
486Signaled on errors raised by failed matches (see the section on {{match}}).
487
488</td></tr><tr><td> (exn syntax)
489
490Signaled on syntax errors.
491
492</td></tr><tr><td> (exn breakpoint)
493
494Signaled when a breakpoint is reached.
495
496</td></tr>
497
498</table>
499
500Notes:
501
502* All error-exceptions (of the kind {{exn}}) are non-continuable.
503
504* Error-exceptions of the {{exn}} kind have additional {{arguments}} and
505{{location}} properties that contain the arguments passed to the
506exception-handler and the name of the procedure where the error occurred (if
507available).
508
509* When the {{posix}} unit is available and used, then a user-interrupt
510({{signal/int}}) signals an exception of the kind {{user-interrupt}}.
511
512* the procedure {{condition-property-accessor}} accepts an optional third
513argument. If the condition does not have a value for the desired property and
514if the optional argument is given, no error is signaled and the accessor
515returns the third argument.
516
517* In composite conditions all properties are currently collected in a single
518property-list, so in the case that to conditions have the same named property,
519only one will be visible.
520
521
522
523=== Environment information and system interface
524
525
526
527==== argv
528
529<procedure>(argv)</procedure>
530
531Return a list of all supplied command-line arguments. The first item in
532the list is a string containing the name of the executing program. The
533other items are the arguments passed to the application. This list is
534freshly created on every invocation of {{(argv)}}. It depends on
535the host-shell whether arguments are expanded ('globbed') or not.
536
537
538==== exit
539
540<procedure>(exit [CODE])</procedure>
541
542Exit the running process and return exit-code, which defaults to 0
543(Invokes {{exit-handler}}).
544
545Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
546
547==== build-platform
548
549<procedure>(build-platform)</procedure>
550
551Returns a symbol specifying the toolset which has been used for
552building the executing system, which is one of the following:
553
554 cygwin
555 mingw32
556 gnu
557 intel
558 unknown
559
560
561==== chicken-version
562
563<procedure>(chicken-version [FULL])</procedure>
564
565Returns a string containing the version number of the CHICKEN runtime
566system. If the optional argument {{FULL}} is given and true, then
567a full version string is returned.
568
569
570==== errno
571
572<procedure>(errno)</procedure>
573
574Returns the error code of the last system call.
575
576
577==== get-environment-variable
578
579 [procedure] (get-environment-variable STRING)
580 [procedure] (getenv STRING)
581
582Returns the value of the environment variable {{STRING}} or
583{{#f}} if that variable is not defined. See also [[http://srfi.schemers.org/srfi-98/|SRFI-98]].
584{{getenv}} is an alias for {{get-environment-variable}}.
585
586
587==== machine-byte-order
588
589<procedure>(machine-byte-order)</procedure>
590
591Returns the symbol {{little-endian}} or {{big-endian}}, depending on the
592machine's byte-order.
593
594
595==== machine-type
596
597<procedure>(machine-type)</procedure>
598
599Returns a symbol specifying the processor on which this process is
600currently running, which is one of the following:
601
602 alpha
603 mips
604 hppa
605 ultrasparc
606 sparc
607 ppc
608 ppc64
609 ia64
610 x86
611 x86-64
612 unknown
613
614
615==== on-exit
616
617<procedure>(on-exit THUNK)</procedure>
618
619Schedules the zero-argument procedures {{THUNK}} to be executed before
620the process exits, either explicitly via {{exit}} or implicitly after execution
621of the last top-level form. Note that finalizers for unreferenced finalized
622data are run before exit procedures.
623
624
625==== software-type
626
627<procedure>(software-type)</procedure>
628
629Returns a symbol specifying the operating system on which this process
630is currently running, which is one of the following:
631
632 windows
633 unix
634 macos
635 ecos
636 unknown
637
638
639==== software-version
640
641<procedure>(software-version)</procedure>
642
643Returns a symbol specifying the operating system version on which this
644process is currently running, which is one of the following:
645
646 linux
647 freebsd
648 netbsd
649 openbsd
650 macosx
651 hpux
652 solaris
653 sunos
654 unknown
655
656
657
658==== c-runtime
659
660<procedure>(c-runtime)</procedure>
661
662Returns a symbol that designates what kind of C runtime library has been linked
663with this version of the Chicken libraries. Possible return values are
664{{static}}, {{dynamic}} or {{unknown}}. On systems not compiled with the
665Microsoft C compiler, {{c-runtime}} always returns {{unknown}}.
666
667
668==== system
669
670<procedure>(system STRING)</procedure>
671
672Execute shell command. The functionality offered by this procedure
673depends on the capabilities of the host shell. If the forking of a subprocess
674failed, an exception is raised. Otherwise the return status of the
675subprocess is returned unaltered.
676
677
678On a UNIX system, that value is the raw return value of waitpid(2), which contains signal, core dump and exit status.    It is 0 on success.  To pull out the signal number or exit status portably requires POSIX calls, but in a pinch you can use something like this:
679
680 ;; Returns two values: #t if the process exited normally or #f otherwise;
681 ;; and either the exit status, or the signal number if terminated via signal.
682 (define (process-status rc)
683   (define (wait-signaled? x) (not (= 0 (bitwise-and x 127))))
684   (define (wait-signal x) (bitwise-and x 127))
685   (define (wait-exit-status x) (arithmetic-shift x -8))
686   (if (wait-signaled? rc)
687       (values #f (wait-signal rc))
688       (values #t (wait-exit-status rc))))
689
690 #;> (process-status (system "exit 42"))
691 #t
692 42
693
694=== Execution time
695
696
697
698==== cpu-time
699
700<procedure>(cpu-time)</procedure>
701
702Returns the used CPU time of the current process in milliseconds as
703two values: the time spent in user code, and the time spent in system
704code. On platforms where user and system time can not be differentiated,
705system time will be always be 0.
706
707
708==== current-milliseconds
709
710<procedure>(current-milliseconds)</procedure>
711
712Returns the number of milliseconds since process- or machine startup.
713
714
715==== current-seconds
716
717<procedure>(current-seconds)</procedure>
718
719Returns the number of seconds since midnight, Jan. 1, 1970.
720
721
722==== current-gc-milliseconds
723
724<procedure>(current-gc-milliseconds)</procedure>
725
726Returns the number of milliseconds spent in major garbage collections since
727the last call of {{current-gc-milliseconds}} and returns an exact
728integer.
729
730
731
732=== Interrupts and error-handling
733
734
735
736==== enable-warnings
737
738<procedure>(enable-warnings [BOOL])</procedure>
739
740Enables or disables warnings, depending on wether {{BOOL}} is true or false.
741If called with no arguments, this procedure returns {{#t}} if warnings are
742currently enabled, or {{#f}} otherwise. Note that this is not a parameter.
743The current state (whether warnings are enabled or disabled) is global and not
744thread-local.
745
746
747==== error
748
749<procedure>(error [LOCATION] [STRING] EXP ...)</procedure>
750
751Prints error message, writes all extra arguments to the
752value of {{(current-error-port)}} and invokes the
753current exception-handler. This conforms to
754[[http://srfi.schemers.org/srfi-23/srfi-23.html|SRFI-23]].
755If {{LOCATION}} is given and a symbol, it specifies the ''location'' (the name
756of the procedure) where the error occurred.
757
758
759
760==== get-call-chain
761
762<procedure>(get-call-chain [START [THREAD]])</procedure>
763
764Returns a list with the call history. Backtrace information
765is only generated in code compiled without {{-no-trace}} and evaluated code.
766If the optional argument {{START}} is given, the backtrace starts
767at this offset, i.e. when {{START}} is 1, the next to last trace-entry
768is printed, and so on. If the optional argument {{THREAD}} is given, then
769the call-chain will only be constructed for calls performed by this thread.
770
771
772
773==== print-call-chain
774
775<procedure>(print-call-chain [PORT [START [THREAD]]])</procedure>
776
777Prints a backtrace of the procedure call history to {{PORT}},
778which defaults to {{(current-output-port)}}.
779
780
781==== print-error-message
782
783<procedure>(print-error-message EXN [PORT [STRING]])</procedure>
784
785Prints an appropriate error message to {{PORT}} (which defaults to the
786value of {{(current-output-port)}} for the object {{EXN}}.
787{{EXN}} may be a condition, a string or any other object.
788If the optional argument {{STRING}} is given, it is printed before the
789error-message. {{STRING}} defaults to {{"Error:"}}.
790
791
792
793==== procedure-information
794
795<procedure>(procedure-information PROC)</procedure>
796
797Returns an s-expression with debug information for the procedure {{PROC}}, or
798{{#f}}, if {{PROC}} has no associated debug information.
799
800
801==== reset
802
803<procedure>(reset)</procedure>
804
805Reset program (Invokes {{reset-handler}}).
806
807
808==== warning
809
810<procedure>(warning STRING EXP ...)</procedure>
811
812Displays a warning message (if warnings are enabled with {{enable-warnings}}) and
813continues execution.
814
815
816==== singlestep
817
818<procedure>(singlestep THUNK)</procedure>
819
820Executes the code in the zero-procedure {{THUNK}} in single-stepping mode.
821
822
823
824=== Garbage collection
825
826
827
828==== gc
829
830<procedure>(gc [FLAG])</procedure>
831
832Invokes a garbage-collection and returns the number of free bytes in the heap.
833The flag specifies whether a minor ({{#f}}) or major ({{#t}}) GC is to be
834triggered. If no argument is given, {{#t}} is assumed. An explicit {{#t}}
835argument will cause all pending finalizers to be executed.
836
837==== memory-statistics
838
839<procedure>(memory-statistics)</procedure>
840
841Performs a major garbage collection and returns a three element vector
842containing the total heap size in bytes, the number of bytes currently
843used and the size of the nursery (the first heap generation). Note
844that the actual heap is actually twice the size given in the heap size,
845because CHICKEN uses a copying semi-space collector.
846
847
848==== set-finalizer!
849
850<procedure>(set-finalizer! X PROC)</procedure>
851
852Registers a procedure of one argument {{PROC}}, that will be
853called as soon as the non-immediate data object {{X}} is about to
854be garbage-collected (with that object as its argument). Note that
855the finalizer will '''not''' be called while interrupts are disabled.
856This procedure returns {{X}}.
857
858Finalizers are invoked asynchronously, in the thread that happens
859to be currently running.
860
861
862==== set-gc-report!
863
864<procedure>(set-gc-report! FLAG)</procedure>
865
866Print statistics after every GC, depending on {{FLAG}}. A value of
867{{#t}} shows statistics after every major GC. A true value different
868from {{#t}} shows statistics after every minor GC. {{#f}}
869switches statistics off.
870
871
872
873
874
875=== Other control structures
876
877
878
879==== promise?
880
881<procedure>(promise? X)</procedure>
882
883Returns {{#t}} if {{X}} is a promise returned by {{delay}}, or
884{{#f}} otherwise.
885
886
887
888=== String utilities
889
890
891==== reverse-list->string
892
893<procedure>(reverse-list->string LIST)</procedure>
894
895Returns a string with the characters in {{LIST}} in reverse order. This is
896equivalent to {{(list->string (reverse LIST))}}, but much more efficient.
897
898
899
900=== Generating uninterned symbols
901
902==== gensym
903
904<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
905
906Returns a newly created uninterned symbol. If an argument is provided,
907the new symbol is prefixed with that argument.
908
909
910==== string->uninterned-symbol
911
912<procedure>(string->uninterned-symbol STRING)</procedure>
913
914Returns a newly created, unique symbol with the name {{STRING}}.
915
916
917
918=== Standard Input/Output
919
920==== port?
921
922<procedure>(port? X)</procedure>
923
924Returns {{#t}} if {{X}} is a port object or {{#f}}
925otherwise.
926
927
928==== print
929
930<procedure>(print [EXP1 ...])</procedure>
931
932Outputs the optional arguments {{EXP1 ...}} using {{display}} and
933writes a newline character to the port that is the value of
934{{(current-output-port)}}. Returns {{(void)}}.
935
936
937==== print*
938
939<procedure>(print* [EXP1 ...])</procedure>
940
941Similar to {{print}}, but does not output a terminating newline
942character and performs a {{flush-output}} after writing its arguments.
943
944
945
946
947=== User-defined named characters
948
949==== char-name
950
951<procedure>(char-name SYMBOL-OR-CHAR [CHAR])</procedure>
952
953This procedure can be used to inquire about character names or to
954define new ones. With a single argument the behavior is as follows:
955If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns
956the character with this name, or {{#f}} if no character is defined
957under this name. If {{SYMBOL-OR-CHAR}} is a character, then the
958name of the character is returned as a symbol, or {{#f}} if the
959character has no associated name.
960
961If the optional argument {{CHAR}} is provided, then
962{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of
963the given character. If multiple names designate the same character,
964then the {{write}} will use the character name that was defined last.
965
966<enscript highlight=scheme>
967(char-name 'space)                  ==> #\space
968(char-name #\space)                 ==> space
969(char-name 'bell)                   ==> #f
970(char-name (integer->char 7))       ==> #f
971(char-name 'bell (integer->char 7))
972(char-name 'bell)                   ==> #\bell
973(char->integer (char-name 'bell))   ==> 7
974</enscript>
975
976
977
978=== Blobs
979
980"blobs" are collections of unstructured bytes. You can't do much
981with them, but allow conversion to and from SRFI-4 number vectors.
982
983==== make-blob
984
985<procedure>(make-blob SIZE)</procedure>
986
987Returns a blob object of {{SIZE}} bytes, aligned on an 8-byte boundary,
988uninitialized.
989
990==== blob?
991
992<procedure>(blob? X)</procedure>
993
994Returns {{#t}} if {{X}} is a blob object, or
995{{#f}} otherwise.
996
997==== blob-size
998
999<procedure>(blob-size BLOB)</procedure>
1000
1001Returns the number of bytes in {{BLOB}}.
1002
1003==== blob->string
1004
1005<procedure>(blob->string BLOB)</procedure>
1006
1007Returns a string with the contents of {{BLOB}}.
1008
1009==== string->blob
1010
1011<procedure>(string->blob STRING)</procedure>
1012
1013Returns a blob with the contents of {{STRING}}.
1014
1015==== blob=?
1016
1017<procedure>(blob=? BLOB1 BLOB2)</procedure>
1018
1019Returns {{#t}} if the two argument blobs are of the same
1020size and have the same content.
1021
1022
1023
1024=== Vectors
1025
1026==== vector-copy!
1027
1028<procedure>(vector-copy! VECTOR1 VECTOR2 [COUNT])</procedure>
1029
1030Copies contents of {{VECTOR1}} into {{VECTOR2}}. If the
1031argument {{COUNT}} is given, it specifies the maximal number of
1032elements to be copied. If not given, the minimum of the lengths of the
1033argument vectors is copied.
1034
1035Exceptions: {{(exn bounds)}}
1036
1037
1038==== vector-resize
1039
1040<procedure>(vector-resize VECTOR N [INIT])</procedure>
1041
1042Creates and returns a new vector with the contents of {{VECTOR}} and length
1043{{N}}. If {{N}} is greater than the original length of {{VECTOR}}, then all
1044additional items are initialized to {{INIT}}. If {{INIT}} is not specified, the
1045contents are initialized to some unspecified value.
1046
1047
1048
1049=== The unspecified value
1050
1051==== void
1052
1053<procedure>(void)</procedure>
1054
1055Returns an unspecified value.
1056
1057
1058
1059=== Continuations
1060
1061==== call/cc
1062
1063<procedure>(call/cc PROCEDURE)</procedure>
1064
1065An alias for {{call-with-current-continuation}}.
1066
1067
1068==== continuation-capture
1069
1070<procedure>(continuation-capture PROCEDURE)</procedure>
1071
1072Creates a continuation object representing the current continuation and
1073tail-calls {{PROCEDURE}} with this continuation as the single argument.
1074
1075More information about this continuation API can be found in the paper
1076[[http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf]] ''A Better
1077API for first class Continuations'' by Marc Feeley.
1078
1079
1080==== continuation?
1081
1082<procedure>(continuation? X)</procedure>
1083
1084Returns {{#t}} if {{X}} is a continuation object, or {{#f}} otherwise. Please
1085note that this applies only to continuations created by the Continuation API,
1086but not by call/cc, i.e.: {{(call-with-current-continuation continuation?)}}
1087returns {{#f}}, whereas {{(continuation-capture continuation?)}} returns
1088{{#t}}.
1089
1090
1091==== continuation-graft
1092
1093<procedure>(continuation-graft CONT THUNK)</procedure>
1094
1095Calls the procedure {{THUNK}} with no arguments and the implicit continuation
1096{{CONT}}.
1097
1098
1099==== continuation-return
1100
1101<procedure>(continuation-return CONT VALUE ...)</procedure>
1102
1103Returns the value(s) to the continuation {{CONT}}. {{continuation-return}} could
1104be implemented like this:
1105
1106<enscript highlight=scheme>
1107(define (continuation-return k . vals)
1108  (continuation-graft
1109    k
1110    (lambda () (apply values vals)) ) )
1111</enscript>
1112
1113
1114
1115=== Setters
1116
1117SRFI-17 is fully implemented. For more information see:
1118[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
1119
1120==== setter
1121
1122<procedure>(setter PROCEDURE)</procedure>
1123
1124Returns the setter-procedure of {{PROCEDURE}}, or signals an error if
1125{{PROCEDURE}} has no associated setter-procedure.
1126
1127Note that {{(set! (setter PROC) ...)}} for a procedure that has no associated
1128setter procedure yet is a very slow operation (the old procedure is replaced by
1129a modified copy, which involves a garbage collection).
1130
1131
1132==== getter-with-setter
1133
1134<procedure>(getter-with-setter GETTER SETTER)</procedure>
1135
1136Returns a copy of the procedure {{GETTER}} with the associated setter procedure
1137{{SETTER}}. Contrary to the SRFI specification, the setter of the returned
1138procedure may be changed.
1139
1140
1141
1142=== Reader extensions
1143
1144==== define-reader-ctor
1145
1146<procedure>(define-reader-ctor SYMBOL PROC)</procedure>
1147
1148Define new read-time constructor for {{#,}} read syntax. For further information, see
1149the documentation for [[http://srfi.schemers.org/srfi-10/srfi-10.html|SRFI-10]].
1150
1151
1152==== set-read-syntax!
1153
1154<procedure>(set-read-syntax! CHAR-OR-SYMBOL PROC)</procedure>
1155
1156When the reader encounters the non-whitespace character {{CHAR}} while reading
1157an expression from a given port, then the procedure {{PROC}} will be called with
1158that port as its argument. The procedure should return a value that will be returned
1159to the reader:
1160
1161<enscript highlight=scheme>
1162 ; A simple RGB color syntax:
1163
1164 (set-read-syntax! #\%
1165   (lambda (port)
1166     (apply vector
1167       (map (cut string->number <> 16)
1168            (string-chop (read-string 6 port) 2) ) ) ) )
1169
1170 (with-input-from-string "(1 2 %f0f0f0 3)" read)
1171 ; ==> (1 2 #(240 240 240) 3)
1172</enscript>
1173
1174If {{CHAR-OR-SYMBOL}} is a symbol, then a so-called ''read-mark'' handler is defined.
1175In that case the handler procedure will be called when a character-sequence of the
1176form
1177
1178 #!SYMBOL
1179
1180is encountered.
1181
1182You can undo special handling of read-syntax by passing {{#f}} as the second argument
1183(if the syntax was previously defined via {{set-read-syntax!}}).
1184
1185Note that all of CHICKEN's special non-standard read-syntax is handled directly by the reader.
1186To disable built-in read-syntax, define a handler that triggers an error (for example).
1187
1188
1189==== set-sharp-read-syntax!
1190
1191<procedure>(set-sharp-read-syntax! CHAR-OR-SYMBOL PROC)</procedure>
1192
1193Similar to {{set-read-syntax!}}, but allows defining new {{#<CHAR> ...}} reader syntax.
1194If the first argument is a symbol, then this procedure is equivalent to {{set-read-syntax!}}.
1195
1196
1197==== set-parameterized-read-syntax!
1198
1199<procedure>(set-parameterized-read-syntax! CHAR-OR-SYMBOL PROC)</procedure>
1200
1201Similar to {{set-sharp-read-syntax!}}, but intended for defining reader syntax of the
1202form {{#<NUMBER><CHAR> ...}}. The handler procedure {{PROC}} will be called with two
1203arguments: the input port and the number preceding
1204the dispatching character.
1205If the first argument is a symbol, then this procedure is equivalent to {{set-read-syntax!}}.
1206
1207
1208==== copy-read-table
1209
1210<procedure>(copy-read-table READ-TABLE)</procedure>
1211
1212Returns a copy of the given read-table. You can access the currently active read-table
1213with {{(current-read-table)}}.
1214
1215
1216=== Property lists
1217
1218As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols.
1219Properties are accessible via a key that can be any kind of value but which will
1220be compared using {{eq?}}.
1221
1222==== get
1223
1224  [procedure] (get SYMBOL PROPERTY [DEFAULT])
1225
1226Returns the value stored under the key {{PROPERTY}} in the property
1227list of {{SYMBOL}}. If no such property is stored, returns
1228{{DEFAULT}}. The {{DEFAULT}} is optional and defaults to {{#f}}.
1229
1230==== put!
1231
1232  [procedure] (put! SYMBOL PROPERTY VALUE)
1233  [setter] (set! (get SYMBOL PROPERTY) VALUE)
1234
1235Stores {{VALUE}} under the key {{PROPERTY}} in the property list of
1236{{SYMBOL}} replacing any previously stored value.
1237
1238==== remprop!
1239
1240  [procedure] (remprop! SYMBOL PROPERTY)
1241
1242Deletes the first property matching the key {{PROPERTY}} in the property list
1243of {{SYMBOL}}. Returns {{#t}} when a deletion performed, and {{#f}} otherwise.
1244
1245==== symbol-plist
1246
1247  [procedure] (symbol-plist SYMBOL)
1248  [setter] (set! (symbol-plist SYMBOL) LST)
1249
1250Returns the property list of {{SYMBOL}} or sets it.
1251
1252==== get-properties
1253
1254  [procedure] (get-properties SYMBOL PROPERTIES)
1255
1256Searches the property list of {{SYMBOL}} for the first property with a key in
1257the list {{PROPERTIES}}. Returns 3 values: the matching property key, value,
1258and the tail of property list after the matching property. When no match found
1259all values are {{#f}}.
1260
1261{{PROPERTIES}} may also be an atom, in which case it is treated as a list of
1262one element.
1263
1264---
1265Previous: [[Parameters]]
1266
1267Next: [[Unit eval]]
Note: See TracBrowser for help on using the repository browser.