In this section I give a list of native QScheme types and the procedure to handle this types. Most of the types are described in the R5RS document and are lightly documented here. New types are described more in depth.
Atoms are unique string collected in a hash, the atom hash. They are used anywhere
we need unique strings. Symbols name and keywords are examples of atoms
(atom-hash) -> hash
(string->atom str) -> atom
(atom->string atom) -> str
A symbol has a name and a value. The name of a symbol is an atom, it's value may be any valid scheme object. New symbols are created by the (define sym value) special form.
(symbol? obj ) -> <boolean>
(symbol->string symbol ) -> <string>
*THINK*: should we provide a way to undefine a symbol ?
Keyword are special symbols that evaluate to them self. The keywords are recognized by the read procedure. A keyword always start with a ':' . Examples:
A pair consist of two pointer to other scheme object. The name of the pointers are CAR and CDR for historical reasons. Procedure to handle pairs are:
(pair? object) -> <boolean>
(cons arg1 arg2) -> <pair>
(car pair) -> <object>
(cdr pair) -> <object>
(caar pair)
(cadr pair)
...
(cdddar pair)
(cddddr pair)
(cdr pair) -> <object>
(set-car! pair object) -> #undefined
(set-cdr! pair object) -> #undefined
(null? obj) -> <boolean>
All procedures of R5RS are implemented.
(list? obj) -> <boolean>
Function description.
(length list) -> <number>
Function description.
(append list ...) -> <list>
Function description.
(reverse list) -> <list>
Function description.
(list-tail list n) -> <object>
Return a sublist of list omitting the first n elements.
(list-ref list n) -> <object>
Return the nth element of list
(memq obj list) -> <list>
(memv obj list) -> <list>
(member obj list) -> <list>
Return the first sublist where car is obj . memq uses eq?
to compare elements, memv uses eqv? and member uses
equal?.
(assq obj alist) -> <list>
(assv obj alist) -> <list>
(assoc obj alist) -> <list>
See R5RS
(for-each func list) -> #undefined
(map func list) -> <list>
See R5RS
Characters represents printed chars. Character uses the notation #\<character>
or #<character name>, see R5RS and table 3 for more
details.
|
Procedure handling chars are:
(char? obj) -> <boolean>
Return #t if object is a character
(char=? char1 char2) -> <boolean>
(char<? char1 char2) -> <boolean>
(char>? char1 char2) -> <boolean>
(char<=? char1 char2) -> <boolean>
(char>=? char1 char2) -> <boolean>
(char-ci=? char1 char2) -> <boolean>
(char-ci<? char1 char2) -> <boolean>
(char-ci>? char1 char2) -> <boolean>
(char-ci<=? char1 char2) -> <boolean>
(char-ci>=? char1 char2) -> <boolean>
Character comparison, See R5RS
(char-alphabetic? char) -> <boolean>
(char-numeric? char) -> <boolean>
(char-whitespace? char) -> <boolean>
(char-upper-case? char) -> <boolean>
(char-lower-case? char) -> <boolean>
Character classification test. See R5RS
(char->integer char) -> <number>
(integer->char number) -> <char>
Character conversion. See R5RS
(char-upcase char) -> <char>
(char-downcase char) -> <char>
Character conversion. See R5RS
Strings procedure are mostly compatible with R5RS.
(string? object) -> <boolean>
Return #t if object is a string.
(make-string size [char]) -> <string>
Create a new string from size chars, optionally filled with char.
If char is not specified, the string is filled with the character #\null.
(string char ...) -> <string>
Create a new string from the characters given as argument.
(string-length str) -> <number>
Return the current length of the string
(string-ref str k) -> <char>
Return the kth character of string.
(string-set! str k char) -> <number>
Change the kth character of string.
(string=? str1 str2) -> <boolean>
(string<? str1 str2) -> <boolean>
(string>? str1 str2) -> <boolean>
(string<=? str1 str2) -> <boolean>
(string>=? str1 str2) -> <boolean>
String comparison.
(string-ci=? str1 str2) -> <boolean>
(string-ci<? str1 str2) -> <boolean>
(string-ci>? str1 str2) -> <boolean>
(string-ci<=? str1 str2) -> <boolean>
(string-ci>=? str1 str2) -> <boolean>
Case insensitive string comparison
(substring str start end) -> <string>
Return the substring of str, starting at position start and terminating
at position end. See R5RS
(string-length str) -> <number>
Return the length of the string str.
(string-append str ...) -> <str>
Return the length of the string str.
(string->list str) -> <list>
Return a list consisting of the chars contained in string.
(list->string list) -> <string>
Build a string from a list of chars
(string-copy str) -> <string>
Return a fresh copy of a string.
(string-fill! str char) -> #undefined
Replace all character of str by char
(string-append2 str1 str2) -> <string>
Concatenate str1 and str2.
(string-index str1 str2) -> <number> | #f
Return the index of the first index in str2 where str1 is found.
Returns #f if the string str1 cannot be found.
(string-chop obj) -> obj
If obj is a string, the size of the string is shorten to exclude the
first newline if any. If obj is not a string, obj is left unchanged.
Note that the allocated size2 of the string is not changed. Only the apparent length of the string is changed.
"Hello world"
("Hello" "world")
> (string-split ":" (hash-ref environ "PATH") )
("/usr/bin" "/bin" "/usr/bin/X11" "/usr/games" "/usr/local/bin" ".")
> (string-split "/" "/usr/local/bin")
("" "usr" "local" "bin")
"/usr/bin|/bin|/usr/bin/X11|/usr/games|/usr/local/bin|."
All procedures of R5RS are implemented.
(vector? object) -> <boolean>
Return #t if obj is a vector.
(make-vector k [fill]) -> <vector>
Return #t if obj is a vector.
(vector obj ...) -> <vector>
Return a newly allocated vector whose element contain the given argument.
(vector-length vector) -> <number>
Return the number of element in vector
(vector-ref vector k) -> <object>
Return the kth element of the vector
(vector-set! vector k obj) -> #undefined
Set the kth element of the vector.
(vector->list vector) -> <list>
(list->vector list) -> <vector>
Convert vetor to list and vice versa.
(vector-fill! vector obj) -> <vector>
Change all element of vector to object
(vector-resize vector newsize) -> <vector>
Change size of a vector to newsize
(vector-append v1 v2) -> <vector>
Create a new vector which is composed from all element of v1 and v2
Hash is used to store key/value pair for fast access. Keys are assumed to be unique. Acceptable key type depends on the hash type. For generic type, any key may be used. For symbol hashes, only atoms or strings are acceptable
(make-hash type) -> <hash>
Create a hash. Hash types are: SCM_HASH_T_GEN for generic (normal)
hashes, SCM_HASH_T_SYMBOL for symbol hash and SCM_HASH_T_ATOM
for atom hash. Symbol hashes are used by modules and atoms hashes are used for
atoms :-)
(hash? hash) -> <boolean>
Return #t if it's a hash, #f otherwise.
(atom-hash? hash) -> <boolean>
Return #t if it's an atom hash, #f otherwise.
(symbol-hash? hash) -> <boolean>
Return #t if it's a symbol hash, #f otherwise.
(generic-hash? hash) -> <boolean>
Return #t if it's a generic hash, #f otherwise.
(hash-set! hash key value) -> <hash>
Create/change value associated with key.
(hash-ref hash key) -> <value>
Return the value associated with the key or #undefined if not found.
(hash-stat hash) -> #undefined
Print statistics for the hash. Useful for hash optimization.
(hash->list hash) -> <list>
Return a list containing all elements of the hash. Elements are association
pairs where car is the key and cdr is the value.
(list->hash list) -> <hash>
Build a hash from an association list.
Spartiat documentation here...
(number? obj) -> <boolean>
(integer? obj) -> <boolean>
(real? obj) -> <boolean>
(exact? obj) -> <boolean>
(inexact? obj) -> <boolean>
Type predicate.
(< n1 n2 ...) -> <boolean>
(<= n1 n2...) -> <boolean>
(>= n1 n2 ...) -> <boolean>
(> n1 n2 ...) -> <boolean>
(= n1 n2 ...) -> <boolean>
Numeric comparison.
(zero? number) -> <boolean>
(positive? number) -> <boolean>
(negative? number) -> <boolean>
(odd? number) -> <boolean>
(even? number) -> <boolean>
Number class.
(min n1 n2 ...) -> <number>
(max n1 n2 ...) -> <number>
Returns the smallest, respectively the biggest number of the given argument.
(+ n1 n2 ...) -> <number>
(- n1 n2 ...) -> <number>
(* n1 n2 ...) -> <number>
(/ n1 n2 ...) -> <number>
Arith operator
(abs n) -> <number>
Absolute value
(quotient n1 n2) -> <number>
(remainder n1 n2) -> <number>
(modulo n1 n2) -> <number>
Modulo operation
(gcd n1 n2 ...) -> <number>
(lcm n1 n2 ...) -> <number>
Gcd and lcm of numbers
(floor n) -> <number>
(ceil n) -> <number>
(truncate n) -> <number>
(round n) -> <number>
Rounding
(exp n) -> <number>
(log n) -> <number>
(log10 n) -> <number>
(sin n) -> <number>
(cos n) -> <number>
(tan n) -> <number>
(asin n) -> <number>
(acos n) -> <number>
(atan n1 n2) -> <number>
(sqrt n) -> <number>
(expt n1 n2) -> <number>
Math functions
(exact->inexact n) -> <number>
(inexact->exact n) -> <number>
Type conversion
(number->string number [base]) -> <string>
(string->number string [base]) -> <number>
Convert to/from string
(1+ n) -> <number>
(2+ n) -> <number>
(1- n) -> <number>
(2- n) -> <number>
Speed arith op
(float-precision digits) -> old
Set the number of digits after the '.' to display when printing a float
number.
pi
The number PI.
Input-output in scheme is based on concept of port.
(port? obj) -> <boolean>
Return #t if obj is a valid port object
(input-port? obj) -> <boolean>
Return #t if obj is a valid input port object
(input-port? obj) -> <boolean>
Return #t if obj is a valid output port object
(current-input-port) -> <port>
(current-output-port) -> <port>
(current-error-port) -> <port>
Return current port for default input / output / error file.
(with-input-from-file str thunk) -> <anything>
(with-output-to-file str thunk) -> <anything>
Redirect standard input or output to/from file. thunk is a procedure
without any arguments. The value returned is the value returned by the thunk.
Example of redirections with with-output-to-file and with-input-from-file:
#undefined
> (system "cat /tmp/tst")
123
0
> (with-input-from-file "/tmp/tst" (lambda () (read)))
123
For example:
"\"Hello world\"123"
(open-input-string string) -> <port>
(open-output-string) -> <port>
Open file for reading respectively writing. An error exception is thrown when file cannot be opened.
(get-output-string <output-string-port>) -> <string>
Return the string currently builded by the output-string-port.
(close-port port) -> <boolean> | <string>
(close-input-port port) -> <boolean> | <string>
(close-output-port port) -> <boolean> | <string>
Close an open port. If port is an output string port, the string output
is returned.
(read-char [port]) -> <char> | #eof
(peek-char [port]) -> <char> | #eof
Read a character from the port passed as argument. If no port argument is given,
the current-input-port is used as input port. peek-char does
not advance file position.
(read-line [port]) -> <string> | #eof
Read a line from the port passed as argument. If no port argument is given,
the current-input-port is used as input port.
(eof-object? obj) -> <boolean>
Return #t if obj is a #eof
(char-ready? port) -> <boolean>
Return #t if obj is a #eof. Not implemented.
(flush-output [port] ) -> #t
Flush the port. If no port is given, flush the default output port.
(file-position port [pos]) -> position
Get or set the current position on a file port. If no position is given the
current position is returned. Otherwise, the current file position is set to
the pos value.
The error handling is proved by two functions: catch and throw. The catch form defines a context where error are trapped. The throw function signal an error. Error is sended to the catch having the same tag or a #f as tag. When a match is found, the handler is called with the string thrown as argument. If the handler terminates, the execution resumed after the catch form and the value returned by the handler will be returned by the catch form.
When throwing, the #t tag can be used to force a top-level error with no resume, some kind of abort.
(catch taglist handler expr ...)
The catch construct traps exceptions occurring during execution of
the expressions. The taglist is a list of tags being catched. The handler
is a function with 2 arguments, a tag and a message. The handler
function is called when an exception matching one of the tag has been thrown
from inside the expr. If no exception occurs, the catch construct returns
the value of the last expression. If an exception is trapped, the value returned
is the value returned by the handler function, if any.
(throw tag string)
Sends an exception to the first catch matching the tag. The tag
and string are passed to the handler function for display purpose.
If tag is #f the top-level catch is activated. If the tag
is #t the handler of the enclosing catch is activated.
Example of a throw to an enclosing catch:
(display "handler: catch: ") (display t)
(display " msg: ") (print m) #f)
(throw 'a "ERROR A"))
*** throw: tag=a msg=ERROR A
*** catch: scm_catch_list=()
handler: catch: a msg: ERROR A
#f
(display "handler: catch: ") (display t)
(display " msg: ") (print m) #f)
(throw #f "ERROR A"))
*** throw: tag=#f msg=ERROR A
*** catch: scm_catch_list=()
handler: catch: #f msg: ERROR A
#f
(display "handler: catch: ") (display t)
(display " msg: ") (print m) #f)
(throw #t "TOPLEVEL ERROR"))
*** throw: tag=#t msg=TOPLEVEL ERROR
toplevel restart: k=1
The module system implement private name spaces in different level. It provides a way to control what names may be used from outside the module. This is a small example of the module definition:
(export x)
(define x 10))
(module B
(export x)
(define x 20))
(module C
(import A B)
(print x))
=> 10
=> 10
(module module expr...)
Create or reuse a module. Definitions occurring in a module uses a separate
symbol hash and will not conflict with definitions in other modules.
(export symbol1 symbol2 ...)
Give a list of symbols that can be used outside of this module.
(import module1 module2 ...)
Import exported symbols of the module listed here. The list of module is searched
left to right.
(current-module) -> module
Return the current module.
(set-current-module module)
Set the current module
(make-module name)-> module
Create a new module. If module already exists, the module associated with name
is returned.
module-hash -> hash
The hash associating name to module.
(module-exports module)-> list
Return the list of exported symbols.
(module-imports module)-> list
Return the list of imported symbols.
(module-symbols module)-> hash
Return a hash containing the symbol list.
(find-module name)-> module
Search a module in module hash. Returns a module or #f if not found.
*REVIEW*
Pointers are use to pass opaque types. You will receive pointers when you use the :item keyword in the foreign function interface.
(pointer? obj)-> <boolean>
Returns #t when obj is a pointer #f otherwise.
(null-pointer? obj)-> <boolean>
Returns #t when obj is a null pointer #f otherwise.
QScheme supports process forking and piping. Interface is described hereafter.
(make-process in out err string ...)-> <process>
(make-process in out err list)-> <process>
(make-process in out err vector)-> <process>
Create a new process. in, out and err possible values are
given in the table 4
|
You can invoque make-process with different type of argument, namely list of string or array of string or inlined strings. Example of such variations are given here:
(make-process :null :pipe :pipe '("ls" "-al" "/tmp"))
(make-process :null :pipe :pipe #("ls" "-al" "/tmp"))
(process? obj)-> <boolean>
Returns #t when obj is a process #f otherwise.
(process-pid proc)-> pid
Returns the process id (pid) of the process.
(process-input proc)-> <port>
(process-output proc)-> <port>
(process-error proc)-> <port>
Returns the ports corresponding to the process input, output and error stream.
You can use this ports to send or read data from the process.
(process-wait proc)-> status
Wait for a process to terminate. If proc is #t, waits for any
process to terminate. Returns the exit status of the process. After a process-wait,
the process does not exist anymore and the ports are closed. You also could
access the status of the process with the process-status function.
(process-use-execv flag)-> oldvalue
Determine if process is created with execv or execvp. When
execv is used, first argument must be the full path to the command. When execvp
is used, the PATH environment variable is search to find the command.
Returns the value of the flag before the call.
(apropos string)-> list
Return a list of known symbols that contains the string.