Semantic Parser

A Semantic Parser is a plugin feature that creates semantic regions within the output of matching jobs. Only terminals with shell integration enabled can make use of semantic parsers. It is also necessary for scrollback fetch to be enabled for semantic parsers to work.

The semantic regions created by parsers may specify:

  • An icon and tooltip to be displayed when hovering over the region with the mouse pointer.
  • A URL associated with the region. If it is a file:// URL, it will become the selected file in the Files tool when the region is clicked.
  • Texts that will be used in drag-and-drop operations when the region is dragged with the mouse.
  • A primary action string. By default, this will be invoked when the region is double-clicked although this can be changed via global settings.
  • A customized context menu containing additional action entries. Menu entries may specify a confirmation prompt which will be displayed to the user before invoking the entry. In the case of a semantic region representing a file, the predefined context menu used in the Files tool can replace or serve as a parent menu for the region's context menu.

Two variants of semantic parser are supported:

  • A standard parser waits until the entire output of the job is available and the command's exit status is known. The parser's start method is called and may use the exit status to decide whether to proceed with output parsing.
  • A fast parser processes each line of output immediately without waiting for the job to finish. The parser's start method is not called. This is a good choice for long-running commands such as make.

Smart hyperlinks are an alternative method of creating semantic regions that does not rely on the plugin system, shell integration, nor on the parsing of command output.

The file parser.mjs.example distributed with qtermy implements a sample semantic parser and is annotated with explanatory comments. Here are some tips for developing a new semantic parser:

  • After reloading the parser plugin from the Manage Plugins window, run a new command to test it. Jobs that have already finished will not be re-parsed.
  • A job that scrolls off the top of the scrollback buffer will not be parsed. The entire job must be within the scrollback buffer and all of its output must have been downloaded by qtermy. Increase the scrollback size if necessary.
  • It may be helpful to bind the HighlightSemanticRegions action to a key in the keymap. This will make it possible to view the regions generated by the semantic parser without moving the mouse pointer around.
  • A semantic region's text can be selected by Shift-clicking it, although this can be changed via global settings.

Control Flow

The entry point to a semantic parser is the match function passed to plugin.registerSemanticParser() which is called once for each job:

match_function(context, cmdline, cmddir)
Arguments:
  • context (object) -- Contains methods used to query for information about the job.
  • cmdline (string) -- The job's command, which is a non-empty string with leading and trailing whitespace removed.
  • cmddir (string) -- The job's directory as reported by shell integration.
Returns:

An object, or null to skip the job.

The match function must examine its arguments and decide whether to parse the output of the job. If not, the match function must return null. Otherwise, the match function must return an object which defines additional callback methods, described below. The returned object may also contain arbitrary private fields for the parser's own use. For protection against future API changes, name private fields starting with an underscore (_) character. The match function may use the methods of the provided match context object to query for various information about the job.

The object returned from the match function must define the following callback methods:

parser.start(context, exitcode, nrows)

Called once to begin output processing, unless the parser is a fast parser in which case this method is not called.

Arguments:
  • context (object) -- Reserved for future use.
  • exitcode (integer) -- The exit status of the job as reported by shell integration.
  • nrows (integer) -- The total size of the output in terminal rows. Note that there may be fewer output lines since a single line might wrap across multiple rows.
Returns:

true to proceed with output processing, false to skip the job.
parser.process(context, text, startRow, endRow)

Called once for each line of output in the job. Note that a newline character printed at the end of the output (before the next prompt) is considered an empty line.

Arguments:
  • context (object) -- Contains methods used to create regions.
  • text (string) -- The text of the line without a trailing newline.
  • startRow (integer) -- The row number on which the line starts.
  • endRow (integer) -- The row number on which the line ends.
Returns:

true to continue processing, false to stop processing and skip the finish method.
parser.finish(context, nrows)

Called once at the end of output processing.

Arguments:
  • context (object) -- Contains methods used to create regions.
  • nrows (integer) -- Same as that passed to the start method.

Match Context

matchContext.getJobId()

Returns the region ID of the incoming job.

matchContext.getJobAttribute(name)

Returns the value of the named job attribute, or undefined if it doesn't exist.

matchContext.getTerminalId()

Returns the UUID of the job's terminal.

matchContext.getTerminalAttribute(name)

Returns the value of the named terminal attribute, or undefined if it doesn't exist.

matchContext.getServerId()

Returns the UUID of the job's server.

matchContext.getServerAttribute(name)

Returns the value of the named server attribute, or undefined if it doesn't exist.

Process Context

processContext.createRegion(startCol, endCol[, regionParams])

Creates a semantic region in the current output line using the given region parameters. This can only be called from the process method.

Arguments:
  • startCol (integer) -- The starting offset of the region within the line.
  • endCol (integer) -- The ending offset of the region within the line.
  • regionParams (object) -- An optional object containing region parameters as fields.
Returns:

The region ID of the new semantic region.
processContext.createRegionAt(startRow, startCol, endRow, endCol[, regionParams])

Creates a semantic region with the given bounds, using the given region parameters.

Arguments:
  • startRow (integer) -- The starting row number of the region.
  • startCol (integer) -- The starting offset of the region within the starting line.
  • endRow (integer) -- The ending row number of the region.
  • endCol (integer) -- The ending offset of the region within the ending line.
  • regionParams (object) -- An optional object containing region parameters as fields.
Returns:

The region ID of the new semantic region.
processContext.nextRegionId()

Returns the region ID of the region that will be created by the next call to createRegion or createRegionAt. This is for the case where the region ID is needed by the region's own parameters.

Region Parameters

All fields are optional.

regionParams.icon

The name of the region's icon. An SVG file with the specified name will be loaded from $HOME/.local/share/qtermy/images/semantic and prefix/share/qtermy/images/semantic in that order. If no such file is found, the name "default" is used which normally results in an empty icon.

regionParams.tooltip

The region's tooltip text.

regionParams.uri

A URL associated with the region.

regionParams.action1

The region's primary action string.

regionParams.drag

The region's drag-and-drop data. This is a dictionary object whose keys are MIME types and whose values are the associated data. Only textual data is supported.

regionParams.menu

The region's menu. This is a list of menu entries. Each menu entry is itself a list of between 1 and 5 values, with the first value specifying the type of menu entry:

  • 0: A separator.

  • 1: An ordinary menu item. The next 4 values in the entry are:

    • The action string to invoke
    • The menu item's text
    • The menu item's icon, which names an icon in the configured IconTheme.
    • The menu item's tooltip

  • 2: Attaches a confirmation prompt to the menu item immediately preceding this entry. The next value in the entry is the prompt to display.

  • 5: Specifies that the region's menu should inherit from the predefined context menu used in the Files tool. If used, this must be the first entry in the menu. The second value in the entry is the file:// URL of the region's file. The third value is an optional submenu name. Any further menu entries will be added to a submenu of the file context menu with this name.