diff options
Diffstat (limited to 'lib/pure/browsers.nim')
| -rw-r--r-- | lib/pure/browsers.nim | 112 |
1 files changed, 88 insertions, 24 deletions
diff --git a/lib/pure/browsers.nim b/lib/pure/browsers.nim index c6a603318..59e2078df 100644 --- a/lib/pure/browsers.nim +++ b/lib/pure/browsers.nim @@ -9,40 +9,104 @@ ## This module implements a simple proc for opening URLs with the user's ## default browser. +## +## Unstable API. -import strutils +import std/private/since # used by the deprecated `openDefaultBrowser()` + +import std/strutils + +when defined(nimPreviewSlimSystem): + import std/assertions when defined(windows): - import winlean + import std/winlean + when defined(nimPreviewSlimSystem): + import std/widestrs + from std/os import absolutePath else: - import os, osproc + import std/os + when not defined(osx): + import std/osproc + +const osOpenCmd* = + when defined(macos) or defined(macosx) or defined(windows): "open" else: "xdg-open" ## \ + ## Alias for the operating system specific *"open"* command, + ## `"open"` on OSX, MacOS and Windows, `"xdg-open"` on Linux, BSD, etc. + +proc prepare(s: string): string = + if s.contains("://"): + result = s + else: + result = "file://" & absolutePath(s) + +proc openDefaultBrowserRaw(url: string) = + ## note the url argument should be alreadly prepared, i.e. the url is passed "AS IS" -proc openDefaultBrowser*(url: string) = - ## opens `url` with the user's default browser. This does not block. - ## - ## Under Windows, ``ShellExecute`` is used. Under Mac OS X the ``open`` - ## command is used. Under Unix, it is checked if ``gnome-open`` exists and - ## used if it does. Next attempt is ``kde-open``, then ``xdg-open``. - ## Otherwise the environment variable ``BROWSER`` is used to determine the - ## default browser to use. when defined(windows): - when useWinUnicode: - var o = newWideCString("open") - var u = newWideCString(url) - discard shellExecuteW(0'i32, o, u, nil, nil, SW_SHOWNORMAL) - else: - discard shellExecuteA(0'i32, "open", url, nil, nil, SW_SHOWNORMAL) + var o = newWideCString(osOpenCmd) + var u = newWideCString(url) + discard shellExecuteW(0'i32, o, u, nil, nil, SW_SHOWNORMAL) elif defined(macosx): - discard execShellCmd("open " & quoteShell(url)) + discard execShellCmd(osOpenCmd & " " & quoteShell(url)) else: - const attempts = ["gnome-open ", "kde-open ", "xdg-open "] var u = quoteShell(url) - for a in items(attempts): - if execShellCmd(a & u) == 0: return - for b in getEnv("BROWSER").string.split(PathSep): + if execShellCmd(osOpenCmd & " " & u) == 0: return + for b in getEnv("BROWSER").split(PathSep): try: - # we use ``startProcess`` here because we don't want to block! - discard startProcess(command=b, args=[url], options={poUsePath}) + # we use `startProcess` here because we don't want to block! + discard startProcess(command = b, args = [url], options = {poUsePath}) return except OSError: discard + +proc openDefaultBrowser*(url: string) = + ## Opens `url` with the user's default browser. This does not block. + ## The URL must not be empty string, to open on a blank page see `openDefaultBrowser()`. + ## + ## Under Windows, `ShellExecute` is used. Under Mac OS X the `open` + ## command is used. Under Unix, it is checked if `xdg-open` exists and + ## used if it does. Otherwise the environment variable `BROWSER` is + ## used to determine the default browser to use. + ## + ## This proc doesn't raise an exception on error, beware. + ## + ## ```nim + ## block: openDefaultBrowser("https://nim-lang.org") + ## ``` + doAssert url.len > 0, "URL must not be empty string" + openDefaultBrowserRaw(url) + +proc openDefaultBrowser*() {.since: (1, 1), deprecated: + "not implemented, please open with a specific url instead".} = + ## Intends to open the user's default browser without any `url` (blank page). + ## This does not block. + ## Intends to implement IETF RFC-6694 Section 3, + ## ("about:blank" is reserved for a blank page). + ## + ## Beware that this intended behavior is **not** implemented and + ## considered not worthy to implement here. + ## + ## The following describes the behavior of current implementation: + ## + ## - Under Windows, this will only cause a pop-up dialog \ + ## asking the assocated application with `about` \ + ## (as Windows simply treats `about:` as a protocol like `http`). + ## - Under Mac OS X the `open "about:blank"` command is used. + ## - Under Unix, it is checked if `xdg-open` exists and used \ + ## if it does and open the application assocated with `text/html` mime \ + ## (not `x-scheme-handler/http`, so maybe html-viewer \ + ## other than your default browser is opened). \ + ## Otherwise the environment variable `BROWSER` is used \ + ## to determine the default browser to use. + ## + ## This proc doesn't raise an exception on error, beware. + ## + ## ```nim + ## block: openDefaultBrowser() + ## ``` + ## + ## **See also:** + ## + ## * https://tools.ietf.org/html/rfc6694#section-3 + openDefaultBrowserRaw("about:blank") # See IETF RFC-6694 Section 3. |