Compatibility highlighter

This plugin complements the regular syntax highlighting by outlining any structures in a script that are considered to be an issue given the version of fish which will execute the script (the target version). You may hover the mouse over an outline to view a popup with information on the particular issue, and a hint for how to resolve it.

Issues that will be outlined by default (see Turn off for some parts of files) include:

• Syntax that is incompatible with the target fish version.
• Syntax that underwent significant changes in behaviour in later fish releases (eg, how {} is handled in 3.0 compared to 2.7). See the syntax philosophy for why this is the case.
• Syntax that has been deprecated (eg, redirection with the caret ^ as of fish 3.0).

The target fish version for a given file is the first number found when checking locations in the following order:

1. Local version setting. May exist, per-file.
2. Global version setting. Must exist. By default, reads the version number from the system fish binary.

Note: The local version setting is optional, and the global version setting has a reasonable default, so you should not need to worry about these unless you edit and execute your scripts on different machines with different versions of fish (or which don't have fish at all).

You can tweak the colours of the issue outlines and the display of the popup. See Customise the formatting.

Turn off for all files

(Modify via fish settings.) The compatibility highlighter is enabled by default. To disable it, remove compatibility from the enabled_highlighters list. To enable it again, add the string back.

Turn off for some files

(Modify via fish settings.) The highlighter is active in every file except for the files in the blacklist. To prevent the highlighter running on a certain file, add the basename (that is, the filename with leading directory components removed) to the highlighter_blacklist list. There is currently no support for globbing characters (*, ?) or regular expressions in the blacklist.

Turn off for some parts of files

(Modify via fish settings.) All types of issues are highlighted by default. To disable a particular type of issue, remove it from the compat_highlighter_types list. The current issue types are:

• error: Structure doesn't exist in target fish version.
• behaviour: Structure behaves differently in target fish version than the regular syntax highlighting indicates.
• deprecated: Structure is deprecated as of target fish version.

Use of the status bar

(Modify via fish settings; see status bar explanation under highlighter_show_status.) The status bar message takes the form Fish compatibility highlighter (<info>). If there are no issues in the current document, then <info> will be "✔". If there are issues in the current document, then <info> will be a short list of the number of errors, behaviour warnings, and deprecations that have been identified. The status bar message is only "critical" (as defined by highlighter_show_status) in the latter case, so use this setting if you prefer that the message only appear when it has something important to tell you.

Global fish version

(Modify via fish settings.) The compat_highlighter_fish_version setting must be set to a specific fish version number, or the word auto.

The version number must take the form X[.Y[.Z]] where components in brackets [] are optional, . represents a literal period, and X/Y/Z are positive integers. If Y or Z are not specified, they are assumed to be zero.

If the setting is auto, then the plugin will test the output of fish --version. If fish is installed in a nonstandard location on your system, then you must manually configure its install directory by setting fish_directory.

Local fish version

A version number may be given on the first line of the file (typically within a comment, to avoid it being parsed as a command in the script). This will always override the global version setting.

The entire line will be scanned for a string of the form fishX[.Y[.Z]] where components in brackets [] are optional, . represents a literal period, and X/Y/Z are positive integers. If Y or Z are not specified, they are assumed to be zero.

Example scripts using the local version setting:

# fish2.7
# Highlighter will assume fish 2.7.0
...

#!/usr/bin/env fish3
# Highlighter will assume fish 3.0.0
# This approach not recommended for executable files unless a binary called fish3 exists
...

Customise the formatting

Outlines

The outlines for different types of issues are given by your colour scheme. It is quite straightforward to change the colour of the outline for a certain type of issue; refer to the official Sublime Text documentation on the topic of customising colour schemes.

The scope names to use in your rules to target specific outlines are as follows:

Issue type	Scope name
error	invalid.illegal.compatibility.error.fish
behaviour	invalid.illegal.compatibility.warning.fish
deprecated	invalid.deprecated.compatibility.fish

Note that your colour scheme is likely (or in the case of the defaults, definitely) defining colours for invalid.illegal and invalid.deprecated already. You could override those more general scopes if you wish, but you probably only want to modify the colour for these specific outlines in this specific context, in which case it's advised to use the most specific scope name possible.

Popups

The popup which appears when you hover over an outlined issue can have its formatting modified by a CSS global setting, but this is not trivial. The body has ID compatibility_highlight, the first two lines of the popup are a div of class problem, and the final line is a div of class hint. Good luck.

(If there's a problem with how the popup is rendered on your system, feel free to open a new issue and we can explore a better way to fix it than local customisations.)