Subcommand syntax highlighting

[JamesTeague]

Here is what I have

Here is what I am looking to do.

The argument or sub-command (honestly, not sure the proper term) should be highlighted a color. I am not sure which tweak to use to get that result or if this should be an enhancement request.

[DimiM99]

I have a similar issue where only first word in command is highlighted, the rest is not.

context:
oh-my-zsh
iTerm2
p10k
JetBrainsMonoNL NF

[danielshahaf]

The argument or sub-command (honestly, not sure the proper term)

Both terms are correct. An element of "$@" is an /argument/, as in the conventional C name "argv". In the context of a particular command, the argument which isn't a global option or an argument to a global option (yes, a different sense of the word "argument") is a /subcommand/.

should be highlighted a color. I am not sure which tweak to use to get that result or if this should be an enhancement request.

An enhancement request... and what would you expect the behaviour to be?

[danielshahaf]

Daniel Shahaf wrote on Wed, 22 Nov 2023 16:37 +00:00:

> The argument or sub-command (honestly, not sure the proper term) Both terms are correct. An element of "$@" is an /argument/, as in the conventional C name "argv". In the context of a particular command, the

first*

…

argument which isn't a global option or an argument to a global option (yes, a different sense of the word "argument") is a /subcommand/. > should be highlighted a color. I am not sure which tweak to use to get > that result or if this should be an enhancement request. An enhancement request... and what would you expect the behaviour to be?

[JamesTeague]

@danielshahaf the behavior I would expect that the first argument should be highlighted. Preferably, it would be highlighted if it was a valid argument. In the case of docker build docker gets highlighted as a command and build would too but something like docker buffer would not highlight the argument buffer. I understand that the add enhancement of being a valid sub-command may not be in the scope of this project. Coming from zsh-fast-syntax-highlighting and using zsh auto-completions, I thought this may be something that could be feasible.

[danielshahaf]

@danielshahaf the behavior I would expect that the first argument should be highlighted. Preferably, it would be highlighted if it was a valid argument. In the case of `docker build` docker gets highlighted as a command and `build` would too but something like `docker buffer` would not highlight the argument `buffer`.

Noting that the proposal is to "not highlight" as opposed to "highlight as an error". (Not advocating one option or the other; just pointing out the trade-off.)

I understand that the add enhancement of being a valid sub-command may not be in the scope of this project. Coming from [zsh-fast-syntax-highlighting](https://github.com/zdharma-continuum/fast-syntax-highlighting) and using zsh auto-completions, I thought this may be something that could be feasible.

It is indeed feasible, similar to the precommands handling ('sudo -u jrandom ls' highlights 'ls'). In principle, something like 'git -c foo.bar=baz pull' could highlight 'pull' too. It'd be nice to somehow derive this command syntax knowledge from completion functions, but that's a longer-term goal. (I can't find a ticket for it, but I think there is one.)

[mattmc3]

I have a similar issue where only first word in command is highlighted, the rest is not.

@DimiM99 - What you're seeing is the default behavior. From the docs:

main - the base highlighter, and the only one active by default.

If you want additional highlighters, add them to the ZSH_HIGHLIGHT_HIGHLIGHTERS array:

typeset -a ZSH_HIGHLIGHT_HIGHLIGHTERS=(
  main
  brackets
  regexp
  pattern
  line
  cursor
  root
)

Or, to add other 'main' highlighters, you need to do things like modify the ZSH_HIGHLIGHT_STYLES array:

# Highlight command flags (-f|--flag).
typeset -A ZSH_HIGHLIGHT_STYLES
ZSH_HIGHLIGHT_STYLES[single-hyphen-option]=fg=cyan
ZSH_HIGHLIGHT_STYLES[double-hyphen-option]=fg=blue

[mattmc3]

Subcommands are kinda tricky. How do you know whether something is a subcommand or simply a positional argument without coding in all the subcommands or calling out to the command? That's how fast-syntax-highlighting does it, but it's a maintenance burden. If you are okay with a simpler (naive) solution, you could simply assume the second word is always a subcommand if that word starts with [[:alnum:]] and contains no punctuation except dash/underscore. Perhaps a project maintainer can weigh-in on whether this is adequate for inclusion in this project and I'll submit a PR. In the meantime, you can just source this in your own .zshrc config:

# Highlight subcommands (the second word) in yellow.
ZSH_HIGHLIGHT_STYLES[subcommand]='fg=yellow'

# Whenever the buffer is modified, evaluate whether there's a subcommand.
_zsh_highlight_highlighter_subcommand_predicate() {
  _zsh_highlight_buffer_modified
}

_zsh_highlight_highlighter_subcommand_paint() {
  # Short-circuit check to ensure there are multiple words.
  local -a words=(${=BUFFER})
  (( $#words > 1 )) || return

  # Find the second word
  local startpos=0 pos=0 state=start char=
  for char in ${(s..)BUFFER}; do
    case $state in
      start)
        if [[ "$char" == [[:alnum:]] ]]; then
          state=cmd
        elif [[ "$char" == '#' ]]; then
          state=comment
          break
        fi
        ;;
      cmd)
        if [[ "$char" == [[:space:]] ]]; then
          state=whitespace
        fi
      ;;
      whitespace)
        if [[ "$char" == [[:alnum:]] ]]; then
          startpos=$pos
          state=subcmd
        elif [[ "$char" != [[:space:]] ]]; then
          # If the next word begins with a non-space, non-alnum char
          # (eg: punctuation), then it's likely a --flag, $var, ~/path,
          # or something else - not a proper subcommand
          state=none
          break
        fi
      ;;
      subcmd)
        if [[ "$char" == [[:space:]] ]]; then
          break
        elif [[ "$char" != [[:alnum:]] ]] && [[ "$char" != (-|_) ]]; then
          state=none
          break
        fi
      ;;
    esac
    (( ++pos ))
  done

  if [[ "$state" == subcmd ]] && (( $startpos < $pos )); then
    _zsh_highlight_add_highlight $startpos $pos 'subcommand'
  fi
}

# Add your custom subcommand highlighter
ZSH_HIGHLIGHT_HIGHLIGHTERS+=(subcommand)

Here's a visual:

[danielshahaf]

Subcommands are kinda tricky. How do you know whether something is a subcommand or simply a positional argument without coding in all the subcommands or calling out to the command?

By hardcoding all the supercommands that have subcommands, or asking the completion system, or "parsing" the man page, or having the command declare its argv syntax in some machine-parseable form [ideally, one that's independent of the language the command is implemented in, and can be designed in ways that don't require running the command, though I could also imagine solutions revolving around a "run the script with a mock getopt"].... For detecting supercommands, something along the lines of "There exist foo and bar such that ${command word}-foo and ${command word}-bar both exist as man pages and are not runnable" might be worth --- but more fanciness would be needed to determine whether 'lorem' or 'ipsum' is the subcommand in cases such as `git -c lorem ipsum`. Might wanna bring this up on zsh-users@, as this is also of interest to the others (including to implementing completions).

That's how fast-syntax-highlighting does it, but it's a maintenance burden. If you are okay with a simpler (naive) solution, you could simply assume the second word is always a subcommand if that word starts with `[[:alnum:]]` and contains no punctuation except dash/underscore.

Off-the-cuff: check whether it's a filename as well.

Perhaps a project maintainer can weigh-in on whether this is adequate for inclusion in this project and I'll submit a PR.

First of all, thanks for posting that. It's good to see people implementing highlighters. I don't think we have a policy (and, perhaps, not even a devs' consensus) on the inclusion criteria for new highlighters. This hasn't come up often. Thanks again for writing and sharing that highlighter :)

```zsh _zsh_highlight_highlighter_subcommand_paint() {

⋮

} ```

Looks like #327 would have been helpful here.