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

Defines the path referring to the current directory. Each LispKit virtual machine has its own current 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.

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

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

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"

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

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

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"

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.

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.

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

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

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

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

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.

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.

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.

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

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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

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.

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

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.

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

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

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

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.

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.

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

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

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

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

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

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

Returns the version of the Scheme implementation as a string.

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

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

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

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

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

Returns the uptime of the system in seconds.

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

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

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

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

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

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

Previous(lispkit styled-text)Next(lispkit system os)

Last updated