LispPad

Lightweight Scheme Development on macOS and iOS

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, compiling them, and evaluating them sequentially in the environment. load returns the result of evaluating the last expression or definition from the file. During compilation, the special form source-directory can be used to access the directory in which the executed file is located.

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 name suffix, also called path extension, is provided, the system will try to determine the right suffix. For instance, (load "Prelude") will find the prelude file, determine its suffix and load and execute the file.

File paths

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) and a path extension (sometimes also called file name suffix, if the path refers to a file). Paths are either absolute, if they start with character '/', or they are relative to some unspecified directory.

If a relative path is used to refer to a concrete directory or file, e.g. in the API provided by library (lispkit port), typically the path is interpreted as relative to the path as defined by the parameter object current-directory, unless specified otherwise.

current-directory     [parameter object]

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

(source-directory)     [syntax]

Returns the directory in which the source file is located which is currently being compiled and executed. Typically, such source files are executed via procedure load.

(home-directory)     [procedure]
(home-directory username)

Returns the path of the home directory of the user identified via string username. If username is not given, the name of the current user is used as a default. The name of the current user can be retrieved via procedure current-user-name.


(home-directory "objecthub")  ⇒  "/Users/objecthub"

(system-directory type)     [procedure]

Returns a list of paths to system directories specified via symbol type for the current user. In most cases, a single value is returned. The following type values are supported:

  • desktop: The "Desktop" folder.
  • downloads: The "Downloads" folder.
  • movies: The "Movies" folder.
  • music: Ths "Music folder.
  • pictures: The "Pictures" folder.
  • documents: The "Documents" folder.
  • shared-public: The "Public" folder.
  • application-scripts: The folder where AppleScript source code is stored.
  • temporary: A shared temporary folder.

(system-directory 'documents)  ⇒  ("/Users/objecthub/Documents")

(path path comp ...)     [procedure]

Constructs a new relative file or directory path consisting of a relative (or absolute) base path base and a number of path components comp .... If it is not possible to coonstruct a valid path, this procedure returns #f.


(path "one" "two" "three.png")  ⇒  "one/two/three.png"

(parent-path path)     [procedure]

Returns the parent path of path. The result is either a relative path if path is relative, or the result is an absolute path. parent-path returns #f if path is not a valid path.


(parent-path "one/two/three.png")  ⇒  "one/two"
(parent-path "three.png")          ⇒  "."

(path-components path)     [procedure]

Returns the individual components of a (relative or absolute) path as a list of strings. Returns #f if path is not a valid path.


(path-components "one/two/three.png")  ⇒  ("one" "two" "three.png")

(file-path path)     [procedure]
(file-path path base)

Constructs a new absolute file or directory path consisting of a base path base and a relative file path path.


(file-path "Photos/img01.jpg" "/Users/objecthub")  ⇒  "/Users/objecthub/Photos/img01.jpg"

(asset-file-path name type)     [procedure]
(asset-file-path name type dir)

Returns a new absolute file or directory path to a LispKit asset. An asset is identified via a file name, a file type, and an optional directory path dir. name, type, and dir are all strings. An asset is a file which is located directly or indirectly in one of the asset directories part of the LispKit installation. An asset has a type, which is the default path extension of the file (e.g. "png" for PNG images). If dir is provided, it is a relative path to a sub-directory within a matching asset directory.

asset-file-path constructs a relative file path in the following way (assuming there is no existing file path extension already):

   dir/name.type

It then searches the asset paths in their given order for a file matching this relative file path. Once the first matching file is found, an absolute file path for this file is returned by asset-file-path. If no valid (and existing) file is found, asset-file-path returns #f.

(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. The result of parent-file-path is always an absolute path.

(path-extension path)     [procedure]

Returns the path extension of path or #f if there is no path extension.


(path-extension "/foo/bar.txt")  ⇒  "txt"
(path-extension "/foo/bar")      ⇒  #f

(append-path-extension path ext opt)     [procedure]

Appends path extension string ext to the file path path. The extension is added no matter whether path has an extension already or not, unless opt is set to #t, in which case extension ext is only added if there is no extension already.


(append-path-extension "/foo/bar" "txt")        ⇒  "/foo/bar.txt"
(append-path-extension "/foo/bar.txt" "mp3")    ⇒  "/foo/bar.txt.mp3"
(append-path-extension "/foo/bar.txt" "mp3" #t) ⇒  "/foo/bar.txt"
(append-path-extension "" "txt")                ⇒  #f

(remove-path-extension path)     [procedure]

Removes the path extension of path if one exists and returns the resulting path. If no path extension exists, path is returned.


(remove-path-extension "/foo/bar")         ⇒  "/foo/bar"
(remove-path-extension "/foo/bar.txt")     ⇒  "/foo/bar"
(remove-path-extension "/foo/bar.txt.mp3") ⇒  "/foo/bar.txt"
(remove-path-extension "")                 ⇒  ""

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

LispKit supports ways to explore the file system, test if files or directories exist, read and write files, list directory contents, get metadata about files (e.g. file sizes), etc. Most of this functionality is provided by the libraries (lispkit system) and (lispkit port).

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

(file-readable? path)     [procedure]

Returns #t if the file at path exists and is readable; returns #f otherwise.

(directory-readable? path)     [procedure]

Returns #t if the directory at path exists and is readable; returns #f otherwise.

(file-writable? path)     [procedure]

Returns #t if the file at path exists and is writable; returns #f otherwise.

(directory-writable? path)     [procedure]

Returns #t if the directory at path exists and is writable; returns #f otherwise.

(file-deletable? path)     [procedure]

Returns #t if the file at path exists and is deletable; returns #f otherwise.

(directory-deletable? path)     [procedure]

Returns #t if the file at path exists and is deletab; returns #f otherwise.

(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

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

(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 (symbol) which got configured by the user for the operation system. If the string argument lang is provided, a locale representing lang (and all countries for which lang is supported) is returned. If both lang and string 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)           ⇒  en_US
(locale "de")      ⇒  de
(locale "en" "GB") ⇒  en_GB

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