next up previous contents
Next: 7. Foreign function interface Up: QScheme Documentation Previous: 5. Expressions   Contents

Subsections

6. QScheme procedures

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 ligthly documented here. New types are described more in depth.

6.1 Atom

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

Return a pointer to the hash table containing all atoms.

(string->atom str) -> atom

Create an atom from the string given as argument.

(atom->string atom) -> str

Create a new string from the atom.

6.2 Symbol

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>

See R5RS.

*THINK*: should we provide a way to undefine a symbol ?

6.3 Keyword

Keyword are special symbols that evaluate to them self. The keywords are reconized by the read procedure. A keyword always start with a ':' . Exemples:

:test -> :test

6.4 Pair

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>

Return #t if object is a pair

(cons arg1 arg2) -> <pair>

Create a new pair whose car is arg1 and cdr is arg2

(car pair) -> <object>

Return the content of the car field of the pair

(cdr pair) -> <object>

Return the content of the cdr field

(caar pair 
(cadr pair 
...  
(cdddar pair 
(cddddr pair)

Successive composition of car and cdr function, up to 4 level depth.

(cdr pair) -> <object>

Return the content of the cdr field

(set-car! pair object) -> #undefined

Set the content of the car field of the pair to object

(set-cdr! pair object) -> #undefined

Set the content of the cdr field of the pair to object

(null? obj) -> <boolean>

Function description.

6.5 List

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 omiting 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

6.6 Characters

Characters represents printed chars. Character uses the notation #\<character> or #<character name>, see R5RS and table 3 for more details.

Table 3: Character name
Character name Character Ascii (decimal)
#\null '\0', the NUL character 0
#\bell '\t' , the character ringing the bell 7
#\backspace the backspace 8
#\tab horizontal tab 9
#\newline newline 10
#\vtab vertical tab 11
#\formfeed formfeed 12
#\return return 13
#\space space 32



.

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

6.7 String

Strings procedure are 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, filled with char.

(string char ...) -> <string>

Create a new string from the characters given as argument.

(string-length str) -> <number>

Return the 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 pos start and terminating at pos 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>

Concat str1 and str2.

6.8 Vector

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

6.9 Hash

Figure 1: The various hash type
\includegraphics {hashes.eps}

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. Usefull for hash optimisation.

(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 assiociation list.

6.10 Number

6.11 Input / output

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:

> (with-output-to-file "/tmp/tst" (lambda () (write 123) (newline)))

#undefined

> (system "cat /tmp/tst")

123

0

> (with-input-from-file "/tmp/tst" (lambda () (read)))

123

(open-input-file <string>filename) -> <port> 
(open-output-file <string>filename) -> <port>

Open file for reading respecively writing. An error exception is thrown when file cannot be opened.

(close-port port) -> <boolean>
(close-input-port port) -> <boolean>
(close-output-port port) -> <boolean>

Close an open port.

(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.

6.12 Error handling

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 excpetions occuring 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 toplevel catch is activated. If the tag is #t the handler of the enclosing catch is activated.

Example of a throw to an enclosing catch:

> (catch (a b) (lambda (t m)

                 (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

Example of a trow to first enclosing catch:

> (catch (a b) (lambda (t m)

                 (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

Exemple of a throw to toplevel catch:

> (catch (a b) (lambda (t m)

                  (display "handler: catch: ") (display t) 

                  (display " msg: ") (print m) #f)

    (throw #t "TOPLEVEL ERROR"))

*** throw: tag=#t msg=TOPLEVEL ERROR

toplevel restart: k=1

6.13 Module

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:

(module A

  (export x)

  (define x 10))

 

(module B

  (export x)

  (define x 20))

 

(module C

  (import A B)

  (print x))

 

=> 10

I have a syntaxic sugar notation: to access objects of a modules you can use the module::symbol notation. Example:

(print A::x)

=> 10

Note: the default module where are all the scheme definitions is the global module.

(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*


next up previous contents
Next: 7. Foreign function interface Up: QScheme Documentation Previous: 5. Expressions   Contents
Daniel Crettol
1999-07-19