This library provides access to the desktop environment of the user. Currently it only provides desktop_open/1,2, which hands a document over to the application the desktop associates with it.

 desktop_open(+Document) is det

 desktop_open(+Document, +Options) is det

Open Document using the application the desktop associates with it, e.g., a PDF viewer for a `.pdf` file or a file browser if Document is a directory. Document is one of

• A URL, i.e., text for which uri_is_global/1 is true, such as https://www.swi-prolog.org or mailto:bugs@example.com. The URL is passed to the opener unmodified.
• A file or directory. This is either a plain file name, a term Dir/File or a file alias such as library(lists). If a plain file name does not exist as given it is expanded using expand_file_name/2, i.e., ~, $var and wildcards are expanded and all matching files are opened.

Options processed:

opener(+Command)

Use Command instead of the platform default. Command is a specification for process_which/2, a term Command-Args to pass the arguments Args before Document or win_shell to use the Windows ShellExecute() API.

wait(+Boolean)

If true, wait for the opener to complete and raise an exception if it fails. This does not wait for the application: openers such as xdg-open merely hand the document to the desktop and complete immediately, normally with success regardless of what the desktop does with it. Default is false, which starts the opener using the detached(true) option of process_create/3. The option is ignored if win_shell is used, which never waits.

The command to use is taken from the first of these that yields an available command:

1. The option opener(Command)
2. The Prolog flag desktop_opener if it is not default. It uses the same syntax as the opener(Command) option.
3. The Windows ShellExecute() API (see win_shell/2)
4. open on MacOS
5. cygstart (Cygwin), termux-open (Android/Termux) or wslview (WSL without a Linux desktop)
6. xdg-open (freedesktop.org), followed by the desktop specific gio, gnome-open, kde-open, kde-open5 and exo-open
7. wslview, handlr, mimeopen or run-mailcap
8. open, unless we are on Linux, where open is an alias for openvt(1) rather than a document opener.

Errors

- existence_error(source_sink, Document) if Document does not exist.

- existence_error(config, desktop_opener) if no command to open documents is available.

- process_error(Command, exit(Status)) if wait(true) is used and Command does not exit successfully.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

 desktop_open(+Document) is det

 desktop_open(+Document, +Options) is det

Open Document using the application the desktop associates with it, e.g., a PDF viewer for a `.pdf` file or a file browser if Document is a directory. Document is one of

• A URL, i.e., text for which uri_is_global/1 is true, such as https://www.swi-prolog.org or mailto:bugs@example.com. The URL is passed to the opener unmodified.
• A file or directory. This is either a plain file name, a term Dir/File or a file alias such as library(lists). If a plain file name does not exist as given it is expanded using expand_file_name/2, i.e., ~, $var and wildcards are expanded and all matching files are opened.

Options processed:

opener(+Command)

Use Command instead of the platform default. Command is a specification for process_which/2, a term Command-Args to pass the arguments Args before Document or win_shell to use the Windows ShellExecute() API.

wait(+Boolean)

If true, wait for the opener to complete and raise an exception if it fails. This does not wait for the application: openers such as xdg-open merely hand the document to the desktop and complete immediately, normally with success regardless of what the desktop does with it. Default is false, which starts the opener using the detached(true) option of process_create/3. The option is ignored if win_shell is used, which never waits.

The command to use is taken from the first of these that yields an available command:

1. The option opener(Command)
2. The Prolog flag desktop_opener if it is not default. It uses the same syntax as the opener(Command) option.
3. The Windows ShellExecute() API (see win_shell/2)
4. open on MacOS
5. cygstart (Cygwin), termux-open (Android/Termux) or wslview (WSL without a Linux desktop)
6. xdg-open (freedesktop.org), followed by the desktop specific gio, gnome-open, kde-open, kde-open5 and exo-open
7. wslview, handlr, mimeopen or run-mailcap
8. open, unless we are on Linux, where open is an alias for openvt(1) rather than a document opener.

Errors

- existence_error(source_sink, Document) if Document does not exist.

- existence_error(config, desktop_opener) if no command to open documents is available.

- process_error(Command, exit(Status)) if wait(true) is used and Command does not exit successfully.