desktop.pl -- Interact with the desktop environment

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:

The option opener(Command)
The Prolog flag desktop_opener if it is not default. It uses the same syntax as the opener(Command) option.
The Windows ShellExecute() API (see win_shell/2)
open on MacOS
cygstart (Cygwin), termux-open (Android/Termux) or wslview (WSL without a Linux desktop)
xdg-open (freedesktop.org), followed by the desktop specific gio, gnome-open, kde-open, kde-open5 and exo-open
wslview, handlr, mimeopen or run-mailcap
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.

document_arguments(+Document, -Arguments) is det[private]

Arguments is the list of URLs and file(File) terms to pass to the opener, one invocation per element.

document_files(+Document, -Files) is det[private]

Files is the list of existing files or directories denoted by Document. Compound terms are handed to absolute_file_name/3, which deals with both aliases and Dir/File terms.

opener(-Command, +Options) is det[private]

Find the command to open a document. Command is either win_shell or a term Exe-Args, where Exe is the absolute path of the executable and Args are arguments that precede the document.

opener_executable(+Command, -Path) is semidet[private]

Path is the absolute file name of Command. A plain name is searched for on $PATH.

default_opener(-Command) is nondet[private]

Enumerate commands that may be able to open a document in the order we prefer them. Note that we must not use open on Linux, where this is an alias for openvt(1) rather than a document opener.

open_argument(+Command, +Options, +Argument) is det[private]

Run Command on a single URL or file name.

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:

The option opener(Command)
The Prolog flag desktop_opener if it is not default. It uses the same syntax as the opener(Command) option.
The Windows ShellExecute() API (see win_shell/2)
open on MacOS
cygstart (Cygwin), termux-open (Android/Termux) or wslview (WSL without a Linux desktop)
xdg-open (freedesktop.org), followed by the desktop specific gio, gnome-open, kde-open, kde-open5 and exo-open
wslview, handlr, mimeopen or run-mailcap
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.