(lispkit system)

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

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

(source-directory)

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) (home-directory username) (home-directory username non-sandboxed?)

Returns the path of the home directory of the user identified via string username. If username is not given or is set to #f, 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. If boolean argument non-sandboxed? is set to #t, home-directory will return the Unix home directory path, even if LispKit is used in a sandboxed application such as LispPad.

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

(system-directory type)

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.

• icloud: The "Documents" folder on iCloud.

• shared-public: The "Public" folder.

• application-support: The application support directory on iOS (only accessible to the application hosting LispKit)

• application-scripts: The folder where AppleScript source code is stored (only available on macOS).

• cache: The cache directory on iOS.

• temporary: A shared temporary folder.

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

(path path comp ...)

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)

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)

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) (file-path path base) (file-path path base resolve?)

Constructs a new absolute file or directory path consisting of a base path base and a relative file path path. Procedure file-path will also resolve symbolic links if boolean argument resolve? is #t. The default for resolve? is #f. Tilde is always resolved, if provided either in path or base.

(file-path "Photos/img.jpg" "/Users/mz/Desktop")
⇒  "/Users/mz/Desktop/Photos/img.jpg"
(file-path "~/Images/test.jpg")
⇒  "/Users/objecthub/Images/test.jpg"
(file-path "~/Images/test.jpg" "/random")
⇒  "/Users/objecthub/Images/test.jpg"

(asset-file-path name type) (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)

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)

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)

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)

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)

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)

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)

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)

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)

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

(directory-readable? path)

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

(file-writable? path)

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

(directory-writable? path)

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

(file-deletable? path)

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

(directory-deletable? path)

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

(delete-file filepath)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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) (open-file filepath app) (open-file filepath app activate)

Opens the file specified by filepath with the application app. app is either an application name or a file path. 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)

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

(http-get url) (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)

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)

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)

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)

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

(available-region? obj)

Returns #t if obj is a string matching one entry in the list of supported 2-letter region code identifiers. Otherwise, #f is returned.

(region-name ident) (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.

(region-flag ident)

Returns the flag of the region identified by the 2-letter region code string ident as a string containing a single flag emoji.

(region-continent ident)

Returns a region identifier (string) for the continent containing the region identified by the 2-letter region code string ident.

(region-parent ident)

Returns an identifier for the parent of the region identified by the 2-letter region code string ident.

(region-subregions ident)

Returns a list of identifiers (strings) for all regions contained in the region identified by the 2-letter region code string ident.

(available-languages)

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

(available-language? obj)

Returns #t if obj is a 2-letter language code identifier string contained in the list of supported/available languages.

(language-name ident) (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-currencies)

Returns a list of available alpha currency codes based on ISO 4217. A currency code is a 3-letter symbol.

(available-currency? obj)

Returns #t if obj is a valid alpha currency code (symbol) that is contained in the list of supported/available currencies.

(currency-name ident) (currency-name ident locale)

Returns the name of the currency identified by the currency identifier ident for the given locale locale. ident can either be a numeric (fixnum) or alpha (symbol or string) currency code as defined by ISO 4217. If locale is not provided, the current (system-configured) locale is used.

(currency-code ident)

Returns the alpha currency code of the currency identified by the currency identifier ident. ident can either be a numeric (fixnum) or alpha (symbol or string) currency code as defined by ISO 4217. Returns #f if ident is not a valid, available currency code symbol.

(currency-numeric-code ident)

Returns the numeric currency code of the currency identified by the currency identifier ident. ident can either be a numeric (fixnum) or alpha (symbol or string) currency code as defined by ISO 4217. Returns #f if ident is not a valid, available currency code symbol.

(currency-symbol ident) (currency-symbol ident locale)

Returns a currency symbol (e.g. "€", "$", "￡") for the currency identified by the currency identifier ident for the given locale locale. ident can either be a numeric (fixnum) or alpha (symbol or string) currency code as defined by ISO 4217. If locale is not provided, the current (system-configured) locale is used. If there is no currency symbol for a given currency, then #f is returned.

(available-locales)

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

(available-locale? locale)

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

(locale) (locale lang) (locale lang country)

If no argument is provided locale returns the current locale (symbol) as configured by the user for the operating 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 canonical locale identifiers 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 "en" "de") ⇒  en_DE

(locale-region locale)

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)

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)

Returns the alpha currency code as a symbol 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)

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)

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)

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

(features)

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:

• 32bit

• 64bit

• arm

• arm64

• big-endian

• complex

• dynamic-loading

• i386

• ios

• linux

• lispkit

• lisppad

• little-endian

• macos

• macosx

• modules

• r7rs

• ratios

• repl

• runloop

• syntax-rules

• threads

• x86-64

(implementation-name)

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

(implementation-version)

Returns the version of the Scheme implementation as a string.

(cpu-architecture)

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

(machine-name)

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

(machine-model)

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

(physical-memory)

Returns the amount of physical memory of the device executing the LispKit code in bytes.

(memory-footprint)

Returns the amount of memory allocated by the application executing the LispKit code in bytes.

(system-uptime)

Returns the uptime of the system in seconds.

(available-network-interfaces) (available-network-interfaces ipv4only)

Returns an association list mapping names of available network interfaces to pairs consisting of local ip addresses and network masks. When ipv4only is set to #t, only network interfaces with IPv4 IP addresses are being returned.

(available-network-interfaces)
⇒  (("en0" "192.168.10.175" . "255.255.255.0") ("utun24" "10.5.0.2" . "255.255.0.0"))

(os-type)

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)

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)

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)

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)

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

(user-data username)

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

(terminal-size)

If a program gets executed in a terminal window, it might be possible to determine the number of columns and rows of that window. In this case, procedure terminal-size returns a pair consisting of the number of columns and the number of rows (both in terms of number of characters). If this is not possible, terminal-size returns #f.

UUIDs

(make-uuid-string) (make-uuid-string bytevector) (make-uuid-string bytevector start end) (make-uuid-string bytevector start end)

Returns a UUID string. A UUID (Universally Unique Identifier) is a 128-bit label. make-uuid-string returns a string with a hexadecimal representation using the 8-4-4-4-12 format. If bytevector is not provided, a random UUID is returned. Otherwise, a string representation of the 16-byte bytevector between start (inclusive) and end (exclusive) is returned.

(make-uuid-string) ⇒ "9AF65983-8D44-43CB-AE9B-2FF49ED898BE"

(make-uuid-bytevector) (make-uuid-bytevector str)

Returns a UUID as a bytevector. A UUID (Universally Unique Identifier) is a 128-bit label. If str is not provided, a random UUID bytevector is returned. If str is provided, it is assumed it is a UUID string (e.g. generated by make-uuid-string) and make-uuid-bytevector returns a 16-byte representation of this UUID as a bytevector.