Go to the first, previous, next, last section, table of contents.


Base Package

List

Function: first list
Function: second list
Function: third list
Function: fourth list
Function: fifth list
Function: sixth list
Function: seventh list
Function: eighth list
Function: ninth list
Function: tenth list
These functions are equivalent to (list-ref list 0), ... (list-ref list 9), respectively.
(first '(1 2 3 4 5))     ==> 1
(third '(1 2 3 4 5))     ==> 3
(ninth '(1 2 3 4 5))     ==> #<error>

Use

Function: use symbol
Loads the source file that has been installed by the name of symbol using (use-install symbol). If the source file has been already loaded by a previous (use symbol), the file is not loaded again. If there is no such a file associated with symbol, an error is raised. Returns an unspecified value.

@source{init.scm} @use{none}

Function: use-install symbol path
Installs path of source file by the name of symbol. The source file can be later loaded by (use symbol). Returns an unspecified value.
(use-install 'clang (path-append (ksm-directory) "clang/init.scm"))

@source{init.scm} @use{none}

Command Line Processing

Function: cmdline-args [optstring optfun]

Returns a list of command line arguments (first argument is the program name). If optstring and optfun are supplied, options are parsed with getopt (3) with the opstring, and for each optional argument optfun is called with two arguments. The first argument is the option character itself and the second argument is the supplied option argument (if option argument is not supplied the second argument defaults to #f).

In an interactive session, cmdline-args returns a list whose only argument is the interpreter name.

$ ksm
> (cmdline-args)
(ksm)

Following is an example when KSM-Scheme is invoked with a Scheme program source.

$ cat prog.scm
(display (cmdline-args))
(newline)
$ ksm prog.scm a b c
(prog.scm a b c)

The above example shows that the first element in the list returned by cmdline-args is the name of the Scheme program (prog.scm), instead of the interpreter name (ksm). It also shows that command line arguments following the Scheme program name (a b c) consitute the remaining elements in the list returned by cmdline-args.

$ cat prog.scm
(display
  (cmdline-args
    "ab:c::d"
    (lambda (opt arg)
      (display "OPTION: ")
      (display opt) (display " ")
      (display arg) (newline))))
(newline)
$ ksm prog.scm -a -b ppp -c -d xyz pqr
OPTION: a #f
OPTION: b ppp
OPTION: c #f
OPTION: d #f
(prog.scm xyz pqr)

The above example illustrates the usage of optstring. optstring is a string containing the legitimate option characters. If such a character is followed by a colon (as in "b:"), the option requires an argument. Two colons (as in "c::") indicates that an option takes an optional argument.

By default, cmdline-args (more specifically, getopt() in C library) permutes the commanline arguments as it scans, so that eventually all the non-options are at the end. This behavior can be overridden by placing + or - as the first character in optstring. If + is the first character, then arguments are not permuted and option processing stops as soon as a non-option argument is encountered, as below.

$ cat prog.scm
(display
  (cmdline-args
    "+abc"
    (lambda (opt arg)
      (display "OPTION: ")
      (display opt) (display " ")
      (display arg) (newline))))
(newline)
$ ksm prog.scm -a xyz -b -c
OPTION: a #f
(prog.scm xyz -b -c)

If - is the first character, then arguments are not permuted and each non-option argument is handled as if it were the argument of an option with character code 1 (#\U{0001}).

$ cat prog.scm
(display
  (cmdline-args
    "-abc"
    (lambda (opt arg)
      (display "OPTION: ")
      (display opt) (display " ")
      (display arg) (newline))))
(newline)
$ ksm prog.scm -a xyz -b -c
OPTION: a #f
OPTION: #\U{0001} xyz
OPTION: b #f
OPTION: c #f
(prog.scm)

The special argument -- forces an end of option-scanning regardless of the scanning mode.

cmdline-args can be used in an interpreter file.

$ cat prog
#!/usr/local/bin/ksm
(display
  (cmdline-args
    "abc"
    (lambda (opt arg)
      (display "OPTION: ")
      (display opt) (display " ")
      (display arg) (newline))))
(newline)
$ prog -a -b -c xyz
OPTION: a #f
OPTION: b #f
OPTION: c #f
(prog xyz)

@source{base/getopt.c} @use{none}

Private Variable

Special Form: define-private symbol val
Special Form: define-private (symbol para ...) body ...)

define-private is the same with define except that define-private allocates or sets values of a variable in an environment private to the source file. Such a variable can be directly accessible only from expressions written in the same file. This behavior is analogous to a static global variable in C language. define-private returns an unspecified value.

$ cat a.scm
(define-private secret 123)
(define (a) secret)
$ ksm
> (load "a.scm")
> (a)
123
> secret
#<error>   ;; no such variable: secret
> (define-private secret 321)
> (a)
123        ;; accessing `secret' in "a.scm", indirectly
> secret
321        ;; accessing `secret' in the interactive environment

@source{base/base.c} @use{none}

Special Form: set-private! symbol val

Updates the value bound to the symbol spcified by symbol to val in the environment private to the source file. If there is no such a symbol in the private environment, it raises an error. Therefore, set-private! ensures that it does not inadvertently change the value of a symbol defined in the global environment that is accessible from any source file.

$ cat a.scm
(define secret 123)
(define (a) secret)
$ ksm
> (load "a.scm")
> (a) 
123
> secret
123       ;; `secret' in "a.scm"
> (set-private! secret 321)
#<error>  ;; no such variable in the private environment
> (define-private secret 321)
> (a) 
123       ;; `secret' in "a.scm"
> secret 
321       ;; `secret' in the private environment
> (set-private! secret 4321) 
> secret  ;; `secret' in the private environment
4321
> (a)     ;; `secret' in "a.scm"
123

@source{base/base.c}
@use{none}

Queue

It is often necessary to append an element at the tail of a list. With the present implementation, this manipulation requires a computational time that is proportional to the list length. Queue object has been introduced to accomplish such a manipulation in a constant time regardles of the list length. Typical usage of queue is as follows.

(define q (make-queue))
(enqueue! q 'one)
(enqueue! q 'two)
(enqueue! q 'three)
(queue-content q)     ==> (one two three) 

Function: make-queue
Returns an empty queue.

@source{base/queue.c} @use{none}

Function: enqueue! queue obj
Appends obj at the end of the queue. Returns an unspecified value.

@source{base/queue.c} @use{none}

Function: queue-content queue
Returns the content of queue (a proper list).

@source{base/queue.c} @use{none}

Function: queue? obj
Returns #t if obj is a queue, otherwise returns #f.
(define q (make-queue))
(enqueue! q 'apple)
(queue? q)          ==> #t

@source{base/queue.c} @use{none}

Function: dequeue! queue
Removes the first element from queue. Returns the removed element (which had been the first element before dequeue! is called).
(define queue (make-queue))
(enqueue! queue 'red)
(enqueue! queue 'yellow)
(queue-content queue)   ==> (red yellow)
(dequeue! queue)        ==> red
(queue-content queue)   ==> (yellow)
(dequeue! queue)        ==> yellow
(queue-content queue)   ==> ()

@source{base/queue.c} @use{none}

Function: queue-empty? queue
Returns #t if the content of queue is empty, otherwise returns #f.
(define q (make-queue))
(queue-empty? q)         ==> #t
(enqueue! q 'red)
(queue-empty? q)         ==> #f

@source{base/queue.c} @use{none}

Error Handling

Function: error string
Prints string to the standard error and end the program execution.

@source{interp/ext.c} @use{none}

Function: fatal string
Prints string to the standard error and end the program execution. Currently, effects of error and fatal are equivalent.

@source{interp/ext.c} @use{none}

Exit

Function: exit [code]
Exits the program with return code of code. If code is omitted, it defaults to 0.

@source{base/base.c} @use{none}

Hash Table

Hash table object is a table that stores objects attaching a name to each object. One can lookup an object in the table by supplying its name. Typical usage is as follows.

(define tab (make-hashtab 100))
(hashtab-enter! tab 'John "New York")
(hashtab-enter! tab 'David "Dallas")
(hashtab-lookup tab 'John)     ==> "New York"
(hashtab-includes? tab 'Mary)  ==> #f

Function: make-hashtab size
Returns an empty hashtab. size indicates the size of the table. To be efficient, size is recommended to be larger than the expected number of elements in the table. However, this is not a strictly required condition. One can specify any positive value for size, and whatever the value of size is the table can store any number of entries.

@source{base/hashtab.c} @use{none}

Function: hashtab? obj
Returns #t if obj is a hash table, otherwise returns #f.

@source{base/hashtab.c} @use{none}

Function: hashtab-enter! hashtab symbol value
Enters a new entry in hashtab. The name of the entry is symbol and its value is value. If there is already an entry with the same name, the entry is updated with value. Returns an unspecified value.

@source{base/hashtab.c} @use{none}

Function: hashtab-lookup hashtab symbol
Returns the value of an entry, in hashtab, whose name is equivalent to symbol. If there is no such entry, it raises an error.

@source{base/hashtab.c} @use{none}

Function: hashtab-includes? hashtab symbol
Returns #t if hashtab includes an entry whose name is equivalent to symbol, otherwise returns #f.

@source{base/hashtab.c} @use{none}

Function: hashtab-update! hashtab symbol value
Updates the value of the entry, in hashtab, whose name is equivalent to symbol to value. If there is no such entry, it raises an error. Returns an unspecified value.
(define tab (make-hashtab 100))
(hashtab-enter! tab 'name 'Alice)
(hashtab-lookup tab 'name)          ==> Alice
(hashtab-update! tab 'name 'Bob)
(hashtab-lookup tab 'name)          ==> Bob
(hashtab-update! tab 'gender 'male) ==> #<error>

@source{base/hashtab.c} @use{none}

Logical Operator

Function: logical-and arg ...
Returns logical-and of args (that is, arg1 & arg2 & ... in C).

(logical-and 7 6) ==> 6

@source{base/logic.c} @use{none} NOTE: Currently, args are limited to 32-bit signed integers.

Function: logical-or arg ...
Returns logical-or of args (that is, arg1 | arg2 | ... in C).

@source{base/logic.c} @use{none} NOTE: Currently, args are limited to 32-bit signed integers.

Function: logical-xor x y
Returns exclusive-or of x and y (that is, x^y in C).

Function: logical-lshift expr n
Returns the value of expr shifted to the left by n.
(logical-lshift 1 2)  ==> 4

Function: logical-rshift expr n
Returns the value of expr shifted to the left by n.
(logical-rshift 1 2)  ==> 4

@source{base/logic.c} @use{none} NOTE: Currently, x and y are limited to 32-bit integers.

Function: logical-complement arg
Returns one's complement of arg (that is, ~arg in C).

@source{base/logic.c} @use{none} NOTE: Currently, arg is limited to 32-bit integer.

Path

Function: ksm-directory
Returns a string that represents the path-name of the KSM-Scheme home directory. KSM-Scheme home directory is determined as the parent directory of the directory that contains the KSM-Scheme interpreter. For example, if the interpreter is
/usr/local/ksm/ksm-0.3.0/interp/ksm-0.3.0

KSM-Scheme home directory is

/usr/local/ksm/ksm-0.3.0
(ksm-directory)   ==> /usr/local/ksm/ksm-0.3.0  ;; example

@source{interp/ext.c} @use{none}

Function: path-append node-name node-name ...
Returns a string that concatenates all node-name's with inserting '/' between them.
(path-append "/home/hangil" "src/ksm" "interp")
  ==> "/home/hangil/src/ksm/interp"
(path-append (ksm-directory) "base")
  ==> "/home/hangil/src/ksm/base"

@source{interp/path.c} @use{none}

Function: path-directory-part path-name
Returns a string that represents the directory part of the path-name.
(path-directory-part "/home/hangil/src/ksm")
  ==> "/home/hangil/src"
(path-directory-part "src.scm")
  ==> "."

@source{interp/path.c} @use{none}

Dynamic Linking

Function: load-shared lib-path [init-fun]
Loads shared library lib-path. If init-fun is supplied, it also calls the C function named init-fun with no argument. Returns an unspecified value.

If lib-path does not include /, the shared library with that name is searched in default directories used by ld.so.

(load-shared "./libservice.so" "init_service")
  ;; loads the shared library "libservice.so" present 
  ;; in the current directory and calls the C function 
  ;; "init_service" which should be decalred as 
  ;; "void init_service(void);" in C source.

@source{interp/ext.c} @use{none}

Signal Handling

Variable: @SIGHUP
Variable: @SIGINT
Variable: @SIGQUIT
Variable: @SIGILL
Variable: @SIGTRAP
Variable: @SIGABRT
Variable: @SIGIOT
Variable: @SIGBUS
Variable: @SIGFPE
Variable: @SIGKILL
Variable: @SIGUSR1
Variable: @SIGSEGV
Variable: @SIGUSR2
Variable: @SIGPIPE
Variable: @SIGALRM
Variable: @SIGTERM
Variable: @SIGSTKFLT
Variable: @SIGCLD
Variable: @SIGCHLD
Variable: @SIGCONT
Variable: @SIGSTOP
Variable: @SIGTSTP
Variable: @SIGTTIN
Variable: @SIGTTOU
Variable: @SIGURG
Variable: @SIGXCPU
Variable: @SIGXFSZ
Variable: @SIGVTALRM
Variable: @SIGPROF
Variable: @SIGWINCH
Variable: @SIGPOLL
Variable: @SIGIO
Variable: @SIGPWR
Variable: @SIGUNUSED

These variables are signal numbers as defined in signum.h. Short descriptions of their meanings are as follows (excerpted from signum.h).
@SIGHUP 1 Hangup (POSIX).
@SIGINT 2 Interrupt (ANSI).
@SIGQUIT 3 Quit (POSIX).
@SIGILL 4 Illegal instruction (ANSI).
@SIGTRAP 5 Trace trap (POSIX).
@SIGABRT 6 Abort (ANSI).
@SIGIOT 6 IOT trap (4.2 BSD).
@SIGBUS 7 BUS error (4.2 BSD).
@SIGFPE 8 Floating-point exception (ANSI).
@SIGKILL 9 Kill, unblockable (POSIX).
@SIGUSR1 10 User-defined signal 1 (POSIX).
@SIGSEGV 11 Segmentation violation (ANSI).
@SIGUSR2 12 User-defined signal 2 (POSIX).
@SIGPIPE 13 Broken pipe (POSIX).
@SIGALRM 14 Alarm clock (POSIX).
@SIGTERM 15 Termination (ANSI).
@SIGSTKFLT 16 Stack fault.
@SIGCLD 17 Same as SIGCHLD (System V).
@SIGCHLD 17 Child status has changed (POSIX).
@SIGCONT 18 Continue (POSIX).
@SIGSTOP 19 Stop, unblockable (POSIX).
@SIGTSTP 20 Keyboard stop (POSIX).
@SIGTTIN 21 Background read from tty (POSIX).
@SIGTTOU 22 Background write to tty (POSIX).
@SIGURG 23 Urgent condition on socket (4.2 BSD).
@SIGXCPU 24 CPU limit exceeded (4.2 BSD).
@SIGXFSZ 25 File size limit exceeded (4.2 BSD).
@SIGVTALRM 26 Virtual alarm clock (4.2 BSD).
@SIGPROF 27 Profiling alarm clock (4.2 BSD).
@SIGWINCH 28 Window size change (4.3 BSD, Sun).
@SIGPOLL 29 Pollable event occurred (System V).
@SIGIO 29 I/O now possible (4.2 BSD).
@SIGPWR 30 Power failure restart (System V).
@SIGUNUSED 31

Function: make-sigset
Returns an empty sigset, which is a Scheme object that represents sigset_t in C language.

Function: sigset? obj
Returns #t if obj is a sigset object, otherwise returns #f.

Function: sigemptyset sigset
Excludes all of the defined signals from sigset. sigset should be a sigset object. Returns an unspecified value.

Function: sigfillset sigset
Adds all of the defined signals in sigset. sigset should be a sigset object. Returns an unspecified value.

Function: sigaddset sigset signum
Adds the signal signum in sigset. sigset should be a sigset object. sigset should be an integer. Returns an unspecified value.

Function: sigdelset sigset signum
Deletes the signal signum from sigset. sigset should be a sigset object. sigset should be an integer. Returns an unspecified value.

Function: sigismember? sigset signum
Returns #t if the signal signum is included in sigset, otherwise returns #f. sigset should be a sigset object. sigset should be an integer.

Variable: @SIG_BLOCK
Variable: @SIG_UNBLOCK
Variable: @SIG_SETMASK

These variables are from signal.h.

Schedule

Variable: @SCHED_RR
Variable: @SCHED_FIFO
Variable: @SCHED_OTHER
These values are from sched.h.

Case Sensitivity

Function: set-read-case-sensitivitiy bool
Sets the case-sensitivity of Scheme reader. If bool is #t, symbol names are read with preserving the case-sensitivity as in C (default behavior). Otherwise, symbol names are read with ignoring the case-sensitivity. Returns an unspecified value.
(eq? 'abc 'ABC) ==> #f ;; KSM-Scheme is case sensitive by default
(set-read-case-sensitivity #f)
(eq? 'abc 'ABC) ==> #t ;; This is in accord with Scheme Standard
(set-read-case-sensitivity #t)
(eq? 'abc 'ABC) ==> #f ;;

@source{base/base.c} @use{none} NOTE: The default behavior of KSM-Scheme (case-sensitive) is contrary to the Scheme Standard. This decision in KSM-Scheme was made to be convinient in interfacing with C.


Go to the first, previous, next, last section, table of contents.