▼Net:   Networking Libraries
On this page:
send-url
send-url/  file
send-url/  contents
send-url/  mac
external-browser
browser-preference?
unix-browser-list
  top  ← prev  up  next → 

5 Send URL: Opening a Web Browser

 (require net/sendurl) package: net-lib
Provides send-url for opening a URL in the user’s chosen web browser.

See also browser/external, which requires racket/gui, but can prompt the user for a browser if no browser preference is set.

procedure

(send-url str    
  [separate-window?    
  #:escape? escape?]) → void?
  str : string?
  separate-window? : any/c = #t
  escape? : any/c = #t
Opens str, which represents a URL, in a platform-specific manner. For some platforms and configurations, the separate-window? parameter determines if the browser creates a new window to display the URL or not.

On Mac OS, send-url calls send-url/mac.

If escape? is true, then str is escaped (by UTF-8 encoding followed by “%” encoding) to avoid dangerous shell characters: single quotes, double quotes, backquotes, dollar signs, backslashes, non-ASCII characters, and non-graphic characters. Note that escaping does not affect already-encoded characters in str.

On all platforms, the external-browser parameter can be set to a procedure to override the above behavior, and the procedure will be called with the URL str.

procedure

(send-url/file path    
  [separate-window?    
  #:fragment fragment    
  #:query query]) → void?
  path : path-string?
  separate-window? : any/c = #t
  fragment : (or/c string? false/c) = #f
  query : (or/c string? false/c) = #f
Similar to send-url (with #:escape? #t), but accepts a path to a file to be displayed by the browser, along with optional fragment (with no leading #) and query (with no leading ?) strings. Use send-url/file to display a local file, since it takes care of the peculiarities of constructing the correct file:// URL.

The path, fragment, and query arguments are all encoded in the same way as a path provided to send-url, which means that already-encoded characters are used as-is.

procedure

(send-url/contents contents    
  [separate-window?    
  #:fragment fragment    
  #:query query    
  #:delete-at seconds]) → void?
  contents : string?
  separate-window? : any/c = #t
  fragment : (or/c string? false/c) = #f
  query : (or/c string? false/c) = #f
  seconds : (or/c number? false/c) = #f
Similar to send-url/file, but it consumes the contents of a page to show and displays it from a temporary file.

When send-url/content is called, it scans old generated files (this happens randomly, not on every call) and removes them to avoid cluttering the temporary directory. If the #:delete-at argument is a number, then the temporary file is more eagerly removed after the specified number of seconds; the deletion happens in a thread, so if Racket exits earlier, the deletion will not happen. If the #:delete-at argument is #f, no eager deletion happens, but old temporary files are still deleted as described above.

procedure

(send-url/mac url [#:browser browser]) → void?

  url : string?
  browser : (or/c string? #f) = #f
Like send-url, but only for use on a Mac OS machine.

The optional browser argument, if present, should be the name of a browser installed on the system. For example,

(send-url/mac "https://www.google.com/" #:browser "Firefox")

would open the url in Firefox, even if that’s not the default browser. Passing #f means to use the default browser.

parameter

(external-browser) → browser-preference?

(external-browser cmd) → void?
  cmd : browser-preference?
A parameter that can hold a procedure to override how a browser is started, or #f to use the default platform-dependent command.

On Unix, the command that is used depends on the 'external-browser preference. It’s recommended not to use this preference, but to rely on xdg-open. If the preference is unset, send-url uses the first of the browsers from unix-browser-list for which the executable is found. Otherwise, the preference should hold a symbol indicating a known browser (from the unix-browser-list), or it a pair of a prefix and a suffix string that are concatenated around the url string to make up a shell command to run. In addition, the external-browser paremeter can be set to one of these values, and send-url will use it instead of the preference value.

Note that the URL is encoded to make it work inside shell double-quotes: URLs can still hold characters like #, ?, and &, so if the external-browser is set to a pair of prefix/suffix strings, they should use double quotes around the url.

If the preferred or default browser can’t be launched, send-url fails. See get-preference and put-preferences for details on setting preferences.

procedure

(browser-preference? a) → boolean?

  a : any/c
Returns #t if v is a valid browser preference, #f otherwise. See external-browser for more information.

value

unix-browser-list : (listof symbol?)

A list of symbols representing Unix executable names that may be tried in order by send-url. The send-url function internally includes information on how to launch each executable with a URL.

  top  ← prev  up  next →