This is mostly and idea at the moment. I will use this issue as a sounding board to develop the idea.
In working on #3028 and #3030, I found it difficult to manage the additions to the CLI code. The issues break down to a couple of basic problems:
- The CLI code is a huge blob in one file that is hard to see the relations between some of the commands (i.e.
get and set commands). This leads to issues where code can become out sync. In several cases the CLI documentation varies from what is actually done in code.
- The parsing of the command relies on looking at specific character offsets rather than tokenizing the command. This is prone to errors inadvertently introduced where the character offset is mis-calculated. It may also not collapse whitespace down to a single occurrence which would also cause the command not to be recognized.
The first thought to move forward is to provide a registration function where code could register a callback function for processing the command. This would allow the CLI command code to be broken into modules based on function (e.g. sensor commands, bridge commands, core functionality, etc.). This would make the code and any changes much more manageable. In addition, it allows related commands (mostly get and set) to reside closer to one another to avoid drift.
The above would require a rebuild of how the parser operates (principally tokenization) and commands would need moved to using the new parser. I think the way I would engineer this is that a module would register the commands that it accepts (i.e. get bridge.type and set bridge.type). When these commands are parsed, the callback function is make with the base command that was registers and a list of parameters that have been specified on the command line. These parameters would already be tokenized so the callback function would not need to have a lot of need to further parse the parameters. It could just operate on the parameter list directly.
Because the commands are all pre-registered, it would be possible to generate help text at the command line also. Not sure what this looks like yet and sending a couple dozen command descriptions over LORA may not be desirable. Maybe the help would require a search term so that the list of command descriptions can be reduced to a manageable size for over the air.
I think part of this process is to also incorporate the command documentation into the module so that the documentation is right with the code. This should combat the documentation drift that is currently plaguing cli_commands.md. The documentation could then be generated during the release process and upon request. Ideally, the documentation should be able to be kept up to date.
Is there a PR checklist? Ideally I would think that you would have a PR template that would have a form for submitting a PR that would allow the inclusion of "has the documentation been updated if there was a CLI code change?".
This is mostly and idea at the moment. I will use this issue as a sounding board to develop the idea.
In working on #3028 and #3030, I found it difficult to manage the additions to the CLI code. The issues break down to a couple of basic problems:
getandsetcommands). This leads to issues where code can become out sync. In several cases the CLI documentation varies from what is actually done in code.The first thought to move forward is to provide a registration function where code could register a callback function for processing the command. This would allow the CLI command code to be broken into modules based on function (e.g. sensor commands, bridge commands, core functionality, etc.). This would make the code and any changes much more manageable. In addition, it allows related commands (mostly
getandset) to reside closer to one another to avoid drift.The above would require a rebuild of how the parser operates (principally tokenization) and commands would need moved to using the new parser. I think the way I would engineer this is that a module would register the commands that it accepts (i.e.
get bridge.typeandset bridge.type). When these commands are parsed, the callback function is make with the base command that was registers and a list of parameters that have been specified on the command line. These parameters would already be tokenized so the callback function would not need to have a lot of need to further parse the parameters. It could just operate on the parameter list directly.Because the commands are all pre-registered, it would be possible to generate help text at the command line also. Not sure what this looks like yet and sending a couple dozen command descriptions over LORA may not be desirable. Maybe the help would require a search term so that the list of command descriptions can be reduced to a manageable size for over the air.
I think part of this process is to also incorporate the command documentation into the module so that the documentation is right with the code. This should combat the documentation drift that is currently plaguing
cli_commands.md. The documentation could then be generated during the release process and upon request. Ideally, the documentation should be able to be kept up to date.Is there a PR checklist? Ideally I would think that you would have a PR template that would have a form for submitting a PR that would allow the inclusion of "has the documentation been updated if there was a CLI code change?".