highlighter_compat_rules.yaml

# Strings used for the "problem" field in popups.
# Each value used for the "change" in the "issues" list must appear here
changes:
  # When a structure won't work until a later version
  added: Added in fish {}
  # When a structure won't behave the way the syntax highlighting shows until a later version
  behaviour: Behaviour changed in fish {}
  # When a structure was marked for removal
  deprecated: Deprecated in fish {}
  # When a structure was removed or intentionally broken
  removed: Removed in fish {}

# For now I'm only specifying version numbers to two fields (eg "3.0"), under
#   the assumption that patch releases (the third field) will never make
#   major changes. But, if that ever happens, the compatibility highlighter ought
#   to have no problem with it because internally I am always padding out the
#   version number to three fields with extra zeroes anyway

# List of conflicting structures between fish versions.
# Each issue must have one or more scope selectors ("selector") used to pick
#   candidate structures from the source file. The full text of each
#   structure (or the text captured after extending the range of the selector
#   by the positive integer "extend" number of characters in both directions)
#   is then tested against the given regular expression ("match").
#   Alternatively, if the expression is "true" then no testing is done
#   and the candidate is immediately accepted. (This is much more
#   efficient when possible, because essentially the regex matching is done
#   during syntax parsing and optimised by Sublime Text.)
#   If the candidate is accepted, then the fish version being
#   targeted by the plugin is compared to each individual state
#   throughout the "history" of the issue. If a conflict is determined
#   (eg, the plugin is targeting fish 2.7 but the issue history indicates
#   the structure was only added in fish 3.0) then the full extent of the
#   structure will be highlighted. Hovering over the region will reveal
#   the "hint" that suggests alternative structures to resolve the conflict
# Important to note: the order of issues is important, as it determines
#   which issue will be preferentially drawn in the (uncommon) event that two
#   or more issues can all describe the exact same region in a file
issues:
  op-cmdsub-in-str:
    selector: meta.interpolation.command meta.parens.command-substitution
    match: true
    history:
      - change: added
        version: 3.4
    hint: Use unquoted as <code>(... | string collect)</code>.

  op-cmdsub-with-dollar:
    selector: meta.parens.command-substitution.dollar punctuation.definition.variable
    match: true
    history:
      - change: added
        version: 3.4
    hint: Remove <code>$</code>.

  op-bang:
    selector: meta.function-call.name keyword.operator.word.bang
    match: true
    history:
      - change: added
        version: 3.0
    hint: Use <code>not</code>.

  op-ampersand-nobg-in-token:
    selector: meta.function-call.operator.control.ampersand
    extend: 1
    match: '\w\&[\w#]'
    history:
      - change: deprecated
        version: 3.4
    hint: Consider putting a separator before or after this symbol.

  op-double-ampersand:
    selector: meta.function-call.operator.control.double-ampersand
    match: true
    history:
      - change: added
        version: 3.0
    hint: Use <code>; and</code>.

  op-double-bar:
    selector: meta.function-call.operator.control.double-bar
    match: true
    history:
      - change: added
        version: 3.0
    hint: Use <code>; or</code>.

  op-newline-in-pipeline:
    selector: meta.function-call.operator.control.newline.ignored
    match: true
    history:
      - change: added
        version: 3.0
    hint: Insert <code>\</code>.

  op-stderr-nocaret-append:
    selector:
      - meta.function-call.operator.pipe.stderr.implicit keyword.operator.redirect.write.append
      - meta.function-call.operator.redirection.stderr.implicit keyword.operator.redirect.write.append
    match: true
    history:
      - change: deprecated
        version: 3.0
    hint: Consider using <code>2>></code>.

  op-stderr-nocaret-truncate:
    selector:
      - meta.function-call.operator.pipe.stderr.implicit keyword.operator.redirect.write.truncate
      - meta.function-call.operator.redirection.stderr.implicit keyword.operator.redirect.write.truncate
    match: true
    history:
      - change: deprecated
        version: 3.0
    hint: Consider using <code>2></code>.

  op-std-write-file-append:
    selector: meta.function-call.operator.redirection.std-write.append
    match: true
    history:
      - change: added
        version: 3.1
    # Whether you use 2>&1 or 2>>&1 makes no difference in fish
    hint: Use <code>&gt;&gt;file 2&gt;&amp;1</code>.

  op-std-write-file-truncate:
    selector: meta.function-call.operator.redirection.std-write.truncate
    match: true
    history:
      - change: added
        version: 3.1
    # Whether you use 2>&1 or 2>>&1 makes no difference in fish
    hint: Use <code>&gt;file 2&gt;&amp;1</code>.

  op-std-write-pipe:
    selector: meta.function-call.operator.pipe.std-write
    match: true
    history:
      - change: added
        version: 3.1
    hint: Use <code>2&gt;&amp;1 &gt;|</code>.

  op-qmark-noglob:
    selector: keyword.operator.question-mark
    match: true
    history:
      - change: deprecated
        version: 3.0
    hint: Consider using <code>*</code>.

  cmd-brace-expansion:
    selector: meta.function-call.name meta.braces.brace-expansion
    match: true
    history:
      - change: added
        version: 3.0
    hint: Try using <code>eval</code>.

  cmd-variable-expansion:
    selector: meta.function-call.name meta.variable-expansion
    match: true
    history:
      - change: added
        version: 3.0
    hint: Try using <code>eval</code>.

  cmd-environment:
    selector: meta.function-call.environment
    match: true
    history:
      - change: added
        version: 3.1
    # This is what `VAR=val cmd` is literally equivalent to
    hint: Use <code>begin set -lx VAR val; cmd; end</code>.

  # This can overlap with arg-braces-empty or arg-braces-non-empty, but it is a more serious issue (results in an error not a warning). Place it above them in this list so that it is drawn preferentially
  arg-braces-space:
    selector:
      - meta.braces.literal.empty.ignored-whitespace
      - meta.braces.literal.non-empty.ignored-whitespace
      - meta.braces.brace-expansion.ignored-whitespace
    match: true
    history:
      - change: added
        version: 3.0
    hint: Delete extra spaces.

  arg-braces-empty:
    selector: meta.braces.literal.empty
    match: true
    history:
      - change: behaviour
        version: 3.0
    hint: This will expand to an empty string and the braces disappear.

  arg-braces-non-empty:
    selector: meta.braces.literal.non-empty
    match: true
    history:
      - change: behaviour
        version: 3.1
    hint: This will expand to its contents and the braces disappear.

  arg-process-expansion-last:
    selector: meta.function-call.parameter.argument.process-expansion.last
    match: true
    history:
      - change: removed
        version: 3.0
    hint: Use <code>$last_pid</code>.

  arg-process-expansion:
    selector: meta.function-call.parameter.argument.process-expansion.other
    match: true
    history:
      - change: removed
        version: 3.0
    hint: Try using <code>pgrep</code>, etc.