source: project/chicken/branches/hygienic/manual/Unit library @ 11989

Last change on this file since 11989 was 11989, checked in by felix winkelmann, 12 years ago

added srfi-98 support, chicken-install should handle core library units as dependencies (untested)

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