LispKit System

Source files

(load filename)     [procedure]
(load filename environment)

load reads a source file specified by filename and executes it in the given environment. If no environment is specified, the current interaction environment is used, which can be accessed via (interaction-environment). Execution of the file consists of reading expressions and definitions from the file and evaluating them sequentially in the environment. load returns the result of evaluating the last expression or definition from the file.

It is an error if filename is not a string. If filename is not an absolute file path, LispKit will try to find the file in a predefined set of directories, such as the default libraries search path. If no file suffixes are provided, the system is trying to determine the right suffix. For instance, (load "Prelude") will find the prelude file, determine its suffix and load and execute the file.

File operations

Files and directories are referenced by paths. Paths are strings consisting of directory names separated by character '/' optionally followed by a file name (if the path refers to a file). Paths are either absolute, if they start with character '/', or they are relative to the current directory. LispKit supports ways to read and write files, inspect directories, get metadata about files (e.g. file sizes), etc.

current-directory     [parameter object]

Defines the path referring to the current directory. Each LispKit virtual machine has its own current directory.

(file-path path base)     [procedure]

Constructs a new file or directory path consisting of a base path base and a relative file path path. Example: (file-path "Photos/img01.jpg" "/Users/objecthub") ⇒ "/Users/objecthub/Photos/img01.jpg".

(parent-file-path path)     [procedure]

If path refers to a file, then parent-file-path returns the directory in which this file is contained. If path refers to a directory, then parent-file-path returns the directory in which this directory is contained.

(file-path-root? path)     [procedure]

Returns #t if path exists and corresponds to the root of the directory hierarchy. The root is typically equivalent to "/". It is an error if path is not a string.

(file-exists? filepath)     [procedure]

The file-exists? procedure returns #t if the named file exists at the time the procedure is called, and #f otherwise. It is an error if filename is not a string.

(directory-exists? dirpath)     [procedure]

The directory-exists? procedure returns #t if the named directory exists at the time the procedure is called, and #f otherwise. It is an error if filename is not a string.

(file-or-directory-exists? path)     [procedure]

The file-or-directory-exists? procedure returns #t if the named file or directory exists at the time the procedure is called, and #f otherwise. It is an error if filename is not a string.

(delete-file filepath)     [procedure]

The delete-file procedure deletes the file specified by filepath if it exists and can be deleted. If the file does not exist or cannot be deleted, an error that satisfies file-error? is signaled. It is an error if filepath is not a string.

(delete-directory dirpath)     [procedure]

The delete-directory procedure deletes the directory specified by dirpath if it exists and can be deleted. If the directory does not exist or cannot be deleted, an error that satisfies file-error? is signaled. It is an error if dirpath is not a string.

(delete-file-or-directory path)     [procedure]

The delete-file-or-directory procedure deletes the directory or file specified by path if it exists and can be deleted. If path neither leads to a file nor a directory or the file or directory cannot be deleted, an error that satisfies file-error? is signaled. It is an error if path is not a string.

(copy-file filepath targetpath)     [procedure]

The copy-file procedure copies the file specified by filepath to the file specified by targetpath. An error satisfying file-error? is signaled if filepath does not lead to an existing file or if a file at targetpath cannot be written. It is an error if either filepath or targetpath are not strings.

(copy-directory dirpath targetpath)     [procedure]

The copy-directory procedure copies the directory specified by dirpath to the directory specified by targetpath. An error satisfying file-error? is signaled if dirpath does not lead to an existing directory or if a directory at targetpath cannot be written. It is an error if either dirpath or targetpath are not strings.

(copy-file-or-directory sourcepath targetpath)     [procedure]

The copy-file-or-directory procedure copies the file or directory specified by sourcepath to the file or directory specified by targetpath. An error satisfying file-error? is signaled if sourcepath does not lead to an existing file or directory, or if a file or directory at targetpath cannot be written. It is an error if either sourcepath or targetpath are not strings.

(move-file filepath targetpath)     [procedure]

Moves the file at filepath to targetpath. This procedure fails if filepath does not reference an existing file, or if the file cannot be moved to targetpath. It is an error if either filepath or targetpath are not strings.

(move-directory dirpath targetpath)     [procedure]

Moves the directory at dirpath to targetpath. This procedure fails if dirpath does not reference an existing directory, or if the directory cannot be moved to targetpath. It is an error if either dirpath or targetpath are not strings.

(move-file-or-directory sourcepath targetpath)     [procedure]

Moves the file or directory at sourcepath to targetpath. This procedure fails if sourcepath does not reference an existing file or directory, or if the file or directory cannot be moved to targetpath. It is an error if either sourcepath or targetpath are not strings.

(file-size filepath)     [procedure]

Returns the size of the file specificed by filepath in bytes. It is an error if filepath is not a string or if filepath does not reference an existing file.

(directory-list dirpath)     [procedure]

Returns a list of names of files and directories contained in the directory specified by dirpath. It is an error if dirpath is not a string or if dirpath does not reference an existing directory.

(make-directory dirpath)     [procedure]

Creates a directory with path dirpath. If the directory exists already or if it is not possible to create a directory with path dirpath, make-directory fails with an error. It is an error if dirpath is not a string.

(open-file filepath)     [procedure]
(open-file filepath app)
(open-file filepath app activate)

Opens the file specified by filepath with the application app. activate is a boolean argument. If it is #t, it will make app the frontmost application after invoking it. If app is not specified, the default application for the type of the file specified by filepath is used. If activate is not specified, it is assumed it is #t. open-file returns #t if it was possible to open the file, #f otherwise. Example: (open-file "/Users/objecthub/main.swift" "TextEdit").

Network operations

(open-url url)     [procedure]

Opens the given url in the default browser and makes the browser the frontmost application.

(http-get url)     [procedure]
(http-get url timeout)

http-get performs an http get request for the given URL. timeout is a floating point number defining the time in seconds it should take at most for receiving a response. http-get returns two values: the HTTP header in form of an association list, and the content in form of a bytevector. It is an error if the http get request fails. Example:

(http-get "http://github.com/objecthub") ⇒

(("Date" . "Sat, 17 Nov 2018 22:47:19 GMT")
 ("Referrer-Policy" . "origin-when-cross-origin, strict-origin-when-cross-origin")
 ("X-XSS-Protection" . "1; mode=block")
 ("Status" . "200 OK")
 ("Transfer-Encoding" . "Identity")
 ...
 ("Content-Type" . "text/html; charset=utf-8")
 ("Server" . "GitHub.com"))
#u8(10 10 60 33 68 79 67 84 89 80 69 32 104 116 109 108 62 10 60 104 116 109 108 32 108 97 110 103 61 34 101 110 34 62 10 32 32 60 104 101 97 100 62 10 32 32 32 32 60 109 101 116 97 32 99 104 97 114 115 101 116 61 34 117 116 102 ...)

Time operations

(time expr)     [syntax]

time compiles expr and executes it. The form displays the time it took to execute expr as a side-effect. It returns the result of executing expr.

(current-second)     [procedure]

Returns a floating-point number representing the current time on the International Atomic Time (TAI) scale. The value 0.0 represents midnight on January 1, 1970 TAI (equivalent to ten seconds before midnight UTC) and the value 1.0 represents one TAI second later. Note: The current implementation returns the same number like current-seconds. This is not conforming to the R7RS spec requiring TAI scale.

(current-jiffy)     [procedure]

Returns the number of jiffies as a fixnum that have elapsed since an arbitrary epoch. A jiffy is a fraction of a second which is defined by the return value of the jiffies-per-second procedure. The starting epoch is guaranteed to be constant during a run of the program, but may vary between runs.

(jiffies-per-second)     [procedure]

Returns a fixnum representing the number of jiffies per SI second. Here is an example for how to use jiffies-per-second:

(define (time-length)
  (let ((list (make-list 100000))
        (start (current-jiffy)))
    (length list)
    (/ (- (current-jiffy) start) (jiffies-per-second))))

Locales

For handling locale-specific behavior, e.g. for formatting numbers and dates, library (lispkit system) defines a framework in which

• regions/countries are identified via ISO 3166-1 Alpha 2-code strings,
• languages are identified via ISO 639-1 2-letter strings, and
• locales (i.e. combinations of regions and languages) are identified as symbols.

Library (lispkit system) provides functions for returning all available regions, languages, and locales. It also defines functions to map identifiers to human-readable names and to construct identifiers out of other identifiers.

(available-regions)     [procedure]

Returns a list of 2-letter region code identifiers (strings) for all available region.

(region-name ident)     [procedure]
(region-name ident locale)

Returns the name of the region identified by the 2-letter region code string ident for the given locale locale. If locale is not provided, the current (system-provided) locale is used.

(available-languages)     [procedure]

Returns a list of 2-letter language code identifiers (strings) for all available languages.

(language-name ident)     [procedure]
(language-name ident locale)

Returns the name of the language identified by the 2-letter language code string ident for the given locale locale. If locale is not provided, the current (system-configured) locale is used.

(available-locales)     [procedure]

Returns a list of all available locale identifiers (symbols).

(available-locale? locale)     [procedure]

Returns #t if the symbol locale is identifying a locale supported by the operating system; returns #f otherwise.

(locale)     [procedure]
(locale lang)
(locale lang country)

If no argument is provided locale returns the current locale which got configured by the user for the operation system. If argument lang is provided, a locale representing lang (and all countries for which lang is supported) is returned. If both lang and country are provided, locale will return a symbol identifying the corresponding locale.

This function never fails if both lang and country are strings. It can be used for constructing locales that are not supported by the underlying operating system. This can be checked with function available-locale?.

(locale-region locale)     [procedure]

Returns the 2-letter region code string for the region targeted by the locale identifier locale. If locale does not target a region, locale-region returns #f.

(locale-language locale)     [procedure]

Returns the 2-letter language code string for the language targeted by the locale identifier locale. If locale does not target a language, locale-language returns #f.

(locale-currency locale)     [procedure]

Returns the 3-letter currency code string for the currency associated with the country targeted by locale. If locale does not target a country, locale-currency returns #f.

Execution environment

(get-environment-variable name)     [procedure]

Many operating systems provide each running process with an environment consisting of environment variables. Both the name and value of an environment variable are represented as strings. The procedure get-environment-variable returns the value of the environment variable name, or #f if the named environment variable is not found. Example: (get-environment-variable "PATH") ⇒ "/usr/local/bin:/usr/bin:/bin".

(get-environment-variables)     [procedure]

Returns the names and values of all the environment variables as an association list, where the car of each entry is the name of an environment variable and the cdr is its value, both as strings. Example: (("USER" . "root") ("HOME" . "/")).

(command-line)     [procedure]

Returns the command line passed to the process as a list of strings. The first string corresponds to the command name.

(features)     [procedure]

Returns a list of the feature identifiers which cond-expand treats as true. Here is an example of what features might return: (modules x86-64 lispkit macosx syntax-rules complex 64bit macos little-endian dynamic-loading ratios r7rs). LispKit supports at least the following feature identifiers:

• lispkit
• r7rs
• ratios
• complex
• syntax-rules
• little-endian
• big-endian
• dynamic-loading
• modules
• 32bit
• 64bit
• macos
• macosx
• ios
• linux
• i386
• x86-64
• arm64
• arm

(implementation-name)     [procedure]

Returns the name of the Scheme implementation. For LispKit, this function returns the string "LispKit".

(implementation-version)     [procedure]

Returns the version of the Scheme implementation as a string.

(cpu-architecture)     [procedure]

Returns the CPU architecture on which this Scheme implementation is executing as a string.

(machine-name)     [procedure]

Returns a name for the particular machine on which the Scheme implementation is currently running.

(machine-model)     [procedure]

Returns an identifier for the machine on which the Scheme implementation is currently running.

(os-type)     [procedure]

Returns the type of the operating system on which the Scheme implementation is running as a string. For macOS, this procedure returns "Darwin".

(os-name)     [procedure]

Returns the name of the operating system on which the Scheme implementation is running as a string. For macOS, this procedure returns "macOS".

(os-version)     [procedure]

Returns the build number of the operating system on which the Scheme implementation is running as a string. For macOS 10.14.1, this procedure returns "18B75".

(os-release)     [procedure]

Returns the (major) release version of the operating system on which the Scheme implementation is running as a string. For macOS 10.14.1, this procedure returns "10.14".

(current-user-name)     [procedure]

Returns the username of the user running the Scheme implementation as a string.

(user-data username)     [procedure]

Returns information about the user specified via username in form of a list. The list provides the following information in the given order:

1. User id (fixnum)
2. Group id (fixnum)
3. Username (string)
4. Full name (string)
5. Home directory (string)
6. Default shell (string)

Here is an example showing the result for invocation (user-data "objecthub"): (501 20 "objecthub" "Max Mustermann" "/Users/objecthub/" "/bin/bash").

Scheme environment

(gc)     [procedure]

Force garbage collection to be performed.

(compile expr)     [procedure]

Compiles expression expr and displays the disassembled code. This is what is being printed when executing (compile '(do ((i 0 (fx1+ i)))((fx> i 10))(display i)(newline))):

CONSTANTS:
    0: #<procedure display>
    1: #<procedure newline>
INSTRUCTIONS:
    0: alloc 1
    1: push_fixnum 0
    2: make_local_variable 0
    3: push_local_value 0
    4: push_fixnum 10
    5: fx_gt
    6: branch_if 14                    ;; jump to 20
    7: make_frame
    8: push_constant 0                 ;; #<procedure display>
    9: push_local_value 0
   10: call 1
   11: pop
   12: make_frame
   13: push_constant 1                 ;; #<procedure newline>
   14: call 0
   15: pop
   16: push_local_value 0
   17: fx_inc
   18: set_local_value 0
   19: branch -16                      ;; jump to 3
   20: push_void
   21: reset 0, 1
   22: return

(disassemble proc)     [procedure]

Disassembles procedure proc and prints out the code. This is what is being printed when executing (disassemble caddr):

CONSTANTS:
INSTRUCTIONS:
    0: assert_arg_count 1
    1: push_global 426
    2: make_frame
    3: push_global 431
    4: push_local 0
    5: call 1
    6: tail_call 1

(trace-calls)     [procedure]
(trace-calls level)

This function is used to enable/disable call tracing. When call tracing is enabled, all function calls that are executed by the virtual machine are being printed to the console. Call tracing operates at three levels:

• 0: Call tracing is switched off
• 1: Call tracing is enabled only for procedures for which it is enabled (via function set-procedure-trace!)
• 2: Call tracing is switched on for all procedures (independent of procedure-level tracing being enabled or disabled)

(trace-calls n) will set call tracing to level n. If the level is ommitted, trace-calls will return the current call tracing level.

For instance, if call tracing is enabled via (trace-calls 2), executing (fib 3) will print the following call trace.

> (define (fib n)
    (if (< n 2) n (+ (fib (- n 1)) (fib (- n 2)))))
> (trace-calls 2)
> (fib 2)
  ↪︎ (fib 2) in <repl>
    ⟶ (< 2 2) in fib
    ⟵ #f from <
    ⟶ (- 2 1) in fib
    ⟵ 1 from -
    ⟶ (fib 1) in fib
      ⟶ (< 1 2) in fib
      ⟵ #t from < in fib
    ⟵ 1 from fib in fib
    ⟶ (- 2 2) in fib
    ⟵ 0 from -
    ⟶ (fib 0) in fib
      ⟶ (< 0 2) in fib
      ⟵ #t from < in fib
    ⟵ 0 from fib in fib
  ↪︎ (+ 1 0) in fib
  ⟵ 1 from fib
1

Function invocations are prefixed with ⟶, or ↪ if it's a tail call. The value returned by a function call is prefixed with ⟵.

(procedure-trace? proc)     [procedure]

Returns #f if procedure-level call tracing is disabled for proc, #t otherwise.

(set-procedure-trace! proc trace?)     [procedure]

Enables procedure-level call tracing for procedure proc if trace? is set to #t. It disables call tracing for proc if trace? is #f.

(available-symbols)     [procedure]

Returns a list of all symbols that have been used so far.

(loaded-libraries)     [procedure]

Returns a list of all libraries that have been loaded so far.

> (loaded-libraries)
((lispkit draw) (lispkit base) (lispkit port) (lispkit control) (lispkit type) (lispkit list) (lispkit string) (lispkit math) (lispkit date-time) (lispkit dynamic) (lispkit char-set) (lispkit bytevector) (lispkit char) (lispkit vector) (lispkit regexp) (lispkit record) (lispkit hashtable) (lispkit system) (lispkit core) (lispkit gvector) (lispkit box))

(loaded-sources)     [procedure]

Returns a list of all sources that have been loaded.

(environment-info)     [procedure]

Prints out debug information about the current execution environment (mostly relevant for developing LispKit).