introducing a help command

[MisterHW]

I was asked to add a help mechanism to list all currently supported scpi commands. Hopefully I haven't overlooked another implementation somewhere. I'd love to hear your thoughts on the approach described below. I feel it's a trade-off between conformity and readability.

Here's what the user sees in a PuTTY session:

The implementation is rather straight-forward:

static scpi_result_t My_HelpQ(scpi_t * context) {
    int i = 0;
    for(;;){
        SCPI_ResultCharacters(context, "\r\n", 2);
        SCPI_ResultMnemonic(context, scpi_commands[i].pattern);
        if(scpi_commands[++i].pattern == NULL){
            break;
        }
    }
    return SCPI_RES_OK;
}

const scpi_command_t scpi_commands[] = {
    {.pattern = "HELP", .callback = My_HelpQ,},
    {.pattern = "HELP?", .callback = My_HelpQ,},
// ...

Now I would expect the pattern strings would need to be returned in quotes, but then again it's most likely a human operator that opened the connection exclusively, so one would in turn even want to do away with the comma separation.

Going one step further even, one might be tempted to add short description strings where commands are not completely clear to the new user, and print them next to the listed commands.

_scpi_command_t would need to be changed to

    struct _scpi_command_t {
        const char * pattern;
        scpi_command_callback_t callback;
#if USE_COMMAND_TAGS
        int32_t tag;
#endif 
#if USE_COMMAND_DESCRIPTIONS
        const char * description;
#endif 
    };

[j123b567]

SCPI-99 is standard with some fixed structure of requests and responses. Even if it has text commands, it is not supposed to be used by humans directly.

E.g. exactly one newline character at the end of the command is expected and exactly one newline character is expected in the response. Exception os only ARBITRARY COMMAND DATA which has special header to allow any binary data, but the header also specify how much data it will contains.

Of course, you can have any nonstandard modification in your product but it is unlikely that it will be part of the library itself.

[MisterHW]

I re-implemented the HELP mechanism with block data. Still working on it a bit and cleaning up.

The optional description mechanism is backward compatible and allows informing the user which arguments are expected. Short explanations can be added to describe the exact scope and use of each command.

Some PC tools allow sending raw SCPI commands. When a program uses HELP, it could use the returned list of commands to populate a drop-down box or show the command list as a table.

The newline characters are absorbed into the ends of each block and should thus not be caught by the parser.

ps. is comma separation required? I think that's the last compliance issue to be addressed. I've only found one reference (in scpi-99, 6.2.3.4) pertaining to multiple blocks, and it appears they need to be treated the same as numerical values.

[MisterHW]

After looking at the delimiter question some more I think it's appropriate to harmonize SCPI_ResultArbitraryBlockHeader() by making it insert a delimiter where needed.

https://github.com/j123b567/scpi-parser/pull/134 adds this behaviour, plus some minor clean-up. https://github.com/j123b567/scpi-parser/pull/134 becomes a prerequisite for #129.

[MisterHW]

I might have to re-write strncasestrn(), but I've got a branch with a USE_SEARCH_FILTER feature which treats an optional string in

HELP? [<string>]

as a filter to narrow down the HELP? output:

[MisterHW]

@j123b567 the HELP? enhancement has served me well in recent months. It's really convenient in the lab when setting up and verifying configurations. I don't have to worry about versions of documentation to boards I've given to colleagues either. The search function is also merged so you can review #135 directly. Hopefully we can conclude this PR in 2022 and I can get it out of my mind ;) Looking forward to your reply.