[BUG] Syntax of command arg with token and multiple (e.g. CLIENT LIST)

[zuiderkwast]

This is about command arguments specified in the JSON file with these properties:

• a "token" property,
• a "type" that is not "pure-token" and
• "multiple": true
• ("optional": true in the examples below, but otherwise, it just affects the use of [ ] vs < >)

For arguments like this, the token is displayed as to be repeated for each argument.

Example: The CLIENT LIST has this argument in the JSON file:

        {
            "name": "client-id",
            "token": "ID",
            "type": "integer",
            "optional": true,
            "multiple": true,
            "since": "6.2.0"
        }

It is presented on the command web page like this:

CLIENT LIST [ TYPE normal | master | replica | pubsub ] [ ID client-id ] [ [ ID client-id ] ... ] 

Expected behaviour

The expected behaviour is that ID only appears once, e.g.

CLIENT LIST [TYPE <NORMAL | MASTER | REPLICA | PUBSUB>] [ID client-id [client-id...]]

Additional

There's an exception: If the argument has "multiple_token": true, then the token should actually be repeated. An example is the SORT command, which is already rendered correctly on the website, with GET get-pattern repeated as a whole:

SORT key [ BY by-pattern ] [ LIMIT offset count ] [ GET get-pattern ] [ [ GET get-pattern ] ... ] [ asc | desc ] [ sorting ] [ STORE destination ] 

[stockholmux]

Okay. I took some time on this. I think there are two distinct issues here. I'll all them "non-pure token multiples" and "< > in optional" for this issue.

non-pure token multiples

Given the criteria in the issue, I found seven commands that would be affected. With my changes, I get:

• CLIENT LIST [ TYPE normal | master | replica | pubsub ] [ ID client-id [client-id ... ] ]
• MIGRATE host port 〈 key | empty-string 〉 destination-db timeout [ copy ][ replace ][ AUTH auth | AUTH2 username password ] [ KEYS keys [keys ... ] ]
• ZINTER numkeys key [ key ... ] [ WEIGHTS weight [weight ... ] ][ AGGREGATE sum | min | max ][ withscores ]
• ZINTERSTORE destination numkeys key [ key ... ] [ WEIGHTS weight [weight ... ] ][ AGGREGATE sum | min | max ]
• ZUNION numkeys key [ key ... ] [ WEIGHTS weight [weight ... ] ][ AGGREGATE sum | min | max ][ withscores ]
• ZUNIONSTORE destination numkeys key [ key ... ] [ WEIGHTS weight [weight ... ] ][ AGGREGATE sum | min | max ]

The above 6 all compare closely to valkey-cli HELP <command>, the 7th doesn't look right:

MODULE LOADEX path [ CONFIG name value ][ [ CONFIG name value ] ... ] [ ARGS args [args ... ] ]

I need to look into MODULE LOADEX since it meets the criteria in this issue but CONFIG arguments aren't rendering as I expect, so there is something else. I personally don't find that as wrong as the repeating token in the other 6.

< > in optional

I have questions here. While these are in the website parser, I did notice that valkey-cli doesn't use < >. For example,

$ valkey-cli help client list

  CLIENT LIST [TYPE NORMAL|MASTER|REPLICA|PUBSUB] [ID client-id [client-id ...]]
  summary: Lists open connections.
  since: 2.4.0
  group: connection

This matches my parsers output, save for a bit of (irrelevant) spacing differences. I'm guessing the man pages do have [TYPE < NORMAL|MASTER|REPLICA|PUBSUB >].

IMHO, we should probably break this bit out into a new issue and harmonize the use < > across CLI, man pages, and website.

Side quest: debugging across all the commands

As part of the fix for this, I implemented a 'cheatsheet' page that has the syntax for all commands in alphabetical order on one single page. I was using this to compare changes as I made alterations to the parser and to avoid unintended consequences. Honestly, it's pretty handy for both this type of debugging and as a quick reference; I may break this out into a seperate PR.