char-up/lo dox
[k8-xscheme:k8-xscheme.git] / dox / xscheme.txt
1 XSCHEME: An Object-oriented Scheme
2
3 Version 0.28.1
4
5 by David Michael Betz
6 changes by Ketmar // Vampire Avalon
7
8
9 Copyright (c) 1988, David Michael Betz
10 Copyright (c) 2010, Ketmar // Vampire Avalon
11 All rights reserved.
12
13 Redistribution and use in source and binary forms, with or without
14 modification, are permitted provided that the following conditions are met:
15   * Redistributions of source code must retain the above copyright notice,
16     this list of conditions and the following disclaimer.
17   * Redistributions in binary form must reproduce the above copyright notice,
18     this list of conditions and the following disclaimer in the documentation
19     and/or other materials provided with the distribution.
20   * Neither rhe names of the authors nor the names of contributors may be
21     used to endorse or promote products derived from this software without
22     specific prior written permission.
23
24 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
25 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
27 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
28 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
30 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
32 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
33 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34
35
36
37 TABLE OF CONTENTS
38
39     TABLE OF CONTENTS.................................
40     INTRODUCTION......................................
41     A NOTE FROM KETMAR................................
42     EXPRESSIONS.......................................
43     GLOBAL VARIABLES..................................
44     BINDING FORMS.....................................
45     SEQUENCING........................................
46     DELAYED EVALUATION................................
47     ITERATION.........................................
48     DEFINITIONS.......................................
49     LIST FUNCTIONS....................................
50     DESTRUCTIVE LIST FUNCTIONS........................
51     SYMBOL FUNCTIONS..................................
52     VECTOR FUNCTIONS..................................
53     ARRAY FUNCTIONS...................................
54     CONVERSION FUNCTIONS..............................
55     TYPE PREDICATES...................................
56     EQUALITY PREDICATES...............................
57     ARITHMETIC FUNCTIONS..............................
58     NUMERIC COMPARISON FUNCTIONS......................
59     BITWISE LOGICAL FUNCTIONS.........................
60     STRING FUNCTIONS..................................
61     STRING COMPARISON FUNCTIONS.......................
62     CHARACTER COMPARISON FUNCTIONS....................
63     INPUT/OUTPUT FUNCTIONS............................
64     OUTPUT CONTROL FUNCTIONS..........................
65     FILE I/O FUNCTIONS................................
66     CONTROL FEATURES..................................
67     ENVIRONMENT FUNCTIONS.............................
68     UTILITY FUNCTIONS.................................
69     SYSTEM FUNCTIONS..................................
70     OTHER FUNCTIONS...................................
71     OS FUNCTIONS......................................
72     DLIB FUNCTIONS....................................
73     TRE REGULAR EXPRESSION FUNCTIONS..................
74     VARIOUS LIBRARY FUNCTIONS.........................
75     OBJECT REPRESENTATIONS............................
76
77
78
79 INTRODUCTION
80 ============
81
82 XScheme is an implementation of the Scheme programming language
83 with extensions to support object-oriented programming.
84
85 There are currently implementations of XScheme running on the
86 various 32-bit architecture under GNU/Linux and Windows OSes.
87 It is completely written in the programming language 'C' and is
88 easily extended with user written built-in functions and classes.
89 It is suitable for embedding in C/C++ projects too.
90
91 This document is a brief description of XScheme. It assumes some
92 knowledge of Scheme or LISP and some understanding of the concepts
93 of object-oriented programming.
94
95 I recommend the book "Structure and Interpretation of Computer
96 Programs" by Harold Abelson and Gerald Jay Sussman and published
97 by The MIT Press and the McGraw-Hill Book Company for learning
98 Scheme (and programming in general). You might also find "The
99 Scheme Programming Language" by R. Kent Dybvig and "The Little
100 Lisper" by Daniel P. Friedman and Matthias Felleisen to be
101 helpful.
102
103
104
105 A NOTE FROM KETMAR
106 ==================
107
108 PLEASE, don't write David about this fork. He is not supporting this
109 fork and can't answer to your questions!
110
111 Some descriptions was taken from various sources like PLT-Scheme
112 documentation or SRFI texts. Thanx to all who wrote that documents.
113
114
115
116 EXPRESSIONS
117 ===========
118
119 ;...
120
121     Comment. Ignore everything until EOL.
122
123 #| ... |#
124
125     Multi-line comment. Can't be nested.
126
127 #;
128
129     Datum comment. Read next datum and ignore it. Note that such
130     comments can be nested.
131
132 <variable>
133
134     An expression consisting of a variable is a variable
135     reference. The value of the variable reference is the value
136     stored in the location to which the variable is bound. It
137     is an error to reference an unbound variable.
138
139 (atom|keyword ...)
140
141     Lists that starts with keyword symbol (':...') or with atom
142     are "autoquoted".
143
144 (QUOTE <datum>)
145 '<datum>
146
147     (quote <datum>) evaluates to <datum>. <Datum> may be any
148     external representation of a Scheme object. This notation
149     is used to include literal constants in Scheme code. (quote
150     <datum>) may be abbreviated as '<datum>. The two notations
151     are equivalent in all respects.
152
153 <constant>
154
155     Numeric constants, string constants, character constants,
156     boolean constants and keywords evaluate "to themselves"; they
157     need not be quoted.
158
159 #(...)
160
161     Vector. Autoquoted.
162
163 #[...]
164
165     Byte vector. Autoquoted.
166
167 #"..."
168
169     Simple string. Does not understand escaping. '"' can be entered
170     by putting it twice.
171
172 "..."
173
174     String. Can span across multiple lines. Understand C-like escaping.
175     Understands "\0", "\e" ("\x1b") and "\xNN".
176
177 (<operator> <operand>...)
178
179     A procedure call is written by simply enclosing in
180     parentheses expressions for the procedure to be called and
181     the arguments to be passed to it. The operator and operand
182     expressions are evaluated and the resulting procedure is
183     passed the resulting arguments.
184
185 (<object> <selector> <operand>...)
186
187     A message sending form is written by enclosing in
188     parentheses expressions for the receiving object, the
189     message selector, and the arguments to be passed to the
190     method. The receiver, selector, and argument expressions
191     are evaluated, the message selector is used to select an
192     appropriate method to handle the message, and the resulting
193     method is passed the resulting arguments.
194
195 (LAMBDA <formals> <body>)
196
197     <Formals> should be a formal argument list as described
198     below, and <body> should be a sequence of one or more
199     expressions. A lambda expression evaluates to a procedure.
200     The environment in effect when the lambda expression is
201     evaluated is remembered as part of the procedure. When the
202     procedure is later called with some actual arguments, the
203     environment in which the lambda expression was evaluated
204     will be extended by binding the variables in the formal
205     argument list to fresh locations, the corresponding actual
206     argument values will be stored in those locations, and the
207     expressions in the body of the lambda expression will be
208     evaluated sequentially in the extended environment. The
209     result of the last expression in the body will be returned
210     as the result of the procedure call.
211
212     <Formals> should have the following form:
213         (<var>... [#!OPTIONAL <ovar>...] [. <rvar>])
214       or
215         (<var>... [#!OPTIONAL <ovar>...] [#!REST <rvar>] [#!KEY <kvar>...])
216       where:
217         <var>    is a required argument
218         <ovar>   is an optional argument
219         <rvar>   is a "rest" argument
220         <kvar>   is a keyword argument
221
222     There are four parts to a <formals> list.
223     The first lists the required arguments of the procedure.
224     All calls to the procedure must supply values for each of
225     the required arguments.
226     The second part lists the optional arguments of the procedure.
227     An optional argument may be supplied in a call or omitted.
228     If it is omitted, a special value is given to the argument
229     that satisfies the default-object? predicate.
230     This provides a way to test to see if an optional argument
231     was provided in a call or omitted.
232     The third part of the <formals> list gives the "rest" argument.
233     This argument will be bound to the rest of the list of
234     arguments supplied to a call after the required and optional
235     arguments have been removed.
236     The fourth part of the <formals> list gives the "key" argument.
237     This is the list of "keyword" arguments a-la Common Lisp ones.
238     The arguments will be searched by "keywords" and binded if
239     found.
240
241     <ovar> can be a simple symbol name or an expression like
242     (sym def-val... [. var]). All previously bounded symbols (args)
243     can be used in def-val expression. This expression will be
244     evaluated only if there is no value for this arg was supplied
245     in function call. Note that there is no way to determine if
246     the value was supplied by the user or was the result of
247     def-val evaluation.
248     if the last var is specified (note the dot!), it will be set to
249     #t if user was specified the arg or to #f if user is not
250     specified the arg.
251     If user will not supply an argument for the "simple" form (i.e.
252     for the argument which is defined by a simple symbol name), the
253     value of this argument will satisfy the default-object? predicate.
254
255     <kvar> can be a simple symbol name or an expression like
256     sym|(sym|(kw sym) def-val... [. var]). 'kw' is the keyword
257     name (it must begin with colon -- ':' -- and it is autoquoted).
258
259     (define (a a0
260                #!rest rest
261                #!key text
262                      (title "tit")
263                      ((:x xpos) . xset)
264                      ((:y ypos)))
265       ...)
266     here we have a simple declaration -- 'text'. The keyword for
267     such declaration is a symbol name prefixed with colon (":text").
268     If user will not supply a keyword argument for this keyword,
269     the value of text will satisfy the default-object? predicate.
270     The second type of declaration is for "title". It has
271     initializer expression. Such expression will be evaluated if
272     there is no keyword ":title" found in argument list.
273     The third type of declaration is for "xpos". It has explicit
274     keyword (":x") and "xset" -- the variable that will be set to
275     #t if user supplied this keyword argument. There is no
276     initializer expression, so the default value of "xpos" will
277     be #nil.
278     The fourth type of declaration is almost the same as the third.
279     It has no special variable that indicates if the user supplies
280     this keyword argument, but otherwise the same as the previous
281     type.
282
283
284 (IF <test> <consequent> [<alternate>])
285
286     An if expression is evaluated as follows: first, <test> is
287     evaluated. If it yields a true value, then <consequent> is
288     evaluated and its value is returned. Otherwise, <alternate>
289     is evaluated and its value is returned. If <test> yields a
290     false value and no <alternate> is specified, then the result
291     of the expression is #f.
292
293 (IFNOT <test> <consequent> [<alternate>])
294
295     An if expression is evaluated as follows: first, <test> is
296     evaluated. If it yields a false value, then <consequent> is
297     evaluated and its value is returned. Otherwise, <alternate>
298     is evaluated and its value is returned. If <test> yields a
299     true value and no <alternate> is specified, then the result
300     of the expression is <test> value.
301
302 (IFX <test> [<alternate>])
303
304     An if expression is evaluated as follows: first, <test> is
305     evaluated. If it yields a non-false value, then it becomes
306     the result of the expression. Otherwise, <alternate> is
307     evaluated and its value is returned.
308
309 (ACCESS <variable> <env>)
310
311     <Env> is evaluated producing an environment. The result is
312     the value of <variable> in this environment.
313
314 (SET! <variable> <expression>)
315
316     <Expression> is evaluated, and the resulting value is stored
317     in the location to which <variable> is bound. <Variable>
318     must be bound in some region or at the top level.
319     The result of the set! expression is <expression> value.
320
321 (SET! (ACCESS <variable> <env>) <value>)
322
323     <Env> is evaluated producing an environment. <Value> is
324     evaluated and the resulting value is stored as the value of
325     <variable> in this environment.
326     The result of the set! expression is <expression> value.
327
328 (COND <clause>...)
329
330     Each clause should be of the form
331
332         (<test> <expression>...)
333
334     where <test> is any expression. The last <clause> may be an
335     "else clause," which has the form
336
337         (ELSE <expression>...)
338
339     A cond expression is evaluated by evaluating the <test>
340     expressions of successive <clause>s in order until one of
341     them evaluates to a true value. When a <test> evaluates to
342     a true value, then the remaining <expression>s in its
343     <clause> are evaluated in order, and the result of the last
344     <expression> in the <clause> is returned as the result of
345     the entire cond expression. If the selected <clause>
346     contains only the <test> and no <expression>s, then the
347     value of the <test> is returned as the result. If all
348     <test>s evaluate to false values, and there is no else
349     clause, then the result of the conditional expression is
350     unspecified; if there is an else clause, then its
351     <expression>s are evaluated, and the value of the last one
352     is returned.
353
354 (AND <test>...)
355
356     The <test> expressions are evaluated from left to right, and
357     the value of the first expression that evaluates to a false
358     value is returned. Any remaining expressions are not
359     evaluated. If all the expressions evaluate to true values,
360     the value of the last expression is returned. If there are
361     no expressions then #t is returned.
362
363 (OR <test>...)
364
365     The <test> expressions are evaluated from left to right, and
366     the value of the first expression that evaluates to a true
367     value is returned. Any remaining expressions are not
368     evaluated. If all expressions evaluate to false values, the
369     value of the last expression is returned. If there are no
370     expressions then #f is returned.
371
372
373
374 GLOBAL VARIABLES
375 ================
376
377 *ERROR-HANDLER*
378
379     Bound to a function to handle errors. The function
380     should take four arguments:
381       * program counter that points after the fetched bytecode;
382       * the function where the error occured;
383       * the environment at the time of the error;
384       * the stack at the time of the error.
385     It shouldn't return, i.e. it must call (exit) or (reset)
386
387 *UNBOUND-HANDLER*
388
389     Bound to a function to handle unbound symbol errors.
390     The function should take two arguments:
391       * the symbol that is unbound;
392       * a continuation to call after correcting the error.
393
394 *LOAD-PATH-LIST*
395
396     List with pathes to search for file in LOAD function.
397     LOAD will look at the path exactly given and then will
398     try all pathes from this list.
399     Each path is string, and you can use "%VAR-NAME%" in
400     string to substitute symbol value in it.
401
402 *LOAD-EXT-LIST*
403
404     List of file extensions (with dots) that will be tried
405     by LOAD in attempts to find the file.
406
407 *LOAD-SHOW-MESSAGES?*
408
409     set this to true to see messages from LOAD.
410
411 *REQUIRE-VERBOSE*
412
413     set this to true to see messages from REQUIRE.
414
415 *REQUIRE-PATH-LIST*
416
417     List with pathes to search for file in REQUIRE function.
418     REQUIRE will look at the path exactly given and then will
419     try all pathes from this list.
420     Each path is string, and you can use "%VAR-NAME%" in
421     string to substitute symbol value in it.
422
423 *REQUIRE-LOADED-LIB-LIST*
424
425     List of libraries already loaded.
426
427 *STANDARD-INPUT*
428
429     Bound to the standard input port.
430
431 *STANDARD-OUTPUT*
432
433     Bound to the standard output port.
434
435 *ERROR-OUTPUT*
436
437     Bound to the error output port.
438
439 *FIXNUM-FORMAT*
440
441     A printf style format string for printing fixed point numbers.
442
443 *FLONUM-FORMAT*
444
445     A printf style format string for printing floating point numbers.
446
447 *PRINT-CASE*
448
449     Bound to a symbol that controls the case in which symbols are printed.
450     Can be set to UPCASE or DOWNCASE.
451
452 *OBARRAY*
453
454     Vector of lists. All symbols known to the system.
455     Do not modify it, it's a kind of hash table!
456
457
458 BINDING FORMS
459 =============
460
461 (LET [<name>] <bindings> <body>)
462
463     <Bindings> should have the form
464
465         ([<variable> <init>]...)
466
467     where each <init> is an expression, and <body> should be a
468     sequence of one or more expressions. The <init>s are
469     evaluated in the current envirnoment, the <variable>s are
470     bound to fresh locations holding the results, the <body> is
471     evaluated in the extended environment, and the value of the
472     last expression of <body> is returned. Each binding of a
473     <variable> has <body> as its region.
474
475     If a name is supplied, a procedure that takes the bound
476     variables as its arguments and has the body of the LET as
477     its body is bound to that name.
478
479 (LET* <bindings> <body>)
480
481     Same as LET except that the bindings are done sequentially
482     from left to right and the bindings to the left are visible
483     while evaluating the initialization expressions for each
484     variable.
485
486 (LETREC <bindings> <body>)
487
488     <Bindings> should have the form
489
490         ([<variable> <init>]...)
491
492     and <body> should be a sequence of one or more expressions.
493     The <variable>s are bound to fresh locations holding
494     undefined values; the <init>s are evaluated in the resulting
495     environment; each <variable> is assigned to the result of
496     the corresponding <init>; the <body> is evaluated in the
497     resulting environment; and the value of the last expression
498     in <body> is returned. Each binding of a <variable> has the
499     entire letrec expression as its region, making it possible
500     to define mutually recursive procedures. One restriction of
501     letrec is very important: it must be possible to evaluate
502     each <init> without referring to the value of any
503     <variable>. If this restriction is violated, then the
504     effect is undefined, and an error may be signalled during
505     evaluation of the <init>s. The restriction is necessary
506     because Scheme passes arguments by value rather than by
507     name. In the most common uses of letrec, all the <init>s
508     are lambda expressions and the restriction is satisfied
509     automatically.
510
511
512
513 SEQUENCING
514 ==========
515
516 (BEGIN <expression>...)
517
518     The <expression>s are evaluated sequentially from left
519     to right, and the value of the last <expression> is
520     returned. This expression type is used to sequence side
521     effects such as input and output.
522
523
524
525 DELAYED EVALUATION
526
527 (CONS-STREAM expr1 expr2)
528
529     Create a cons stream whose head is expr1 (which is
530     evaluated immediately) and whose tail is expr2 (whose
531     evaluation is delayed until TAIL is called). To use
532     CONS-STREAM, enter the following access procedures:
533
534         (define head car)
535         (define (tail stream) (force (cdr stream)))
536
537 (DELAY <expression>)
538
539     Evaluating this expression creates a "promise" to
540     evaluate <expression> at a later time.
541
542 (FORCE promise)
543
544     Applying FORCE to a promise generated by DELAY requests
545     that the promise produce the value of the expression
546     passed to DELAY. The first time a promise is FORCEed,
547     the DELAY expression is evaluated and the value stored.
548     On subsequent calls to FORCE with the same promise, the
549     saved value is returned.
550
551
552
553 ITERATION
554 =========
555
556 (WHILE <test> <expression>...)
557
558     While is an iteration construct. Each iteration begins
559     by evaluating <test>; if the result is false, then the
560     loop terminates and the value of <test> is returned as
561     the value of the while expression. If <test> evaluates
562     to a true value, then the <expression>s are evaluated in
563     order for effect and the next iteration begins.
564
565
566
567 DEFINITIONS
568 ===========
569
570 (DEFINE <variable> <expression>)
571
572     Define a variable and give it an initial value.
573     The result is <variable> symbol.
574
575 (DEFINE (<variable> <formals>) <body>)
576
577     Define a procedure.
578     The result is <variable> symbol.
579
580 (DEFINE-MACRO (<name> <formals>) <body>)
581
582     Defines a macro with the specified name.
583     The result is UNDEFINED.
584
585
586
587 LIST FUNCTIONS
588 ==============
589
590 (CONS expr1 expr2)
591
592     Create a new pair whose car is expr1 and whose cdr is
593     expr2.
594
595 (CAR pair)
596
597     Extract the car of a pair.
598
599 (CDR pair)
600
601     Extract the cdr of a pair.
602
603 (CxxR pair)
604 (CxxxR pair)
605 (CxxxxR pair)
606
607     These functions are short for combinations of CAR and
608     CDR. Each 'x' is stands for either 'A' or 'D'. An 'A'
609     stands for the CAR function and a 'D' stands for the CDR
610     function. For instance, (CADR x) is the same as (CAR
611     (CDR x)).
612
613 (LIST expr...)
614
615     Create a list whose elements are the arguments to the
616     function. This function can take an arbitrary number of
617     arguments. Passing no arguments results in the empty
618     list.
619
620 (LIST* expr...)
621
622     Create a list whose elements are the arguments to the
623     function except that the last argument is used as the
624     tail of the list. This means that the call (LIST* 1 2
625     3) produce the result (1 2 . 3).
626
627 (APPEND list...)
628
629     Append lists to form a single list. This function takes
630     an arbitrary number of arguments. Passing no arguments
631     results in the empty list.
632
633 (REVERSE list)
634
635     Create a list whose elements are the same as the
636     argument except in reverse order.
637
638 (LAST-PAIR list)
639
640     Return the last pair in a list.
641
642 (LENGTH list)
643
644     Compute the length of a list.
645
646 (MEMBER expr list)
647 (MEMV expr list)
648 (MEMQ expr list)
649
650     Find an element in a list. Each of these functions
651     searches the list looking for an element that matches
652     expr. If a matching element is found, the remainder of
653     the list starting with that element is returned. If no
654     matching element is found, the empty list is returned.
655     The functions differ in the test used to determine if an
656     element matches expr. The MEMBER function uses EQUAL?,
657     the MEMV function uses EQV? and the MEMQ function uses
658     EQ?.
659
660 (ASSOC expr alist)
661 (ASSV expr alist)
662 (ASSQ expr alist)
663
664     Find an entry in an association list. An association
665     list is a list of pairs. The car of each pair is the
666     key and the cdr is the value. These functions search an
667     association list for a pair whose key matches expr. If
668     a matching pair is found, it is returned. Otherwise,
669     the empty list is returned. The functions differ in the
670     test used to determine if a key matches expr. The ASSOC
671     function uses EQUAL?, the ASSV function uses EQV? and
672     the ASSQ function uses EQ?.
673
674 (LIST-REF list n)
675
676     Return the nth element of a list (zero based).
677
678 (LIST-TAIL list n)
679
680     Return the sublist obtained by removing the first n
681     elements of list.
682
683
684
685 DESTRUCTIVE LIST FUNCTIONS
686 ==========================
687
688 (SET-CAR! pair expr)
689
690     Set the car of a pair to expr. The value returned by
691     this procedure is unspecified.
692
693 (SET-CDR! pair expr)
694
695     Set the cdr of a pair to expr. The value returned by
696     this procedure is unspecified.
697
698 (APPEND! list...)
699
700     Append lists destructively.
701
702 (REVERSE! list)
703
704     Reverses list 'in-place' (destructively).
705
706
707
708 SYMBOL FUNCTIONS
709 ================
710
711 (BOUND? sym)
712
713     Returns #t if a global value is bound to the symbol and
714     #f otherwise.
715
716 (SYMBOL-VALUE sym)
717
718     Get the global value of a symbol.
719
720 (SYMBOL-VALUE-SET! sym expr)
721
722     Set the global value of a symbol. The value returned by
723     this procedure is unspecified.
724
725 (SYMBOL-PLIST sym)
726
727     Get the property list associated with a symbol.
728
729 (SYMBOL-PLIST-SET! sym plist)
730
731     Set the property list associate with a symbol. The
732     value returned by this procedure is unspecified.
733
734 (GENSYM [sym|str|num])
735
736     Generate a new, uninterned symbol. The print name of
737     the symbol will consist of a prefix with a number
738     appended. The initial prefix is "_:G_:" and the initial
739     number is 1. If a symbol is specified as an argument,
740     the prefix is set to the print name of that symbol. If
741     a string is specified, the prefix is set to that string.
742     If a number is specified, the numeric suffix is set to
743     that number. After the symbol is generated, the number
744     is incremented so subsequent calls to GENSYM will
745     generate numbers in sequence.
746
747 (GET sym prop)
748
749     Get the value of a property of a symbol. The prop
750     argument is a symbol that is the property name. If a
751     property with that name exists on the symbols property
752     list, the value of the property is returned. Otherwise,
753     the empty list is returned.
754
755 (PUT sym prop expr)
756
757     Set the value of a property of a symbol. The prop
758     argument is a symbol that is the property name. The
759     property/value combination is added to the property list
760     of the symbol.
761
762
763
764 VECTOR FUNCTIONS
765 ================
766
767 (VECTOR expr...)
768
769     Create a vector whose elements are the arguments to the
770     function. This function can take an arbitrary number of
771     arguments. Passing no arguments results in a zero
772     length vector.
773
774 (MAKE-VECTOR len [init])
775
776     Make a vector of the specified length.
777     if 'init' is specified, fill the vector with this value.
778
779 (MAKE-BVECTOR len [init])
780
781     Make a byte vector of the specified length.
782     if 'init' is specified, fill the byte vector with this value.
783
784 (VECTOR-LENGTH vect)
785
786     Get the length of a vector or byte vector.
787
788 (VECTOR-REF vect n)
789
790     Return the nth element of a vector or byte vector (zero based).
791
792 (VECTOR-SET! vect n expr)
793
794     Set the nth element of a vector or byte vector (zero based).
795
796 (BVECTOR-RESIZE! vect newsz)
797
798     Resize byte vector (old contents are preserved, new contents
799     are zero-filled).
800
801
802
803 ARRAY FUNCTIONS
804 ===============
805
806 (MAKE-ARRAY d1 d2...)
807
808     Make an array (vector of vectors) with the specified
809     dimensions. At least one dimension must be specified.
810
811 (ARRAY-REF array s1 s2...)
812
813     Get an array element. The sn arguments are integer
814     subscripts (zero based).
815
816 (ARRAY-SET! array s1 s2... expr)
817
818     Set an array element. The sn arguments are integer
819     subscripts (zero based).
820
821
822
823 CONVERSION FUNCTIONS
824 ====================
825
826 (SYMBOL->STRING sym)
827
828     Convert a symbol to a string. Returns the print name of
829     the symbol as a string.
830
831 (STRING->SYMBOL str)
832
833     Convert a string to a symbol. Returns a symbol with the
834     string as its print name. This can either be a new
835     symbol or an existing one with the same print name.
836
837 (VECTOR->LIST vect)
838
839     Convert a vector or byte vector to a list. Returns a list
840     of the elements of the vector.
841
842 (LIST->VECTOR list)
843
844     Convert a list to a vector. Returns a vector of the
845     elements of the list.
846
847 (LIST->BVECTOR list)
848
849     Convert a list to a byte vector. Returns a byte vector of
850     the elements of the list.
851
852 (STRING->LIST str)
853
854     Convert a string to a list. Returns a list of the
855     characters in the string.
856
857 (LIST->STRING list)
858
859     Convert a list of character to a string. Returns a
860     string whose characters are the elements of the list.
861
862 (CHAR->INTEGER char)
863
864     Convert a character to an integer. Returns the ASCII
865     code of the character as an integer.
866
867 (INTEGER->CHAR n)
868
869     Convert an integer ASCII code to a character. Returns
870     the character whose ASCII code is the integer.
871
872
873
874 TYPE PREDICATE FUNCTIONS
875 ========================
876
877 (NOT expr)
878
879     Returns #t if the expression is #f and #t otherwise.
880
881 (NULL? expr)
882
883     Returns #t if the expression is the empty list and #f
884     otherwise.
885
886 (ATOM? expr)
887
888     Returns #f if the expression is a pair and #t otherwise.
889
890 (LIST? expr)
891
892     Returns #t if the expression is either a valid list or empty
893     list.
894     WARNING: do not feed (LIST?) with circular lists!
895
896 (NUMBER? expr)
897
898     Returns #t if the expression is a number and #f
899     otherwise.
900
901 (BOOLEAN? expr)
902
903     Returns #t if the expression is either #t or #f and #f
904     otherwise.
905
906 (PAIR? expr)
907
908     Returns #t if the expression is a pair and #f otherwise.
909
910 (SYMBOL? expr)
911
912     Returns #t if the expression is a symbol and #f
913     otherwise.
914
915 (COMPLEX? expr)
916
917     Returns #t if the expression is a complex number and #f
918     otherwise.
919     Note: Complex numbers are not yet supported by XScheme.
920
921 (REAL? expr)
922
923     Returns #t if the expression is a real number and #f
924     otherwise.
925
926 (RATIONAL? expr)
927
928     Returns #t if the expression is a rational number and #f
929     otherwise.
930     Note: Rational numbers are not yet supported by
931     XScheme.
932
933 (INTEGER? expr)
934
935     Returns #t if the expression is an integer and #f
936     otherwise.
937
938 (CHAR? expr)
939
940     Returns #t if the expression is a character and #f
941     otherwise.
942
943 (STRING? expr)
944
945     Returns # if the expression is a string and #f
946     otherwise.
947
948 (VECTOR? expr)
949
950     Returns #t if the expression is a vector and #f
951     otherwise.
952
953 (BVECTOR? expr)
954
955     Returns #t if the expression is a byte vector and #f
956     otherwise.
957
958 (PROCEDURE? expr)
959
960     Returns #t if the expression is a procedure (closure)
961     and #f otherwise.
962
963 (PORT? expr)
964
965     Returns #t if the expression is a port and #f otherwise.
966
967 (INPUT-PORT? expr)
968
969     Returns #t if the expression is an input port and #f
970     otherwise.
971
972 (OUTPUT-PORT? expr)
973
974     Returns #t if the expression is an output port and #f
975     otherwise.
976
977 (OBJECT? expr)
978
979     Returns #t if the expression is an object and #f
980     otherwise.
981
982 (EOF-OBJECT? expr)
983
984     Returns #t if the expression is the object returned by
985     READ upon detecting an end of file condition and #f
986     otherwise.
987
988 (DEFAULT-OBJECT? expr)
989
990     Returns #t if the expression is the object passed as the
991     default value of an optional parameter to a procedure
992     when that parameter is omitted from a call and #f
993     otherwise.
994
995 (ENVIRONMENT? x)
996
997     Returns #t if the expression is an environment and #f
998     otherwise.
999
1000
1001
1002 EQUALITY PREDICATES
1003 ===================
1004
1005 (EQUAL? expr1 expr2)
1006
1007     Recursively compares two objects to determine if their
1008     components are the same and returns #t if they are the
1009     same and #f otherwise.
1010
1011 (EQV? expr1 expr2)
1012
1013     Compares two objects to determine if they are the same
1014     object. Returns #t if they are the same and #f
1015     otherwise. This function does not compare the elements
1016     of lists, vectors or strings but will compare all types
1017     of numbers.
1018
1019 (EQ? expr1 expr2)
1020
1021     Compares two objects to determine if they are the same
1022     object. Returns #t if they are the same and #f
1023     otherwise. This function performs a low level address
1024     compare on two objects and may return #f for objects
1025     that appear on the surface to be the same. This is
1026     because the objects are not stored uniquely in memory.
1027     For instance, numbers may appear to be equal, but EQ?
1028     will return #f when comparing them if they are stored at
1029     different addresses. The advantage of this function is
1030     that it is faster than the others. Symbols are
1031     guaranteed to compare correctly, so EQ? can safely be
1032     used to compare them.
1033
1034
1035
1036 ARITHMETIC FUNCTIONS
1037 ====================
1038
1039 (ZERO? n)
1040
1041     Returns #t if the number is zero and #f otherwise.
1042
1043 (POSITIVE? n)
1044
1045     Returns #t if the number is positive and #f otherwise.
1046
1047 (NEGATIVE? n)
1048
1049     Returns #t if the number is negative and #f otherwise.
1050
1051 (ODD? n)
1052
1053     Returns #t if the integer is odd and #f otherwise.
1054
1055 (EVEN? n)
1056
1057     Returns #t if the integer is even and #f otherwise.
1058
1059 (EXACT? n)
1060
1061     Returns #t if the number is exact and #f otherwise.
1062     Note: This function always returns #f in XScheme since
1063     exact numbers are not yet supported.
1064
1065 (INEXACT? n)
1066
1067     Returns #t if the number is inexact and #f otherwise.
1068     Note: This function always returns #t in XScheme since
1069     exact numbers are not yet supported.
1070
1071 (TRUNCATE n)
1072 (TRUNC n)
1073
1074     Truncates a number to an integer and returns the
1075     resulting value.
1076
1077 (FLOOR n)
1078
1079     Returns the largest integer not larger than n.
1080
1081 (CEILING n)
1082 (CEIL n)
1083
1084     Returns the smallest integer not smaller than n.
1085
1086 (ROUND n)
1087
1088     Returns the closest integer to n, rounding to even when
1089     n is halfway between two integers.
1090
1091 (1+ n)
1092 (ADD1 n)
1093
1094     Returns the result of adding one to the number.
1095
1096 (-1+ n)
1097 (SUB1 n)
1098
1099     Returns the result of subtracting one from the number.
1100
1101 (ABS n)
1102
1103     Returns the absolute value of the number.
1104
1105 (GCD n1 n2)
1106
1107     Returns the greatest common divisor of the two numbers.
1108
1109 (RAND-SEED n)
1110
1111     Returns current seed.
1112
1113 (RAND-SEED-SET! n)
1114
1115     Sets random seed. Returns old seed.
1116
1117 (RANDOM n)
1118
1119     Returns a random number between zero and n-1 (n must be
1120     an integer).
1121
1122 (+ n1 n2...)
1123
1124     Returns the sum of the numbers.
1125
1126 (- n)
1127
1128     Negates the number and returns the resulting value.
1129
1130 (- n1 n2...)
1131
1132     Subtracts each remaining number from n1 and returns the
1133     resulting value.
1134
1135 (* n1 n2...)
1136
1137     Multiples the numbers and returns the resulting value.
1138
1139 (/ n)
1140
1141     Returns 1/n.
1142
1143 (/ n1 n2...)
1144
1145     Divides n1 by each of the remaining numbers and returns
1146     the resulting value.
1147
1148 (QUOTIENT n1 n2...)
1149
1150     Divides the integer n1 by each of the remaining numbers
1151     and returns the resulting integer quotient. This
1152     function does integer division.
1153
1154 (REMAINDER n1 n2)
1155
1156     Divides the integer n1 by the integer n2 and returns the
1157     remainder.
1158
1159 (MIN n1 n2...)
1160
1161     Returns the number with the minimum value.
1162
1163 (MAX n1 n2...)
1164
1165     Returns the number with the maximum value.
1166
1167 (SIN n)
1168
1169     Returns the sine of the number.
1170
1171 (COS n)
1172
1173     Returns the cosine of the number.
1174
1175 (TAN n)
1176
1177     Returns the tangent of the number.
1178
1179 (ASIN n)
1180
1181     Returns the arc-sine of the number.
1182
1183 (ACOS n)
1184
1185     Returns the arc-cosine of the number.
1186
1187 (ATAN x)
1188
1189     Returns the arc-tangent of x.
1190
1191 (ATAN y x)
1192
1193     Returns the arc-tangent of y/x.
1194
1195 (EXP n)
1196
1197     Returns e raised to the n.
1198
1199 (SQRT n)
1200
1201     Returns the square root of n.
1202
1203 (EXPT n1 n2)
1204
1205     Returns n1 raised to the n2 power.
1206
1207 (LOG n)
1208
1209     Returns the natural logarithm of n.
1210
1211
1212
1213 NUMERIC COMPARISON FUNCTIONS
1214 ============================
1215
1216 (< n1 n2...)
1217 (= n1 n2...)
1218 (> n1 n2...)
1219 (<= n1 n2...)
1220 (>= n1 n2...)
1221 (<> n1 n2...)
1222
1223     These functions compare numbers and return #t if the
1224     numbers match the predicate and #f otherwise. For
1225     instance, (< x y z) will return #t if x is less than y
1226     and y is less than z.
1227
1228
1229
1230 BITWISE LOGICAL FUNCTIONS
1231 =========================
1232
1233 (LOGAND n1 n2...)
1234 (& n1 n2...)
1235
1236     Returns the bitwise AND of the integer arguments.
1237
1238 (LOGIOR n1 n2...)
1239 (| n1 n2...)
1240
1241     Returns the bitwise inclusive OR of the integer
1242     arguments.
1243
1244 (LOGXOR n1 n2...)
1245 (^ n1 n2...)
1246
1247     Returns the bitwise exclusive OR of the integer
1248     arguments.
1249
1250 (LOGNOT n)
1251 (~ n)
1252
1253     Returns the bitwise complement of n.
1254
1255 (BIT-FIELD fx1 fx2 fx3)
1256
1257     fx2 and fx3 must be non-negative fixnums. moreover,
1258     fx2 must be less than or equal to fx3. The BIT-FIELD
1259     procedure returns the number represented by the bits
1260     at the positions from fx2 (inclusive) to fx3 (exclusive).
1261
1262 (<< <n> <cnt>)
1263 (>> <n> <cnt>)
1264
1265     Bit-shifts for integers.
1266
1267
1268
1269 STRING FUNCTIONS
1270 ================
1271
1272 (MAKE-STRING len [filler])
1273
1274     Create new string with 'len' 'filler's. 'filler' can be char,
1275     integer or string.
1276
1277 (STRING-LENGTH str)
1278
1279     Returns the length of the string.
1280
1281 (STRING-NULL? str)
1282 (STRING-EMPTY? str)
1283
1284     Returns #t if the string has a length of zero and #f
1285     otherwise.
1286
1287 (STRING-APPEND str1...)
1288
1289     Returns the result of appending the string arguments.
1290     If no arguments are supplied, it returns the null
1291     string.
1292     This function accepts both strings and characters.
1293
1294 (CHAR-CODE-AT str n)
1295
1296     Returns the nth character in a string as fixnum.
1297     'n' can be negative which means "(-n)th character
1298     from the end of the string".
1299
1300 (STRING-REF str n)
1301
1302     Returns the nth character in a string.
1303     'n' can be negative which means "(-n)th character
1304     from the end of the string".
1305
1306 (STRING-SET! str n c)
1307
1308     Sets the nth character of the string to c. 'c' can be
1309     char or fixnum.
1310     'n' can be negative which means "(-n)th character
1311     from the end of the string".
1312
1313 (SUBSTRING str start end)
1314 (SUBSTR str start end)
1315
1316     Returns the substring of str starting at start and
1317     ending at end (integers). The range is inclusive of
1318     start and exclusive of end.
1319     'end' can be omited. Both 'start' and 'end' can be
1320     negative: (SUBSTRING "12345" -3 -2) returns "34".
1321     Note that 'end' is included, as opposed to "normal"
1322     SUBSTRING. This is done to allow things like
1323     (SUBSTRING str -3 -1) return the same as
1324     (SUBSTRING str -3)
1325
1326 (STRING-FIND where what #!OPTIONAL (stpos 0) (endpos 0))
1327 (STRING-FIND-CI where what #!OPTIONAL (stpos 0) (endpos 0))
1328 (STRING-RFIND where what #!OPTIONAL (stpos 0) (endpos 0))
1329 (STRING-RFIND-CI where what #!OPTIONAL (stpos 0) (endpos 0))
1330
1331     Find 'what' in 'where' starting from 'stpos' ending at 'endpos'-1.
1332     Return position from the start of the string (not from 'stpos') or
1333     #f.
1334
1335 (STRCHR str chr #!OPTIONAL (stpos 0) (endpos 0))
1336 (STRCHR-CI str chr #!OPTIONAL (stpos 0) (endpos 0))
1337 (STRRCHR str chr #!OPTIONAL (stpos 0) (endpos 0))
1338 (STRRCHR-CI str chr #!OPTIONAL (stpos 0) (endpos 0))
1339
1340     Find character in string. Return position or #f.
1341     'chr' can be char, integer or string/symbol (first char will be used).
1342
1343
1344
1345 STRING COMPARISON FUNCTIONS
1346 ===========================
1347
1348 (STRING<? str1 str2)
1349 (STRING=? str1 str2)
1350 (STRING<>? str1 str2)
1351 (STRING>? str1 str2)
1352 (STRING<=? str1 str2)
1353 (STRING>=? str1 str2)
1354
1355     These functions compare strings and return #t if the
1356     strings match the predicate and #f otherwise. For
1357     instance, (STRING< x y) will return #t if x is less than
1358     y. Case is significant. #\A does not match #\a.
1359
1360 (STRING-CI<? str1 str2)
1361 (STRING-CI=? str1 str2)
1362 (STRING-CI<>? str1 str2)
1363 (STRING-CI>? str1 str2)
1364 (STRING-CI<=? str1 str2)
1365 (STRING-CI>=? str1 str2)
1366
1367     These functions compare strings and return #t if the
1368     strings match the predicate and #f otherwise. For
1369     instance, (STRING-CI< x y) will return #t if x is less
1370     than y. Case is not significant. #\A matches #\a.
1371
1372
1373
1374 CHARACTER COMPARISON FUNCTIONS
1375 ==============================
1376
1377 (CHAR<? ch1 ch2)
1378 (CHAR=? ch1 ch2)
1379 (CHAR<>? ch1 ch2)
1380 (CHAR>? ch1 ch2)
1381 (CHAR<=? ch1 ch2)
1382 (CHAR>=? ch1 ch2)
1383
1384     These functions compare characters and return #t if the
1385     characters match the predicate and #f otherwise. For
1386     instance, (CHAR< x y) will return #t if x is less than
1387     y. Case is significant. #\A does not match #\a.
1388
1389 (CHAR-CI<? ch1 ch2)
1390 (CHAR-CI=? ch1 ch2)
1391 (CHAR-CI<>? ch1 ch2)
1392 (CHAR-CI>? ch1 ch2)
1393 (CHAR-CI<=? ch1 ch2)
1394 (CHAR-CI>=? ch1 ch2)
1395
1396     These functions compare characters and return #t if the
1397     characters match the predicate and #f otherwise. For
1398     instance, (CHAR-CI< x y) will return #t if x is less
1399     than y. Case is not significant. #\A matchs #\a.
1400
1401 (CHAR-UPCASE ch)
1402
1403     Return uppercased char.
1404
1405 (CHAR-LOCASE ch)
1406
1407     Return lowercased char.
1408
1409
1410
1411 INPUT/OUTPUT FUNCTIONS
1412 ======================
1413
1414 (READ [port])
1415
1416     Reads an expression from the specified port. If no port
1417     is specified, the current input port is used. Returns
1418     the expression read or an object that satisfies the
1419     eof-object? predicate if it reaches the end of file
1420     on the port.
1421
1422 (READ-CHAR [port])
1423
1424     Reads a character from the specified port. If no port
1425     is specified, the current input port is used. Returns
1426     the character read or an object that satisfies the
1427     eof-object? predicate if it reaches the end of file
1428     on the port.
1429
1430 (UNREAD-CHAR [port])
1431
1432     Unreads a character to the specified port. If no port
1433     is specified, the current input port is used. Returns
1434     the #t or #f.
1435
1436 (PEEK-CHAR [port])
1437
1438     Peeks a character from the specified port. If no port
1439     is specified, the current input port is used. Returns
1440     the character read or an object that satisfies the
1441     eof-object? predicate if it reaches the end of file
1442     on the port.
1443
1444 (READ-BYTE [port])
1445
1446     Reads a byte from the specified port. If no port is
1447     specified, the current input port is used. Returns the
1448     byte read or an object that satisfies the eof-object?
1449     predicate if it reaches the end of file on the port.
1450
1451 (READ-BVEC bvec ofs len [port])
1452
1453     Reads a bytes from the specified port. If no port is
1454     specified, the current input port is used. Returns the
1455     number of bytes read or an object that satisfies the
1456     eof-object? predicate if it reaches the end of file on
1457     the port.
1458
1459 (WRITE expr [port])
1460
1461     Writes an expression to the specified port. If no port
1462     is specified, the current output port is used. The
1463     expression is written such that the READ function can
1464     read it back. This means that strings will be enclosed
1465     in quotes and characters will be printed with #
1466     notation.
1467
1468 (WRITE-CHAR ch [port])
1469
1470     Writes a character to the specified port. If no port is
1471     specified, the current output port is used.
1472
1473 (WRITE-BYTE ch [port])
1474
1475     Writes a byte to the specified port. If no port is
1476     specified, the current output port is used.
1477
1478 (WRITE-BVEC bvec ofs len [port])
1479
1480     Writes a bytes to the specified port. If no port is
1481     specified, the current output port is used.
1482
1483 (DISPLAY expr [port])
1484
1485     Writes an expression to the specified port. If no port
1486     is specified, the current output port is used. The
1487     expression is written without any quoting characters.
1488     No quotes will appear around strings and characters are
1489     written without the # notation.
1490
1491 (NEWLINE [port])
1492
1493     Starts a new line on the specified port. If no port is
1494     specified, the current output port is used.
1495
1496 (FORMAT [port] str #!rest args)
1497
1498     If port is #f, FORMAT collects its output into a string and returns
1499     the string. If port is #t, FORMAT sends its output to the current
1500     output port. Otherwise, port should be an output port.
1501
1502     ~S, ~W print argument as if with WRITE
1503
1504     ~A, ~D print argument as if with DISPLAY
1505
1506     ~X print argument as a hexadecimal number
1507
1508     ~Q print argument with "shell quotation", so it can be safely passed
1509        to shell.
1510
1511     ~% print as if with NEWLINE
1512
1513     You can add C-like width specifier (with '@' instead of '-' for
1514     padding with spaces -- or zeroes if number starts with 0-- at the right).
1515
1516
1517 OUTPUT CONTROL FUNCTIONS
1518 ========================
1519
1520 (PRINT-BREADTH [n])
1521
1522     Controls the maximum number of elements of a list that
1523     will be printed. If n is an integer, the maximum number
1524     is set to n. If it is #f, the limit is set to infinity.
1525     This is the default. If n is omitted from the call, the
1526     current value is returned.
1527
1528 (PRINT-DEPTH [n])
1529
1530     Controls the maximum number of levels of a nested list
1531     that will be printed. If n is an integer, the maximum
1532     number is set to n. If it is #f, the limit is set to
1533     infinity. This is the default. If n is omitted from
1534     the call, the current value is returned.
1535
1536
1537
1538 FILE I/O FUNCTIONS
1539 ==================
1540
1541 (OPEN-STRING-PORT strinit modestr)
1542
1543     Open string port for input and/or output. 'strinit' is the
1544     inital value (note that even output port will not mutate
1545     'strinit').
1546
1547 (OPEN-DYN-PORT modestr)
1548     Open string port for input and/or output.
1549
1550 (DYN-PORT->STRING port)
1551
1552     Return current value of the output string/dynamic port.
1553
1554 (OPEN-FILE-PORT str modestr)
1555
1556     Opens the file named by the string and returns an input
1557     port. 'modestr' is the same as in fopen().
1558
1559 (PORT-SIZE port)
1560
1561     Returns size of the port or #f if size can't be determined.
1562
1563 (PORT-LINE-POS port)
1564
1565     Return pair (line . pos), where 'line' is the current line and
1566     'pos' is the current position in line.
1567
1568 (PORT-POS port)
1569
1570     Returns the current file position as an offset in bytes
1571     from the beginning of the file or #f.
1572
1573 (PORT-POS-SET! port offset [whence])
1574
1575     Sets the current file position as an offset in bytes
1576     from the beginning of the file (when whence equals 0),
1577     the current file position (when whence equals 1) or the
1578     end of the file (when whence equals 2). Returns #t or #f.
1579     'whence' can be number:
1580       1: SEEK_CUR
1581       -1, 2: SEEK_END
1582       other: SEEK_SET
1583     or string/symbol:
1584       cur: SEEK_CUR
1585       end: SEEK_END
1586       other: SEEK_SET
1587
1588 (FLUSH-PORT [port])
1589
1590     Flush specified port. If there was no port specified, flush
1591     standard output port.
1592
1593 (CLOSE-PORT port)
1594
1595     Closes any port.
1596
1597 (CURRENT-INPUT-PORT)
1598
1599     Returns the current input port.
1600
1601 (CURRENT-OUTPUT-PORT)
1602
1603     Returns the current output port.
1604
1605 (CURRENT-ERROR-PORT)
1606
1607     Returns the current error output port.
1608
1609
1610
1611 CONTROL FEATURES
1612 ================
1613
1614 (EVAL expr [env])
1615
1616     Evaluate the expression in the global (or given) environment
1617     and return its value.
1618
1619 (APPLY proc args)
1620
1621     Apply the procedure to the list of arguments and return
1622     the result.
1623
1624 (MAP proc list...)
1625
1626     Apply the procedure to argument lists formed by taking
1627     corresponding elements from each list. Form a list from
1628     the resulting values and return that list as the result
1629     of the MAP call.
1630
1631 (FOR-EACH fun list...)
1632
1633     Apply the procedure to argument lists formed by taking
1634     corresponding elements from each list. The values
1635     returned by the procedure applications are discarded.
1636     The value returned by FOR-EACH is unspecified.
1637
1638 (CALL-WITH-CURRENT-CONTINUATION proc)
1639 (CALL/CC proc)
1640
1641     Form an "escape procedure" from the current continuation
1642     and pass it as an argument to proc. Calling the escape
1643     procedure with a single argument will cause that
1644     argument to be passed to the continuation that was in
1645     effect when the CALL-WITH-CURRENT-CONTINUATION procedure
1646     was called.
1647
1648 (DYNAMIC-WIND <thunk1> <thunk2> <thunk3>)
1649
1650     The arguments <thunk1>, <thunk2>, and <thunk3> must all be
1651     procedures of no arguments (thunks).
1652
1653     DYNAMIC-WIND calls <thunk1>, <thunk2>, and then <thunk3>.
1654     The value returned by <thunk2> is returned as the result of
1655     DYNAMIC-WIND. <thunk3> is also called just before control leaves
1656     the dynamic context of <thunk2> by calling a continuation created
1657     outside that context. Furthermore, <thunk1> is called before
1658     reentering the dynamic context of <thunk2> by calling a continuation
1659     created inside that context. (Control is inside the context of
1660     <thunk2> if <thunk2> is on the current return stack).
1661
1662
1663 ENVIRONMENT FUNCTIONS
1664 =====================
1665
1666 (THE-ENVIRONMENT)
1667
1668     Returns the current environment.
1669
1670 (PROCEDURE-ENVIRONMENT proc)
1671
1672     Returns the environment from a procedure closure.
1673
1674 (ENVIRONMENT-BINDINGS env)
1675
1676     Returns an association list corresponding to the top
1677     most frame of the specified environment.
1678
1679 (ENVIRONMENT-PARENT env)
1680
1681     Returns the parent environment of the specified
1682     environment.
1683
1684
1685
1686 UTILITY FUNCTIONS
1687 =================
1688
1689 (REQUIRE sym sym...)
1690
1691     Load library. Library is an ordinary Scheme source file.
1692     Each library will be loaded only once.
1693
1694     Sample: (require strlib setex)
1695
1696 (LOAD str-or-port)
1697
1698     Read and evaluate each expression from the specified
1699     file or port.
1700
1701 (LOAD-NOISILY str)
1702
1703     Read and evaluate each expression from the specified
1704     file or port and print the results to the current output
1705     port.
1706
1707 (LOAD-STR str)
1708     Read and evaluate each expression from the specified
1709     string.
1710
1711 (LOAD-STR-NOISILY str)
1712
1713     Read and evaluate each expression from the specified
1714     string and print the results to the current output port.
1715
1716 (%EVAL-WHOLE-STRING str)
1717
1718     Evaluate the expressions from the specified string in the
1719     global environment. Return result of the last expression.
1720
1721 (EXIT)
1722
1723     Exits from XScheme back to the operating system.
1724
1725 (GC [ni vi])
1726
1727     Invokes the garbage collector and returns information on
1728     memory usage. If ni and vi are specified, they must be
1729     integers. Node and vector space are expanded by those
1730     amounts respectively and no garbage collection is
1731     triggered. GC returns a pair: the car is the total number
1732     of bytes allocated to the heap and the cdr is the number
1733     of calls to the garbage collector.
1734
1735 (RESET)
1736
1737     Returns to the top level read/eval/print loop.
1738
1739
1740
1741 SYSTEM FUNCTIONS
1742 ================
1743
1744 (%CAR pair)
1745 (%CDR pair)
1746 (%SET-CAR! pair expr)
1747 (%SET-CDR! pair expr)
1748 (%VECTOR-LENGTH vect)
1749 (%VECTOR-REF vect n)
1750 (%VECTOR-SET! vect n expr)
1751 (%Cx+R pair)
1752 (%STRING-REF str n)
1753 (%STRING-SET! str n c)
1754
1755     These functions do the same as their counterparts
1756     without the leading '%' character. The difference is
1757     that they don't check the type of their first argument.
1758     This makes it possible to examine data structures that
1759     have the same internal representation as pairs and
1760     vectors. It is *very* dangerous to modify objects using
1761     these functions and there is no guarantee that future
1762     releases of XScheme will represent objects in the same
1763     way that the current version does.
1764
1765
1766
1767 OTHER FUNCTIONS
1768 ===============
1769
1770 (DECOMPILE <function|method> [port])
1771
1772     Decompile function -- show disassembly of internal VM
1773     bytecodes.
1774
1775 (DECOMPILE-ONE <function|method> pc [port])
1776
1777     Decompile one bytecode. Return next PC or #f.
1778
1779 (%MAKE-CODE size)
1780
1781     Make new 'code' object. 'size' is the number of cells reserved
1782     for literals.
1783
1784 (%MAKE-CLOSURE code #!optional env)
1785
1786     Make new 'closure' object. Can be used to make new function.
1787
1788 (PARAMETERIZE <bindings> <body>)
1789
1790     <Bindings> should have the form
1791
1792         ([<variable> <init>]...)
1793
1794     where each <init> is an expression, and <body> should be a
1795     sequence of one or more expressions.
1796     The <init>s are evaluated in the current envirnoment, the
1797     <variable>s are set to fresh locations holding the results,
1798     the <body> is evaluated in the extended environment, the
1799     value of the last expression of <body> is returned and
1800     <variable>s will be restored to their previous values.
1801
1802 (CASE <key> <case clause1> <case clause2>...)
1803
1804     <key> must be an expression. Each <case clause> must have
1805     one of the following forms:
1806
1807         ((<datum1> ...) <expression1> <expression2> ...)
1808         (else <expression1> <expression2> ...)
1809
1810     The second form, which specifies an else clause, may only
1811     appear as the last <case clause>. Each <datum> is an external
1812     representation of some object. The data represented by the
1813     <datum>s need not be distinct.
1814     A case expression is evaluated as follows. <key> is evaluated
1815     and its result is compared using eqv? against the data
1816     represented by the <datum>s of each <case clause> in turn,
1817     proceeding in order from left to right through the set of clauses.
1818     If the result of evaluating <key> is equivalent to a datum of a
1819     <case clause>, the corresponding <expression>s are evaluated from
1820     left to right and the results of the last expression in the
1821     <case clause> are returned as the results of the case expression.
1822     Otherwise, the comparison process continues. If the result of
1823     evaluating <key> is different from every datum in each set, then
1824     if there is an else clause its expressions are evaluated and the
1825     results of the last are the results of the case expression;
1826     otherwise the case expression returns unspecified values.
1827
1828
1829 (DO ((id init-expr [step-expr-maybe]) ...)
1830     (stop?-expr finish-expr ...)
1831       expr ...+)
1832
1833     Iteratively evaluates the exprs for as long as stop?-expr returns #f.
1834     To initialize the loop, the init-exprs are evaluated in order and
1835     bound to the corresponding ids. The ids are bound in all expressions
1836     within the form other than the init-exprs.
1837     After the ids are bound, then stop?-expr is evaluated. If it produces
1838     #f, each expr is evaluated for its side-effect. The ids are then
1839     effectively updated with the values of the step-exprs, where the
1840     default step-expr for id is just id; more precisely, iteration
1841     continues with fresh locations for the ids that are initialized with
1842     the values of the corresponding step-exprs.
1843     When stop?-expr produces a true value, then the finish-exprs are
1844     evaluated in order, and the last one is evaluated in tail position
1845     to produce the overall value for the do form.
1846     If no finish-expr is provided, the value of the do form is undefined.
1847
1848 (WHEN test-expr expr ...)
1849
1850     Evaluates the text-expr. If the result is #f, then the result of the
1851     WHEN expression is #f. Otherwise, the exprs are evaluated, and the last
1852     expr is in tail position with respect to the when form.
1853
1854 (UNLESS test-expr expr ...)
1855
1856     Equivalent to (when (not test-expr) expr ...).
1857
1858
1859
1860 OS FUNCTIONS
1861 ============
1862
1863 (SYSTEM cmd)
1864
1865     Execute OS command. Return error code or #f on success.
1866
1867 (UNIX-TIME)
1868
1869     Return current unix time.
1870
1871 (UNLINK fname)
1872
1873     Delete file. Return #t or #f.
1874
1875 (GETENV vname)
1876
1877     Return environment var or #f.
1878
1879 (CURRENT-DIR)
1880
1881     Return current directory.
1882
1883 (CURRENT-DIR-SET! dir)
1884
1885     Set current directory. Return #t or #f.
1886
1887
1888
1889 DLIB FUNCTIONS
1890 ==============
1891
1892 (DLIB:LOAD libnamestr)
1893
1894     Load XScheme extension library. Return #t or #f.
1895
1896
1897
1898 TRE REGULAR EXPRESSION FUNCTIONS
1899 ================================
1900
1901 (MAKE-TREGEXP restr . options)
1902
1903     Create new regular expression object. The function returns
1904     either regexp object or string with error message.
1905     'options' can be either symbol(s), char(s) or string(s).
1906     Chars and strings are case-insensitive.
1907     options are:
1908       'ignorecase, #\i
1909         ingonre case
1910       'basic #\b
1911         use POSIX basic RE synthax (default is extended)
1912       'multiline #\m
1913         treat '\n' as special symbol
1914       'ungreedy #\u
1915         'repeaters' are ungreedy (default is greedy)
1916       'no-submatch #\s
1917         do not return submatch positions
1918
1919 (TREGEXP-MATCH? re str . submatches? ignore-bol? ignore-eol?)
1920
1921     Match string. If 'submatches?' is #f or not specified,
1922     return #t or #f. else return either #f or vector. Each
1923     vector item is either #f or pair where car is the starting
1924     position of found submatch and cdr is the position just
1925     after the submatch. The first item is for the whole match.
1926
1927     if 'ignore-bol?' is not false, the match-beginning-of-line
1928     operator ^ does not match the empty string at the beginning
1929     of string. If 'multiline was used when compiling re, the empty
1930     string immediately after a newline character will still be matched.
1931
1932     if 'ignore-eol?' is not false, the match-end-of-line operator $
1933     does not match the empty string at the end of string. If 'multiline
1934     was used when compiling preg the empty string immediately before a
1935     newline character will still be matched.
1936
1937 (TREGEXP? re)
1938
1939     Return #t if 're' is a regexp object.
1940
1941 (<regexp-obj> str . submatches? ignore-bol? ignore-eol?)
1942
1943     The same as (TREGEXP-MATCH? <regexp-obj> ...).
1944
1945
1946
1947 VARIOUS LIBRARY FUNCTIONS
1948 =========================
1949
1950 Some of this functions will be autorequired from various libraries.
1951 If the user needs to manually (require) some library, documentation
1952 will say so.
1953
1954
1955 (ANY pred clist1 clist2...)
1956 (ANY? pred clist1 clist2...)
1957
1958     Applies the predicate across the lists, returning true if the
1959     predicate returns true on any application.
1960     If there are n list arguments clist1 ... clistn, then pred must
1961     be a procedure taking n arguments and returning a boolean result.
1962     ANY applies pred to the first elements of the clisti parameters.
1963     If this application returns a true value, any immediately returns
1964     that value. Otherwise, it iterates, applying pred to the second
1965     elements of the clisti parameters, then the third, and so forth.
1966     The iteration stops when a true value is produced or one of the
1967     lists runs out of values; in the latter case, any returns #f.
1968
1969     (any integer? '(a 3 b 2.7))   => #t
1970     (any integer? '(a 3.1 b 2.7)) => #f
1971     (any < '(3 1 4 1 5) '(2 7 1 8 2)) => #t
1972
1973
1974 (EVERY pred clist1 clist2...)
1975 (EVERY? pred clist1 clist2...)
1976
1977     Applies the predicate across the lists, returning true if the
1978     predicate returns true on every application.
1979     If there are n list arguments clist1 ... clistn, then pred must
1980     be a procedure taking n arguments and returning a boolean result.
1981     EVERY applies pred to the first elements of the clisti parameters.
1982     If this application returns false, every immediately returns false.
1983     Otherwise, it iterates, applying pred to the second elements of
1984     the clisti parameters, then the third, and so forth. The iteration
1985     stops when a false value is produced or one of the lists runs out
1986     of values. In the latter case, every returns the true value produced
1987     by its final application of pred.
1988     If one of the clisti has no elements, every simply returns #t.
1989
1990
1991 (MAKE-COROUTINE <routine>)
1992
1993     Creates a coroutine. <routine> must be a lambda with one argument,
1994     which will be "yield" continuation. Returns coroutine object.
1995     Coroutine object can be called without args to run coroutine until
1996     it yields. Such call returns yielded value.
1997     Also coroutine can be called with one argument. This argument must
1998     be symbol and coroutine will perform some actions accroding to arg.
1999     Actions:
2000         'status?
2001             return current coroutine status: 'suspended or 'dead.
2002         'dead?
2003             return true if coroutine is dead and false otherwise.
2004         'alive?
2005             return true if coroutine is alive and false otherwise.
2006         'kill!
2007             kill coroutine (make it dead).
2008
2009
2010 (READ-LINE #!optional (port (current-input-port)))
2011
2012     Read line from input port. Return string without trailing "\n"
2013     or eof-object.
2014
2015 (READ-FILE-LINES filename)
2016
2017     Return list with all lines from the file. Raises an error if
2018     there is no such file or file can't be read.
2019
2020 (IOTA count #!optional (start 0) (step 1))
2021
2022     Returns a list containing the elements (start start+step ... start+(count-1)*step)
2023
2024
2025
2026 OBJECT REPRESENTATIONS
2027 ======================
2028
2029 This version of XScheme uses the following object
2030 representations:
2031
2032 Closures are represented as pairs.
2033 The car of the pair is the compiled function.
2034 The cdr of the pair is the saved environment.
2035
2036 Compiled functions are represented as vectors.
2037 The element at offset 0 is the bytecode string.
2038 The element at offset 1 is the function name.
2039 The element at offset 2 is a list of names of the
2040 function arguments.
2041 The element at offset 3 is a debug info. This is
2042 the list of items: (code-ofs . (line pos)). The
2043 first item is the name of the source file (not yet).
2044 The elements at offsets above 3 are the literals
2045 refered to by the compiled bytecodes.
2046
2047 Environments are represented as lists of vectors.
2048 Each vector is an environment frame. The element at
2049 offset 0 is a list of the symbols that are bound in
2050 that frame. The symbol values start at offset 1.
2051
2052 Objects are represented as vectors. The element at
2053 offset 0 is the class of the object. The remaining
2054 elements are the object's instance variable values.