Open a URL in the default web browser from a MoonBit program, on macOS, Linux (including WSL) and Windows.

browser

open

url

cli

Download zip

Author

bobzhang

Version

0.1.0

License

Apache-2.0

Repository

github.com/bobzhang/open_in_browser

Last updated

20 hours ago

Downloads

Dependencies

moonbitlang/async0.22.4

#bobzhang/open_in_browser

Open a URL in the default web browser from a MoonBit program, on macOS, Linux (including WSL) and Windows. Works on the native and wasm (moonrun) targets.

moon add bobzhang/open_in_browser

async fn main {
  match @open_in_browser.open("http://127.0.0.1:8080/") {
    Launched => println("opened it in your browser")
    Skipped(why) => println("not opening a browser \{why}; open the link yourself")
    Failed(error) => println("could not open a browser (\{error})")
  }
}

open never blocks and never writes to your terminal. The opener is started detached and not waited on, and its output goes to the null device, so it is safe to call from a TUI.

#What it runs

Where	Command
$BROWSER set	each :-separated entry in turn (; on Windows); %s is replaced by the URL, otherwise the URL is appended
macOS	open <url>
Windows	rundll32 url.dll,FileProtocolHandler <url>: one argument, no shell, so ?, & and # are safe
Linux under WSL	wslview <url>, then explorer.exe <url>
Linux	xdg-open <url>

open is used only on macOS, because on Linux that name can belong to another program (openvt).

#When it does not try

Over SSH (SSH_CONNECTION or SSH_TTY set), where the browser would open on the remote machine: Skipped("over SSH").
On Linux without a display (no DISPLAY or WAYLAND_DISPLAY, and not WSL): Skipped("without a display").

Pass force=true to try anyway. $BROWSER is always honoured, since it is the user's own choice.

#API

open(url, force?, env?) -> Outcome (async): try the commands in order until one starts. env defaults to the process environment.
commands(platform, url, env~, force?) -> Result[Array[Array[String]], String]: the decision alone, without starting anything, to show or test.
Outcome: Launched, Skipped(reason) or Failed(error). Launched means an opener was started, not that a window appeared.

#License

Apache-2.0

Outcome

source

pub(all) enum Outcome {
  Launched
  Skipped(String)
  Failed(String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

What open did with a URL.

commands

source

fn commands(platform : @moonbitlang/async/types.Platform
Platform, url : String, env~ : Map[String, String], force? : Bool) -> Result[Array[Array[String]], String]

The commands that would open url in the default browser on platform, in the order to try them, or why not to try at all.

$BROWSER, when set, wins: a list of commands separated by : (; on Windows), tried in order. %s in a command is replaced by the URL; otherwise the URL is appended as the last argument.
Over SSH (SSH_CONNECTION or SSH_TTY set) nothing is tried, since the browser would open on the remote machine; force=true overrides this.
macOS: open <url>. On Linux open can be a different program (openvt), so it is never used there.
Windows: rundll32 url.dll,FileProtocolHandler <url>, which takes the URL as one argument with no shell in between, so ?, & and # are safe.
Linux under WSL: wslview <url>, then explorer.exe <url>, both of which open the Windows browser.
Other Linux: xdg-open <url> when there is a display (DISPLAY or WAYLAND_DISPLAY); without one nothing is tried unless force=true.

Blank environment values count as unset. This function only decides; it starts nothing, which makes it easy to test or to show to a user.

open

source

async fn open(url : String, force? : Bool, env? : Map[String, String]) -> Outcome

Open url in the default browser, best effort, without blocking.

The commands from commands are tried in order until one starts. Each is started detached and never waited on (some xdg-open setups run the browser itself in the foreground), with its output sent to the null device so nothing lands on a terminal the caller may own, such as a TUI. A missing command moves on to the next; the result says what happened.

env defaults to the process environment; pass one to decide from another.

match @open_in_browser.open("http://127.0.0.1:8080/") {
  Launched => println("opened it in your browser")
  Skipped(why) => println("not opening a browser \{why}")
  Failed(error) => println("could not open a browser: \{error}")
}