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 lightly 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 recognized by the read procedure. A keyword always start with a ':' . Examples:

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

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

> (string-chop "Hello world\n\nI said...\n")

"Hello world"

(string-split delim str) -> <list>
Returns a list of the substring from str that were enclosed within one of the character in the delim string. Example:

> (string-split "\t " "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")

(string-join sep list) -> string
Is the inverse transformation of string-split. It takes a list of string and make a new string composed of all string of list separated with sep. Example:

> (string-join "|" (string-split ":" (hash-ref environ "PATH")))

"/usr/bin|/bin|/usr/bin/X11|/usr/games|/usr/local/bin|."

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

6.10 Number

No documented yet

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

(with-input-from-string str thunk) -> <anything>
(with-output-to-string thunk) -> <string>
Redirect standard input or output to/from string. thunk is a procedure without any arguments. The value returned by with-input-from-string is the value returned by the thunk. The value returned by with-output-to-string is the entire string built in thunk.

For example:

> (with-output-to-string (lambda () (write "Hello world") (write 123)))

"\"Hello world\"123"

(open-input-file <string>filename) -> <port> 
(open-output-file <string>filename) -> <port>
Open file for reading respectively writing. An error exception is thrown when file cannot be opened.

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

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

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

Example of a throw to top-level 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*

6.14 Pointers

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.

6.15 Process

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

Table 4: Possible values for make-process in out and err
Type Description
:null Nothing connected here
:pipe Create a pipe
string Open a file and redirect from/to it
port Use an already opened port
number Redirect to an already opened slot


. After this call, a new process is created and a process descriptor is returned. If something goes wrong, an error will be generated.

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"))

(make-process :null :pipe :pipe #("ls" "-al" "/tmp"))

The first string of the argument is the full path to the command to execute and is also the argv[0] of the command.

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

Note:
By default, execvp is used.

6.16 Miscellaneous

(apropos string)-> list
Return a list of known symbols that contains the string.


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