[Ovmsdev] Addition to OVMS Developer Guide

[Stephen Casner]

Michael,

On Fri, 1 Jan 2021, Michael Balzer wrote:
> Positional optional parameters don't grow well for multiple options, force
> users to a fixed argument scheme and tend to produce hardly readable commands.
> I also think command options are for experienced/advanced users, and those are
> familiar with the concept.

As I said, I agree that there are some situations like obdii where the
variability of operations is too complex for positional optional
parameters.  However, I don't consider a fixed argument scheme to be a
bad thing for many of our commands.  Do you consider the scheme I've
set up for "location action" to be hardly readable?

> Extending the parser to support command argument templates would be an option,
> but I had the impression that would add a lot of complexity, and would only
> benefit a small set of (advanced) commands.

I agree that it makes sense to implement the flag options directly for
those commands where it is appropriate.

> Agreed for the case of a single option and a command that's not supposed to
> grow any new features. I did so on some of the CANopen commands. But imagine
> we need to add another numerical option to "event raise": nice and clean by
> prefix options, a usability nightmare with positional args.

Depends whether the options are truly independent.

> I wasn't aware of the tab completion on "event raise"... I normally use the
> command to raise custom events only. I'll fix that.

Are those custom events not registered?  RegisterEvent() adds events
to m_map which makes them available for tab completion.

> > With the flexibility to have intermediate parameters now, using the
> > validate function, it may fit reasonably to have the options handled
> > by a subtree.
> >
> >                                                          -- Steve
>
> Do you mean a secondary option subtree triggered by the "-" prefix, inherited
> to the regular command subtree?
>
> That would allow simple tab completion on options as well... sounds like a
> nice idea.

What I was referring to was that when there are multiple options
needing their own argument schemes that can be handled by the subtree
of OvmsCommand nodes that can follow an intermediate parameter, as in
the "location action" command.

Tab completion wouldn't provide any benefit for single-letter option
flags, but if options were words, as is the case for the different
actions that can happen on a location, then it's useful.

I'm not sure if you were thinking of detatched command subtrees.  I
considered that idea when designing the validation scheme to allow
intermediate parameters, but decided against it because I did not
figure out a way to implement it cleanly including linking back up to
the root for dynamic generation of the usage message.

                                                        -- Steve