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

introduce SCPI_HelpQ with descriptions #135

Open
wants to merge 24 commits into
base: master
Choose a base branch
from
Open

introduce SCPI_HelpQ with descriptions #135

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
28b17f7
output block data with delimiter
MisterHW Feb 1, 2022
8ed2623
fix typos
MisterHW Feb 2, 2022
bc4f1d5
introduce SCPI_HelpQ
MisterHW Feb 3, 2022
315f20d
introduce help search
MisterHW Feb 7, 2022
159fe83
drop C++20 keyword
MisterHW Feb 7, 2022
d099d9a
rename to USE_HELP_FILTER
MisterHW Feb 7, 2022
aa660db
fix expression
MisterHW Feb 7, 2022
1460793
add full command descriptions to examples common def, set desc. defau…
MisterHW Jan 6, 2023
7d0c83d
clean-up
MisterHW Jan 7, 2023
c394eb9
propagate MODE to Makefile for cross-compiling
MisterHW Jan 7, 2023
1e1b594
provide more elaborate description depending on USE_HELP_FILTER
MisterHW Jan 14, 2023
f7c4cc4
Merge branch 'j123b567:master' into scpi_helpq_enhancement
MisterHW Jan 16, 2023
b3668be
Merge branch 'j123b567:master' into scpi_helpq_enhancement
MisterHW Jan 17, 2023
36ddafe
strncasestr, strncasestrn_s, pp_xstr clean-up and formatting
MisterHW Jan 17, 2023
9c66dcd
fix C89 issue (FALSE, for syntax)
MisterHW Jan 17, 2023
0e7c828
remove strcasestr
MisterHW Jan 17, 2023
5dfac2b
strncasecmp -> SCPIDEFINE_strncasecmp
MisterHW Jan 17, 2023
5153e03
C style comments
MisterHW Jan 17, 2023
8aa90a7
split off HELP? into help.h/.c
MisterHW Jan 17, 2023
31a3e44
add help.c, help.h to Makefile
MisterHW Jan 17, 2023
d8a5d24
redo delete SCPI_HelpQ
MisterHW Jan 17, 2023
63f5e88
Revert "propagate MODE to Makefile for cross-compiling"
MisterHW Jan 17, 2023
d803ffe
simply SCPI_CMD_LIST_END definition
MisterHW Jan 17, 2023
a44b9aa
add missing ,
MisterHW Jan 17, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
provide more elaborate description depending on USE_HELP_FILTER 
When compiled with USE_HELP_FILTER 1, HELP? accepts an optional search string -> HELP? command description extended to reflect input and output types.
  • Loading branch information
@MisterHW
MisterHW committed Jan 14, 2023
commit 1e1b594e491312b6550081ba73177b7a41e31f4d
7 changes: 5 additions & 2 deletions examples/common/scpi-def.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,8 +359,11 @@ static scpi_result_t My_CoreTstQ(scpi_t * context) {

const scpi_command_t scpi_commands[] = {
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please provide alternative definition files for this functionality?

It is a generally useful but unusual extension. I would like to keep examples simple. Users can decide on their own if they would like to use help command or not and it is generally not needed. It will find its way, but I would like to keep the first impression simple.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternatively, somehow divide the existing source (it is just an example anyway) so one part of the commands has help and the other does not so it is clear, that it is not mandatory to use and define help and tag.

Copy link
Contributor Author

@MisterHW MisterHW Jan 17, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

scpi-def.c and scpi-def.cpp are essentially identical. scpi-def.c could be stripped down to illustrate what a version with no help and no command tags could look like. One could additionally introduce

#define NO_CMD_DESC SCPI_CMD_DESC(NULL)

which would help being explicit about the generalized structure. With scpi-def being in common, offering definitions for all possible cases seems a bit excessive to me.

Retrospective Context:
Keep in mind that prior to this PR, the default was

#define USE_COMMAND_TAGS 1

and setting it to 0 would cause a type mismatch, as in scpi-def.c/.cpp there were extra (unconditional) , 0 in the scpi_commands[] items.

The documentation on HELP? might be the best place to elaborate on way to further strip down the definition and explain the implications. This was warrented through the existence of USE_COMMAND_TAGS, and in my opinion is underscored yet again through the introduction of USE_COMMAND_DESCRIPTIONS.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, scpi-def.cpp is identical to the scpi-def.c but all C specific features are removed so it can be compiled by the C++ compiler. Because this is C library, C++ file is just an example without real usage here.

Initially, examples were more about the communication interface and the command interface was the same. In the current perspective, there could be more standalone examples promoting separate features of the library, like enabling/disabling TAGs, and more importantly, introducing HELP? command.

Maybe, there can be a new example based on e.g. test-interactive to show, how HELP? command works and how to define all strings. It can have a completely different structure and its own commands definition.

/* Optional help command */
{"HELP?", SCPI_HelpQ, SCPI_CMD_DESC("\t - list supported commands") SCPI_CMD_TAG(0)},

#if USE_HELP_FILTER
{"HELP?", SCPI_HelpQ, SCPI_CMD_DESC("[<string>] - list supported commands [containing \"<string>\"] (multiple block data)") SCPI_CMD_TAG(0)},
#else
{"HELP?", SCPI_HelpQ, SCPI_CMD_DESC("\t - list supported commands (multiple block data)") SCPI_CMD_TAG(0)},
#endif
/* IEEE Mandated Commands (SCPI std V1999.0 4.1.1): *CLS *ESE *ESE? *ESR? *IDN? *OPC *OPC? *RST *SRE *SRE? *STB? *TST? *WAI */
{"*CLS", SCPI_CoreCls, SCPI_CMD_DESC("\t - clear all Event Status registers, errors, output queue") SCPI_CMD_TAG(0)},
// -- Standard Event Status Group [EVENT]-[ENABLE]
Expand Down
6 changes: 5 additions & 1 deletion examples/common/scpi-def.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -359,7 +359,11 @@ static scpi_result_t My_CoreTstQ(scpi_t * context) {

const scpi_command_t scpi_commands[] = {
/* Optional help command */
{"HELP?", SCPI_HelpQ, SCPI_CMD_DESC("\t - list supported commands") SCPI_CMD_TAG(0)},
#if USE_HELP_FILTER
{"HELP?", SCPI_HelpQ, SCPI_CMD_DESC("[<string>] - list supported commands [containing \"<string>\"] (multiple block data)") SCPI_CMD_TAG(0)},
#else
{"HELP?", SCPI_HelpQ, SCPI_CMD_DESC("\t - list supported commands (multiple block data)") SCPI_CMD_TAG(0)},
#endif

/* IEEE Mandated Commands (SCPI std V1999.0 4.1.1): *CLS *ESE *ESE? *ESR? *IDN? *OPC *OPC? *RST *SRE *SRE? *STB? *TST? *WAI */
{"*CLS", SCPI_CoreCls, SCPI_CMD_DESC("\t - clear all Event Status registers, errors, output queue") SCPI_CMD_TAG(0)},
MisterHW marked this conversation as resolved.
Show resolved Hide resolved
Expand Down