Common Interfaces

The plugin API is exposed through objects in the global namespace:

plugin

Provides version and system information attributes, utility methods, and the registration methods used to create plugin features.

console

Provides logging methods.

Logging

console.log(message)

Creates a log message at the info level containing the plugin's name in square brackets followed by the given message string.

console.info(message)

Same as console.log().

console.warn(message)

As console.log(), but creates the log message at the warning level.

Constants

plugin.majorVersion

The major version of the plugin API. Check this value before registering any features to ensure that the plugin is compatible with the plugin API.

plugin.minorVersion

The minor version of the plugin API. Check this value if the plugin depends on a particular interface introduced by a minor revision of the plugin API.

plugin.installPrefix

The install prefix configured when qtermy was built. Useful for plugins which need to reference files or paths relative to the install location.

plugin.installDatadir

(API version 1.3) The install datadir configured when qtermy was built.

plugin.installConfdir

(API version 1.3) The install sysconfdir configured when qtermy was built.

Properties

plugin.pluginName

Assign the name of the plugin to this property before registering any features. It will be shown in the Manage Plugins window and in log messages. If unset, the name of the plugin's source file will be used.

plugin.pluginVersion

Assign the version of the plugin to this property before registering any features. It will be shown in the Manage Plugins window but is otherwise not used by the plugin system.

plugin.pluginDescription

Assign a brief, one line description of the plugin to this property before registering any features. It will be shown in the Manage Plugins window but is otherwise not used by the plugin system.

Methods

plugin.now()

Returns a timestamp value representing the current time, measured in tenths of a second. This can be used to compare relative times.

plugin.htmlEscape(string)

Returns the given string with HTML metacharacters replaced by the appropriate HTML entities.

plugin.registerSemanticParser(version, name, callback[, variant])

Registers a semantic parser feature. The variant argument specifies the parser type and is one of:

  • 0: a standard parser (the default)
  • 1: a fast parser
Arguments:
  • version (integer) -- The requested interface version (must be 1). Future revisions of the API may introduce new versions.
  • name (string) -- The name of the parser being registered.
  • callback (function) -- The parser's match function.
  • variant (integer) -- The type of parser being registered.
plugin.registerCustomAction(version, name, callback[, description])

Registers a custom action feature.

Arguments:
  • version (integer) -- The requested interface version (must be 1). Future revisions of the API may introduce new versions.
  • name (string) -- The name of the action. To invoke the action from a key binding or elsewhere within qtermy, prepend "Custom" to this name.
  • callback (function) -- The action's run function.
  • description (string) -- A brief, one line description of the action. This will be displayed in tooltips but is otherwise not used by the plugin system. If unspecified, the value of plugin.pluginDescription is used.
plugin.registerTipProvider(version, callback)

Registers a tip of the day provider. There can only be one of these registered.

Arguments:
  • version (integer) -- The requested interface version (must be 1). Future revisions of the API may introduce new versions.
  • callback (function) -- The tip provider's tip function.

File Interface

plugin.createOutputFile(filename)

Creates and opens a file for writing, overwriting any existing file with the same name. The file is created in the DownloadLocation specified in the global settings. An Error exception is thrown on open failure. Otherwise, a handle object is returned with attributes and methods described below.

fileHandle.path

The path of this handle's file.

fileHandle.print(value)

Writes the given value to this handle's file as UTF-8 text. No newline is added to the printed string.

fileHandle.close()

Closes this handle's file. This is required; file handles are not closed implicitly.