Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

introducing a help command #129

Open
MisterHW opened this issue Nov 7, 2021 · 5 comments · May be fixed by #135
Open

introducing a help command #129

MisterHW opened this issue Nov 7, 2021 · 5 comments · May be fixed by #135
Labels
enhancement

Comments

@MisterHW
Copy link
Contributor

MisterHW commented Nov 7, 2021

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:

grafik

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
Copy link
Owner

j123b567 commented Nov 8, 2021

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
Copy link
Contributor Author

MisterHW commented Jan 31, 2022 •
edited
Loading

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.

image

@MisterHW
Copy link
Contributor Author

MisterHW commented Feb 1, 2022

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.

#134 adds this behaviour, plus some minor clean-up. #134 becomes a prerequisite for #129.

@MisterHW MisterHW linked a pull request Feb 3, 2022 that will close this issue
Open
@MisterHW
Copy link
Contributor Author

MisterHW commented Feb 7, 2022

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:

grafik

@MisterHW
Copy link
Contributor Author

@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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

introduce SCPI_HelpQ with descriptions MisterHW/scpi-parser
2 participants
@j123b567 @MisterHW