# (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)** 
\
\&#xNAN;**(home-directory *****username*****)**\
\&#xNAN;**(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.
```scheme
(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.
```scheme
(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`.
```scheme
(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.
```scheme
(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.
```scheme
(path-components "one/two/three.png") ⇒ ("one" "two" "three.png")
```
**(file-path *****path*****)** \
\&#xNAN;**(file-path *****path base*****)**\
\&#xNAN;**(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*.
```scheme
(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*****)** \
\&#xNAN;**(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.
```scheme
(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.
```scheme
(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.
```scheme
(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*****)** \
\&#xNAN;**(open-file *****filepath app*****)**\
\&#xNAN;**(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*****)** \
\&#xNAN;**(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:
```scheme
(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`:
```scheme
(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*****)** \
\&#xNAN;**(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*****)** \
\&#xNAN;**(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*****)** \
\&#xNAN;**(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*****)** \
\&#xNAN;**(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)** \
\&#xNAN;**(locale *****lang*****)**\
\&#xNAN;**(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?`.
```scheme
(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)** \
\&#xNAN;**(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.
```scheme
(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".
**(host-name)**
Returns the network host name of the computer running the LispKit interpreter as a string. This is typically the name assigned to the machine on the local network.
**(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)** \
\&#xNAN;**(make-uuid-string *****bytevector*****)**\
\&#xNAN;**(make-uuid-string *****bytevector start end*****)**\
\&#xNAN;**(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.
```scheme
(make-uuid-string) ⇒ "9AF65983-8D44-43CB-AE9B-2FF49ED898BE"
```
**(make-uuid-bytevector)** \
\&#xNAN;**(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.