docs » URLDispatcher

Route URLs to different applications with pattern matching

Download: https://github.com/Hammerspoon/Spoons/raw/master/Spoons/URLDispatcher.spoon.zip

Sets Hammerspoon as the default browser for HTTP/HTTPS links, and dispatches them to different apps according to the patterns defined in the config. If no pattern matches, default_handler is used.

API Overview

API Documentation

Variables

decode_slack_redir_urls
Signature URLDispatcher.decode_slack_redir_urls
Type Variable
Description

If true, handle Slack-redir URLs to apply the rule on the destination URL. Defaults to true

Source Source/URLDispatcher.spoon/init.lua
default_handler
Signature URLDispatcher.default_handler
Type Variable
Description

Bundle ID for default URL handler. (Defaults to "com.apple.Safari")

Source Source/URLDispatcher.spoon/init.lua
logger
Signature URLDispatcher.logger
Type Variable
Description

Logger object used within the Spoon. Can be accessed to set the default log level for the messages coming from the Spoon.

Source Source/URLDispatcher.spoon/init.lua
set_system_handler
Signature URLDispatcher.set_system_handler
Type Variable
Description

If true, URLDispatcher set itself as system handler for http requests. Defaults to true

Source Source/URLDispatcher.spoon/init.lua
url_patterns
Signature URLDispatcher.url_patterns
Type Variable
Description

URL dispatch rules. A table containing a list of dispatch rules. Each rule should be its own table in the format: { "url pattern", "application bundle ID", "function" }, and they are evaluated in the order they are declared. Note that the patterns are Lua patterns and not regular expressions. Defaults to an empty table, which has the effect of having all URLs dispatched to the default_handler. If "application bundle ID" is specified, that application will be used to open matching URLs. If no "application bundle ID" is specified, but "function" is provided (and is a Lua function) it will be called with the URL.

Source Source/URLDispatcher.spoon/init.lua
url_redir_decoders
Signature URLDispatcher.url_redir_decoders
Type Variable
Description

List containing optional additional redirection decoders (other than the known Slack decoder, which is enabled by URLDispatcher.decode_slack_redir_urls to apply to URLs before dispatching them. Each list element must be a list itself with four elements:

  • String: a name to identify the decoder;
  • String: a Lua pattern to match against the URL;
  • String: a replacement pattern to apply if a match is found;
  • (optional) Boolean: whether to skip URL-decoding of the resulting string (by default the results are always decoded);
  • (optional) String or Table: a pattern or list of patterns to match against the name of the application from which the URL was opened. If this parameter is present, the decoder will only be applied when the application matches. Default is to apply the decoder regardless of the application. The first two values are passed as arguments to string.gsub applied on the original URL. Default value: empty list
Source Source/URLDispatcher.spoon/init.lua

Methods

dispatchURL
Signature URLDispatcher:dispatchURL(scheme, host, params, fullUrl)
Type Method
Description

Dispatch a URL to an application according to the defined url_patterns.

Parameters:

  • scheme - A string containing the URL scheme (i.e. "http")
  • host - A string containing the host requested (e.g. "www.hammerspoon.org")
  • params - A table containing the key/value pairs of all the URL parameters
  • fullURL - A string containing the full, original URL. This is the only parameter used in this implementation.

Notes:

Source Source/URLDispatcher.spoon/init.lua
start
Signature URLDispatcher:start()
Type Method
Description

Start dispatching URLs according to the rules

Parameters:

  • None
Source Source/URLDispatcher.spoon/init.lua