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

Last change on this file since 15600 was 15600, checked in by felix winkelmann, 11 years ago

added get-condition-property

File size: 31.9 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.
331
332
333
334==== get-keyword
335
336<procedure>(get-keyword KEYWORD ARGLIST [THUNK])</procedure>
337
338Returns the argument from {{ARGLIST}} specified under the keyword
339{{KEYWORD}}. If the keyword is not found, then the zero-argument
340procedure {{THUNK}} is invoked and the result value is returned. If
341{{THUNK}} is not given, {{#f}} is returned.
342
343<enscript highlight=scheme>
344(define (increase x . args)
345  (+ x (get-keyword #:amount args (lambda () 1))) )
346(increase 123)                                      ==> 124
347(increase 123 #:amount 10)                          ==> 133
348</enscript>
349
350Note: the {{KEYWORD}} may actually be any kind of object.
351
352
353==== keyword?
354
355<procedure>(keyword? X)</procedure>
356
357Returns {{#t}} if {{X}} is a keyword symbol, or {{#f}}
358otherwise.
359
360
361==== keyword->string
362
363<procedure>(keyword->string KEYWORD)</procedure>
364
365Transforms {{KEYWORD}} into a string.
366
367
368==== string->keyword
369
370<procedure>(string->keyword STRING)</procedure>
371
372Returns a keyword with the name {{STRING}}.
373
374
375
376
377
378=== Exceptions
379
380
381CHICKEN implements the (currently withdrawn)
382[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] exception system. For
383more information, see the
384[[http://srfi.schemers.org/srfi-12/srfi-12.html|SRFI-12]] document.
385
386
387
388==== condition-case
389
390 [syntax] (condition-case EXPRESSION CLAUSE ...)
391
392Evaluates {{EXPRESSION}} and handles any exceptions that are covered by
393{{CLAUSE ...}}, where {{CLAUSE}} should be of the following form:
394
395<enscript highlight=scheme>
396CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
397</enscript>
398
399If provided, {{VARIABLE}} will be bound to the signaled exception
400object. {{BODY ...}} is executed when the exception is a property-
401or composite condition with the kinds given {{KIND ...}} (unevaluated).
402If no clause applies, the exception is re-signaled in the same dynamic
403context as the {{condition-case}} form.
404
405<enscript highlight=scheme>
406(define (check thunk)
407  (condition-case (thunk)
408    [(exn file) (print "file error")]
409    [(exn) (print "other error")]
410    [var () (print "something else")] ) )
411
412(check (lambda () (open-input-file "")))   ; -> "file error"
413(check (lambda () some-unbound-variable))  ; -> "othererror"
414(check (lambda () (signal 99)))            ; -> "something else"
415
416(condition-case some-unbound-variable
417  [(exn file) (print "ignored")] )      ; -> signals error
418
419</enscript>
420
421
422==== breakpoint
423
424<procedure>(breakpoint [NAME])</procedure>
425
426Programmatically triggers a breakpoint (similar to the {{,br}} top-level csi
427command).
428
429
430==== get-condition-property
431
432<procedure>(get-condition-property CONDITION KIND PROPERTY [DEFAULT])</procedure>
433
434A slightly more convenient condition property accessor, equivalent to
435
436  ((condition-property-accessor KIND PROPERTY [DEFAULT]) CONDITION)
437
438
439==== System conditions
440
441All error-conditions signaled by the system are of kind {{exn}}.
442The following composite conditions are additionally defined:
443
444<table>
445
446<tr><td> (exn arity)
447
448Signaled when a procedure is called with the wrong number of arguments.
449
450</td></tr><tr><td> (exn type)
451
452Signaled on type-mismatch errors, for example when an argument of the wrong
453type is passed to a built-in procedure.
454
455</td></tr><tr><td> (exn arithmetic)
456
457Signaled on arithmetic errors, like division by zero.
458
459</td></tr><tr><td> (exn i/o)
460
461Signaled on input/output errors.
462
463</td></tr><tr><td> (exn i/o file)
464
465Signaled on file-related errors.
466
467</td></tr><tr><td> (exn i/o net)
468
469Signaled on network errors.
470
471</td></tr><tr><td> (exn bounds)
472
473Signaled on errors caused by accessing non-existent elements of a collection.
474
475</td></tr><tr><td> (exn runtime)
476
477Signaled on low-level runtime-system error-situations.
478
479</td></tr><tr><td> (exn runtime limit)
480
481Signaled when an internal limit is exceeded (like running out of memory).
482
483</td></tr><tr><td> (exn match)
484
485Signaled on errors raised by failed matches (see the section on {{match}}).
486
487</td></tr><tr><td> (exn syntax)
488
489Signaled on syntax errors.
490
491</td></tr><tr><td> (exn breakpoint)
492
493Signaled when a breakpoint is reached.
494
495</td></tr>
496
497</table>
498
499Notes:
500
501* All error-exceptions (of the kind {{exn}}) are non-continuable.
502
503* Error-exceptions of the {{exn}} kind have additional {{arguments}} and
504{{location}} properties that contain the arguments passed to the
505exception-handler and the name of the procedure where the error occurred (if
506available).
507
508* When the {{posix}} unit is available and used, then a user-interrupt
509({{signal/int}}) signals an exception of the kind {{user-interrupt}}.
510
511* the procedure {{condition-property-accessor}} accepts an optional third
512argument. If the condition does not have a value for the desired property and
513if the optional argument is given, no error is signaled and the accessor
514returns the third argument.
515
516* In composite conditions all properties are currently collected in a single
517property-list, so in the case that to conditions have the same named property,
518only one will be visible.
519
520
521
522=== Environment information and system interface
523
524
525
526==== argv
527
528<procedure>(argv)</procedure>
529
530Return a list of all supplied command-line arguments. The first item in
531the list is a string containing the name of the executing program. The
532other items are the arguments passed to the application. This list is
533freshly created on every invocation of {{(argv)}}. It depends on
534the host-shell whether arguments are expanded ('globbed') or not.
535
536
537==== exit
538
539<procedure>(exit [CODE])</procedure>
540
541Exit the running process and return exit-code, which defaults to 0
542(Invokes {{exit-handler}}).
543
544Note that pending {{dynamic-wind}} thunks are ''not'' invoked when exiting your program in this way.
545
546==== build-platform
547
548<procedure>(build-platform)</procedure>
549
550Returns a symbol specifying the toolset which has been used for
551building the executing system, which is one of the following:
552
553 cygwin
554 mingw32
555 gnu
556 intel
557 unknown
558
559
560==== chicken-version
561
562<procedure>(chicken-version [FULL])</procedure>
563
564Returns a string containing the version number of the CHICKEN runtime
565system. If the optional argument {{FULL}} is given and true, then
566a full version string is returned.
567
568
569==== errno
570
571<procedure>(errno)</procedure>
572
573Returns the error code of the last system call.
574
575
576==== get-environment-variable
577
578 [procedure] (get-environment-variable STRING)
579 [procedure] (getenv STRING)
580
581Returns the value of the environment variable {{STRING}} or
582{{#f}} if that variable is not defined. See also [[http://srfi.schemers.org/srfi-98/|SRFI-98]].
583{{getenv}} is an alias for {{get-environment-variable}}.
584
585
586==== machine-byte-order
587
588<procedure>(machine-byte-order)</procedure>
589
590Returns the symbol {{little-endian}} or {{big-endian}}, depending on the
591machine's byte-order.
592
593
594==== machine-type
595
596<procedure>(machine-type)</procedure>
597
598Returns a symbol specifying the processor on which this process is
599currently running, which is one of the following:
600
601 alpha
602 mips
603 hppa
604 ultrasparc
605 sparc
606 ppc
607 ppc64
608 ia64
609 x86
610 x86-64
611 unknown
612
613
614==== on-exit
615
616<procedure>(on-exit THUNK)</procedure>
617
618Schedules the zero-argument procedures {{THUNK}} to be executed before
619the process exits, either explicitly via {{exit}} or implicitly after execution
620of the last top-level form. Note that finalizers for unreferenced finalized
621data are run before exit procedures.
622
623
624==== software-type
625
626<procedure>(software-type)</procedure>
627
628Returns a symbol specifying the operating system on which this process
629is currently running, which is one of the following:
630
631 windows
632 unix
633 macos
634 ecos
635 unknown
636
637
638==== software-version
639
640<procedure>(software-version)</procedure>
641
642Returns a symbol specifying the operating system version on which this
643process is currently running, which is one of the following:
644
645 linux
646 freebsd
647 netbsd
648 openbsd
649 macosx
650 hpux
651 solaris
652 sunos
653 unknown
654
655
656
657==== c-runtime
658
659<procedure>(c-runtime)</procedure>
660
661Returns a symbol that designates what kind of C runtime library has been linked
662with this version of the Chicken libraries. Possible return values are
663{{static}}, {{dynamic}} or {{unknown}}. On systems not compiled with the
664Microsoft C compiler, {{c-runtime}} always returns {{unknown}}.
665
666
667==== system
668
669<procedure>(system STRING)</procedure>
670
671Execute shell command. The functionality offered by this procedure
672depends on the capabilities of the host shell. If the forking of a subprocess
673failed, an exception is raised. Otherwise the return status of the
674subprocess is returned unaltered.
675
676
677On 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:
678
679 ;; Returns two values: #t if the process exited normally or #f otherwise;
680 ;; and either the exit status, or the signal number if terminated via signal.
681 (define (process-status rc)
682   (define (wait-signaled? x) (not (= 0 (bitwise-and x 127))))
683   (define (wait-signal x) (bitwise-and x 127))
684   (define (wait-exit-status x) (arithmetic-shift x -8))
685   (if (wait-signaled? rc)
686       (values #f (wait-signal rc))
687       (values #t (wait-exit-status rc))))
688
689 #;> (process-status (system "exit 42"))
690 #t
691 42
692
693=== Execution time
694
695
696
697==== cpu-time
698
699<procedure>(cpu-time)</procedure>
700
701Returns the used CPU time of the current process in milliseconds as
702two values: the time spent in user code, and the time spent in system
703code. On platforms where user and system time can not be differentiated,
704system time will be always be 0.
705
706
707==== current-milliseconds
708
709<procedure>(current-milliseconds)</procedure>
710
711Returns the number of milliseconds since process- or machine startup.
712
713
714==== current-seconds
715
716<procedure>(current-seconds)</procedure>
717
718Returns the number of seconds since midnight, Jan. 1, 1970.
719
720
721==== current-gc-milliseconds
722
723<procedure>(current-gc-milliseconds)</procedure>
724
725Returns the number of milliseconds spent in major garbage collections since
726the last call of {{current-gc-milliseconds}} and returns an exact
727integer.
728
729
730
731=== Interrupts and error-handling
732
733
734
735==== enable-warnings
736
737<procedure>(enable-warnings [BOOL])</procedure>
738
739Enables or disables warnings, depending on wether {{BOOL}} is true or false.
740If called with no arguments, this procedure returns {{#t}} if warnings are
741currently enabled, or {{#f}} otherwise. Note that this is not a parameter.
742The current state (whether warnings are enabled or disabled) is global and not
743thread-local.
744
745
746==== error
747
748<procedure>(error [LOCATION] [STRING] EXP ...)</procedure>
749
750Prints error message, writes all extra arguments to the
751value of {{(current-error-port)}} and invokes the
752current exception-handler. This conforms to
753[[http://srfi.schemers.org/srfi-23/srfi-23.html|SRFI-23]].
754If {{LOCATION}} is given and a symbol, it specifies the ''location'' (the name
755of the procedure) where the error occurred.
756
757
758
759==== get-call-chain
760
761<procedure>(get-call-chain [START [THREAD]])</procedure>
762
763Returns a list with the call history. Backtrace information
764is only generated in code compiled without {{-no-trace}} and evaluated code.
765If the optional argument {{START}} is given, the backtrace starts
766at this offset, i.e. when {{START}} is 1, the next to last trace-entry
767is printed, and so on. If the optional argument {{THREAD}} is given, then
768the call-chain will only be constructed for calls performed by this thread.
769
770
771
772==== print-call-chain
773
774<procedure>(print-call-chain [PORT [START [THREAD]]])</procedure>
775
776Prints a backtrace of the procedure call history to {{PORT}},
777which defaults to {{(current-output-port)}}.
778
779
780==== print-error-message
781
782<procedure>(print-error-message EXN [PORT [STRING]])</procedure>
783
784Prints an appropriate error message to {{PORT}} (which defaults to the
785value of {{(current-output-port)}} for the object {{EXN}}.
786{{EXN}} may be a condition, a string or any other object.
787If the optional argument {{STRING}} is given, it is printed before the
788error-message. {{STRING}} defaults to {{"Error:"}}.
789
790
791
792==== procedure-information
793
794<procedure>(procedure-information PROC)</procedure>
795
796Returns an s-expression with debug information for the procedure {{PROC}}, or
797{{#f}}, if {{PROC}} has no associated debug information.
798
799
800==== reset
801
802<procedure>(reset)</procedure>
803
804Reset program (Invokes {{reset-handler}}).
805
806
807==== warning
808
809<procedure>(warning STRING EXP ...)</procedure>
810
811Displays a warning message (if warnings are enabled with {{enable-warnings}}) and
812continues execution.
813
814
815==== singlestep
816
817<procedure>(singlestep THUNK)</procedure>
818
819Executes the code in the zero-procedure {{THUNK}} in single-stepping mode.
820
821
822
823=== Garbage collection
824
825
826
827==== gc
828
829<procedure>(gc [FLAG])</procedure>
830
831Invokes a garbage-collection and returns the number of free bytes in the heap.
832The flag specifies whether a minor ({{#f}}) or major ({{#t}}) GC is to be
833triggered. If no argument is given, {{#t}} is assumed. An explicit {{#t}}
834argument will cause all pending finalizers to be executed.
835
836==== memory-statistics
837
838<procedure>(memory-statistics)</procedure>
839
840Performs a major garbage collection and returns a three element vector
841containing the total heap size in bytes, the number of bytes currently
842used and the size of the nursery (the first heap generation). Note
843that the actual heap is actually twice the size given in the heap size,
844because CHICKEN uses a copying semi-space collector.
845
846
847==== set-finalizer!
848
849<procedure>(set-finalizer! X PROC)</procedure>
850
851Registers a procedure of one argument {{PROC}}, that will be
852called as soon as the non-immediate data object {{X}} is about to
853be garbage-collected (with that object as its argument). Note that
854the finalizer will '''not''' be called while interrupts are disabled.
855This procedure returns {{X}}.
856
857Finalizers are invoked asynchronously, in the thread that happens
858to be currently running.
859
860
861==== set-gc-report!
862
863<procedure>(set-gc-report! FLAG)</procedure>
864
865Print statistics after every GC, depending on {{FLAG}}. A value of
866{{#t}} shows statistics after every major GC. A true value different
867from {{#t}} shows statistics after every minor GC. {{#f}}
868switches statistics off.
869
870
871
872
873
874=== Other control structures
875
876
877
878==== promise?
879
880<procedure>(promise? X)</procedure>
881
882Returns {{#t}} if {{X}} is a promise returned by {{delay}}, or
883{{#f}} otherwise.
884
885
886
887=== String utilities
888
889
890==== reverse-list->string
891
892<procedure>(reverse-list->string LIST)</procedure>
893
894Returns a string with the characters in {{LIST}} in reverse order. This is
895equivalent to {{(list->string (reverse LIST))}}, but much more efficient.
896
897
898
899=== Generating uninterned symbols
900
901==== gensym
902
903<procedure>(gensym [STRING-OR-SYMBOL])</procedure>
904
905Returns a newly created uninterned symbol. If an argument is provided,
906the new symbol is prefixed with that argument.
907
908
909==== string->uninterned-symbol
910
911<procedure>(string->uninterned-symbol STRING)</procedure>
912
913Returns a newly created, unique symbol with the name {{STRING}}.
914
915
916
917=== Standard Input/Output
918
919==== port?
920
921<procedure>(port? X)</procedure>
922
923Returns {{#t}} if {{X}} is a port object or {{#f}}
924otherwise.
925
926
927==== print
928
929<procedure>(print [EXP1 ...])</procedure>
930
931Outputs the optional arguments {{EXP1 ...}} using {{display}} and
932writes a newline character to the port that is the value of
933{{(current-output-port)}}. Returns {{(void)}}.
934
935
936==== print*
937
938<procedure>(print* [EXP1 ...])</procedure>
939
940Similar to {{print}}, but does not output a terminating newline
941character and performs a {{flush-output}} after writing its arguments.
942
943
944
945
946=== User-defined named characters
947
948==== char-name
949
950<procedure>(char-name SYMBOL-OR-CHAR [CHAR])</procedure>
951
952This procedure can be used to inquire about character names or to
953define new ones. With a single argument the behavior is as follows:
954If {{SYMBOL-OR-CHAR}} is a symbol, then {{char-name}} returns
955the character with this name, or {{#f}} if no character is defined
956under this name. If {{SYMBOL-OR-CHAR}} is a character, then the
957name of the character is returned as a symbol, or {{#f}} if the
958character has no associated name.
959
960If the optional argument {{CHAR}} is provided, then
961{{SYMBOL-OR-CHAR}} should be a symbol that will be the new name of
962the given character. If multiple names designate the same character,
963then the {{write}} will use the character name that was defined last.
964
965<enscript highlight=scheme>
966(char-name 'space)                  ==> #\space
967(char-name #\space)                 ==> space
968(char-name 'bell)                   ==> #f
969(char-name (integer->char 7))       ==> #f
970(char-name 'bell (integer->char 7))
971(char-name 'bell)                   ==> #\bell
972(char->integer (char-name 'bell))   ==> 7
973</enscript>
974
975
976
977=== Blobs
978
979"blobs" are collections of unstructured bytes. You can't do much
980with them, but allow conversion to and from SRFI-4 number vectors.
981
982==== make-blob
983
984<procedure>(make-blob SIZE)</procedure>
985
986Returns a blob object of {{SIZE}} bytes, aligned on an 8-byte boundary,
987uninitialized.
988
989==== blob?
990
991<procedure>(blob? X)</procedure>
992
993Returns {{#t}} if {{X}} is a blob object, or
994{{#f}} otherwise.
995
996==== blob-size
997
998<procedure>(blob-size BLOB)</procedure>
999
1000Returns the number of bytes in {{BLOB}}.
1001
1002==== blob->string
1003
1004<procedure>(blob->string BLOB)</procedure>
1005
1006Returns a string with the contents of {{BLOB}}.
1007
1008==== string->blob
1009
1010<procedure>(string->blob STRING)</procedure>
1011
1012Returns a blob with the contents of {{STRING}}.
1013
1014==== blob=?
1015
1016<procedure>(blob=? BLOB1 BLOB2)</procedure>
1017
1018Returns {{#t}} if the two argument blobs are of the same
1019size and have the same content.
1020
1021
1022
1023=== Vectors
1024
1025==== vector-copy!
1026
1027<procedure>(vector-copy! VECTOR1 VECTOR2 [COUNT])</procedure>
1028
1029Copies contents of {{VECTOR1}} into {{VECTOR2}}. If the
1030argument {{COUNT}} is given, it specifies the maximal number of
1031elements to be copied. If not given, the minimum of the lengths of the
1032argument vectors is copied.
1033
1034Exceptions: {{(exn bounds)}}
1035
1036
1037==== vector-resize
1038
1039<procedure>(vector-resize VECTOR N [INIT])</procedure>
1040
1041Creates and returns a new vector with the contents of {{VECTOR}} and length
1042{{N}}. If {{N}} is greater than the original length of {{VECTOR}}, then all
1043additional items are initialized to {{INIT}}. If {{INIT}} is not specified, the
1044contents are initialized to some unspecified value.
1045
1046
1047
1048=== The unspecified value
1049
1050==== void
1051
1052<procedure>(void)</procedure>
1053
1054Returns an unspecified value.
1055
1056
1057
1058=== Continuations
1059
1060==== call/cc
1061
1062<procedure>(call/cc PROCEDURE)</procedure>
1063
1064An alias for {{call-with-current-continuation}}.
1065
1066
1067==== continuation-capture
1068
1069<procedure>(continuation-capture PROCEDURE)</procedure>
1070
1071Creates a continuation object representing the current continuation and
1072tail-calls {{PROCEDURE}} with this continuation as the single argument.
1073
1074More information about this continuation API can be found in the paper
1075[[http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf]] ''A Better
1076API for first class Continuations'' by Marc Feeley.
1077
1078
1079==== continuation?
1080
1081<procedure>(continuation? X)</procedure>
1082
1083Returns {{#t}} if {{X}} is a continuation object, or {{#f}} otherwise. Please
1084note that this applies only to continuations created by the Continuation API,
1085but not by call/cc, i.e.: {{(call-with-current-continuation continuation?)}}
1086returns {{#f}}, whereas {{(continuation-capture continuation?)}} returns
1087{{#t}}.
1088
1089
1090==== continuation-graft
1091
1092<procedure>(continuation-graft CONT THUNK)</procedure>
1093
1094Calls the procedure {{THUNK}} with no arguments and the implicit continuation
1095{{CONT}}.
1096
1097
1098==== continuation-return
1099
1100<procedure>(continuation-return CONT VALUE ...)</procedure>
1101
1102Returns the value(s) to the continuation {{CONT}}. {{continuation-return}} could
1103be implemented like this:
1104
1105<enscript highlight=scheme>
1106(define (continuation-return k . vals)
1107  (continuation-graft
1108    k
1109    (lambda () (apply values vals)) ) )
1110</enscript>
1111
1112
1113
1114=== Setters
1115
1116SRFI-17 is fully implemented. For more information see:
1117[[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
1118
1119==== setter
1120
1121<procedure>(setter PROCEDURE)</procedure>
1122
1123Returns the setter-procedure of {{PROCEDURE}}, or signals an error if
1124{{PROCEDURE}} has no associated setter-procedure.
1125
1126Note that {{(set! (setter PROC) ...)}} for a procedure that has no associated
1127setter procedure yet is a very slow operation (the old procedure is replaced by
1128a modified copy, which involves a garbage collection).
1129
1130
1131==== getter-with-setter
1132
1133<procedure>(getter-with-setter GETTER SETTER)</procedure>
1134
1135Returns a copy of the procedure {{GETTER}} with the associated setter procedure
1136{{SETTER}}. Contrary to the SRFI specification, the setter of the returned
1137procedure may be changed.
1138
1139
1140
1141=== Reader extensions
1142
1143==== define-reader-ctor
1144
1145<procedure>(define-reader-ctor SYMBOL PROC)</procedure>
1146
1147Define new read-time constructor for {{#,}} read syntax. For further information, see
1148the documentation for [[http://srfi.schemers.org/srfi-10/srfi-10.html|SRFI-10]].
1149
1150
1151==== set-read-syntax!
1152
1153<procedure>(set-read-syntax! CHAR-OR-SYMBOL PROC)</procedure>
1154
1155When the reader encounters the non-whitespace character {{CHAR}} while reading
1156an expression from a given port, then the procedure {{PROC}} will be called with
1157that port as its argument. The procedure should return a value that will be returned
1158to the reader:
1159
1160<enscript highlight=scheme>
1161 ; A simple RGB color syntax:
1162
1163 (set-read-syntax! #\%
1164   (lambda (port)
1165     (apply vector
1166       (map (cut string->number <> 16)
1167            (string-chop (read-string 6 port) 2) ) ) ) )
1168
1169 (with-input-from-string "(1 2 %f0f0f0 3)" read)
1170 ; ==> (1 2 #(240 240 240) 3)
1171</enscript>
1172
1173If {{CHAR-OR-SYMBOL}} is a symbol, then a so-called ''read-mark'' handler is defined.
1174In that case the handler procedure will be called when a character-sequence of the
1175form
1176
1177 #!SYMBOL
1178
1179is encountered.
1180
1181You can undo special handling of read-syntax by passing {{#f}} as the second argument
1182(if the syntax was previously defined via {{set-read-syntax!}}).
1183
1184Note that all of CHICKEN's special non-standard read-syntax is handled directly by the reader.
1185To disable built-in read-syntax, define a handler that triggers an error (for example).
1186
1187
1188==== set-sharp-read-syntax!
1189
1190<procedure>(set-sharp-read-syntax! CHAR-OR-SYMBOL PROC)</procedure>
1191
1192Similar to {{set-read-syntax!}}, but allows defining new {{#<CHAR> ...}} reader syntax.
1193If the first argument is a symbol, then this procedure is equivalent to {{set-read-syntax!}}.
1194
1195
1196==== set-parameterized-read-syntax!
1197
1198<procedure>(set-parameterized-read-syntax! CHAR-OR-SYMBOL PROC)</procedure>
1199
1200Similar to {{set-sharp-read-syntax!}}, but intended for defining reader syntax of the
1201form {{#<NUMBER><CHAR> ...}}. The handler procedure {{PROC}} will be called with two
1202arguments: the input port and the number preceding
1203the dispatching character.
1204If the first argument is a symbol, then this procedure is equivalent to {{set-read-syntax!}}.
1205
1206
1207==== copy-read-table
1208
1209<procedure>(copy-read-table READ-TABLE)</procedure>
1210
1211Returns a copy of the given read-table. You can access the currently active read-table
1212with {{(current-read-table)}}.
1213
1214
1215=== Property lists
1216
1217As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols.
1218Properties are accessible via a key that can be any kind of value but which will
1219be compared using {{eq?}}.
1220
1221==== get
1222
1223  [procedure] (get SYMBOL PROPERTY [DEFAULT])
1224
1225Returns the value stored under the key {{PROPERTY}} in the property
1226list of {{SYMBOL}}. If no such property is stored, returns
1227{{DEFAULT}}. The {{DEFAULT}} is optional and defaults to {{#f}}.
1228
1229==== put!
1230
1231  [procedure] (put! SYMBOL PROPERTY VALUE)
1232  [setter] (set! (get SYMBOL PROPERTY) VALUE)
1233
1234Stores {{VALUE}} under the key {{PROPERTY}} in the property list of
1235{{SYMBOL}} replacing any previously stored value.
1236
1237==== remprop!
1238
1239  [procedure] (remprop! SYMBOL PROPERTY)
1240
1241Deletes the first property matching the key {{PROPERTY}} in the property list
1242of {{SYMBOL}}. Returns {{#t}} when a deletion performed, and {{#f}} otherwise.
1243
1244==== symbol-plist
1245
1246  [procedure] (symbol-plist SYMBOL)
1247  [setter] (set! (symbol-plist SYMBOL) LST)
1248
1249Returns the property list of {{SYMBOL}} or sets it.
1250
1251==== get-properties
1252
1253  [procedure] (get-properties SYMBOL PROPERTIES)
1254
1255Searches the property list of {{SYMBOL}} for the first property with a key in
1256the list {{PROPERTIES}}. Returns 3 values: the matching property key, value,
1257and the tail of property list after the matching property. When no match found
1258all values are {{#f}}.
1259
1260{{PROPERTIES}} may also be an atom, in which case it is treated as a list of
1261one element.
1262
1263---
1264Previous: [[Parameters]]
1265
1266Next: [[Unit eval]]
Note: See TracBrowser for help on using the repository browser.