source: project/chicken/branches/prerelease/manual/Unit library @ 15101

Last change on this file since 15101 was 15101, checked in by felix winkelmann, 10 years ago

merged trunk changes from 14491:15100 into prerelease branch

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