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

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

small manual fixes; merged wiki changes (rev. 13647) into manual

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