descriptive labels and types for $macroArgs

[mhantsch]

Parse macros for declarations of macroArgs.
Display descriptive labels (instead of "$macroArg.x") in front of value fields.
Based on the type of each macroArg, allow only input of permitted values.

This is a first draft for this Agent feature.

Example:

// macroArg.1:scancode Scancode for solo activation
// macroArg.2:scancode Scancode for combo activation
// macroArg.3:keyid Key to check for combo
// macroArg.4:int Timeout in ms
ifShortcut timeoutIn $macroArg.4 &macroArg.3 final holdKey &macroArg.2
holdKey &macroArg.1

Agent would parse the comments and understand to show four arguments to be filled out.

• Argument 1 is labelled "Scancode for solo activation" and needs a Scancode + Mod selection
• Argument 2 is labelled "Scancode for combo activation" and also needs a Scancode + Mod selection.
• Argument 3 is labelled "Key to check for combo" and needs a Key ID selection.
• Argument 4 is labelled "Timeout in ms" and needs an integer.

Instead of "$macroArg.1", "$macroArg.2" etc. Agent would show the descriptions from the declaration.

For the value field, Agent would allow only allowed values according to the type:

• For int, the value needs to match the regex /[0-9]+/
• For float, the value needs to match the regex /[0-9\.]+/
• For string, the value can be anything, but will be put between single quotes automatically, and any single quotes and escape characters will be escaped.
• For keyid, a popup will allow only the selection of key legends, and the values field will internally be set to the KEYID for that legend.
• For scancode, a popup will allow only the selection of scancodes (similar to Keypress action), and buttons for modifiers will be shown (again, similar to Keypress action). The value field will internally be set to the corresponding SHORTCUT.
• For verbatim, the value can be anything, and it will be passed verbatim (= as entered) without any checks. This is identical to macroArg parameters which were added manually in Agent (although it will be labelled with the description instead of "$macroArg.x").

This feature works without any changes to firmware or config structure.

[mondalaci]

I love it!

Instead of verbatim , I'd prefer something more familiar to programmers, possibly void.

I'm unsure about macroArg.X; argX or $X would be simpler, but they don't reflect the macro language. However, to accurately reflect the language, we should use $macroArg.X or &macroArg.1, depending on the final syntax.

@kareltucek Any opinions, suggestions?

[kareltucek]

• void and anything are two substantially different things. For familiarity, I would suggest any. (Yay, three people, three opinions.)
• If we are really doing this, we should do it properly.
• Who writes those comments? If you expect the user to write them, then this is a thing for selected few.
• I dislike the idea o doing this via comments quite a lot, and so would prefer to store them in the macro structure (was that the purpose?), and in that case we can as well introduce the name indirection (the name then would be &macroArg.foo).

For keyid, a popup will allow only the selection of key legends, and the values field will internally be set to the KEYID for that legend.
For scancode, a popup will allow only the selection of scancodes (similar to Keypress action), and buttons for modifiers will be shown (again, similar to Keypress action). The value field will internally be set to the corresponding SHORTCUT.

KEYID (a number) or KEYID_ABBREV (a string)?

Will this be grammar driven? (It can be. It should be fairly easy to ask the autocomplete library to give anything matching KEYID_ABBREV or SCANCODE_ABBREV)

[mondalaci]

any is great.

Implementing this feature at the user config level is more integrated and makes better use of the configuration space. I'm fine with it if you have time for it eventually. It's not a priority.

Should we move this issue to the firmware repo?

[kareltucek]

Feel free to.

[mhantsch]

I thought you wanted this to be an Agent-based feature only, without changes to firmware. But I'm fine if you want to enhance it through some firmware support.

any is good. I was torn between any and verbatim when I spec'ed it originally. 😏

Users who create macros will write the declarations. Users can copy/paste macros from posts in the forum, and Agent will start showing the parameters automatically when they assign the macro to an action.

If you want to make this feature a proper part of the language, here's my take on a step-by-step implementation:

Step 1: minimal change to firmware

• arguments are prefixed with $macroArg or &macroArg just like today (no change in firmware)
• arguments are named in declaration, but are also automatically numbered in the order they are listed (Agent just displays them in the order listed)
• only change in firmware: ignore all macroArg commands
• arguments can be accessed via number just like today (no change in firmware)
• Agent can be changed to parse macroArg statements and show the new UI
  • step A: just name the args in Agent; no parameter validation
  • step B: Agent also performs parameter validation (check against regex)
  • step C: Agent supports new-style entry fields (pop-up lists, modifier buttons) for scancode and keyid values

This gives
a) minimal changes in firmware
b) Agent development can start; also in steps.

Immediate benefits for users:

• Agent step A: macro args show up automatically in Agent in correct amount, order, and with descriptive name.
• Agent step B: users are forced to enter valid values
• Agent step C: users are guided to the correct entries for scancode and keyid through UI selections and button clicks

macroArg solo_key:scancode Scancode for solo activation
macroArg combo_key:scancode Scancode for combo activation
macroArg other_key:keyid Key to check for combo
macroArg combo_timeout:int Timeout in ms
ifShortcut timeoutIn $macroArg.4 &macroArg.3 final holdKey &macroArg.2
holdKey &macroArg.1

---

Step 2: more changes to firmware

• arguments are prefixed with $macroArg or &macroArg just like today (no change in firmware)
• arguments are named in declaration, but are also automatically numbered in the order they are listed (Agent just displays them in the order listed)
• firmware parses macroArg commands and remembers the macroArg names
• arguments can still be accessed via number just like today (no immediate changes to macros needed)
• arguments can also be accessed via names (new style macros can be written)

macroArg solo_key:scancode Scancode for solo activation
macroArg combo_key:scancode Scancode for combo activation
macroArg other_key:keyid Key to check for combo
macroArg combo_timeout:int Timeout in ms
ifShortcut timeoutIn $macroArg.4 $macroArg.3 final holdKey $macroArg.combo_key
holdKey $macroArg.solo_key

---

Step 3, Option 1: always access arguments with $macroArg.<name>

• all arguments are prefixed with $macroArg, no & notation ($macroArg is functionally equivalent to the current & notation)
• declaration keyword is macroArg
• arguments are named
• (optional) no numbered access to arguments anymore

macroArg solo_key:scancode Scancode for solo activation
macroArg combo_key:scancode Scancode for combo activation
macroArg other_key:keyid Key to check for combo
macroArg combo_timeout:int Timeout in ms
ifShortcut timeoutIn $macroArg.combo_timeout $macroArg.other_key final holdKey $macroArg.combo_key
holdKey $macroArg.solo_key

---

Step 3, Option 2: declare arguments with param, access with &<name>

• arguments are prefixed with &, no macroArg needed in front when accessing argument (saves macro space)
• declaration keyword is param (optional, I'm just trying out how that would look like; feel free to keep macroArg)
• arguments must be named
• no numbered access to arguments anymore

param solo_key:scancode Scancode for solo activation
param combo_key:scancode Scancode for combo activation
param other_key:keyid Key to check for combo
param combo_timeout:int Timeout in ms
ifShortcut timeoutIn &combo_timeout &other_key final holdKey &combo_key
holdKey &solo_key

[mhantsch]

Oh, and if a macro doesn't have any macroArg declarations, then Agent will still allow users to manually add arguments in the UI. (Compatibility to today.)

[mondalaci]

Macro sharing is a strong argument I hadn't considered, and on second thought, I prefer to use the JSDoc-like approach, whether with comments or a dedicated param command. Unlike Karel, I consider this a proper solution, especially for sharing macros.

I wouldn't force users to use parameter declarations, but leave it optional.

Named argument declarations are nice, but I don't insist on them. Having a noOp macroArg command, however, doesn't make sense to me.

[mhantsch]

The noOp macroArg command (or param) makes the argument declaration a proper language element, even if the firmware ignores it at first. A later extension of the firmware can then use named arguments and possibly types -- independent of the Agent implementation; and existing macros will continue to work and just gain better semantics. If you just keep information in comments, Agent may parse them, but the firmware really should not, as they are not part of the language.

Separating the implementation in steps, as I suggested, makes sense to me for the following reasons:

• you don't have to implement everything at once
• Every step is reasonably small
• Every step delivers some benefit for users, and every subsequent step adds more
• you can stop, observe and collect feedback from users at any step
• Agent and firmware implementations are largely decoupled
• Firmware implementation minimal at first (just ignore macroArg) -- @kareltucek has enough on his plate already
• Agent implementation is broken down in Steps, too -- @ert78gb can do as little or as much as is feasible
• Backwards compatibility with macros and configuration built at a previous step
• you don't have to implement the full thing, and you still have some useful improvements
• if you implement all steps, the end result will be a consistent, full-featured, and arguably elegant design for both user interface and macro language

As a tiny first step, I would suggest:

• add macroArg (or param) command to the macro language
  • macroArg <name>:<type> <descriptive label>
• firmware: parse and ignore macroArg command
• Agent: read macroArg from each macro, build argument list for UI, label each argument with descriptive label
  => Agent will now automatically show value fields for all arguments that a macro requires, and there will be proper descriptions for each argument

As a second step, I would then:

• Agent: use the type of each argument to validate its value according to regex, or in case of keyid and scancode/shortcut, offer autocomplete suggestions.
  => users will be forced (or guided) to enter correct values

At that stage I would stop and observe how users like it, how the use it, and then re-assess what the next steps should be, or whether it is good enough for now.

I think this approach gives the most value for the smallest implementation efforts.

[mondalaci]

I think this feature set isn't so large to justify a multi-step rollout. We just have to find the time to implement it, and it's not urgent. I prefer optional named arguments.

[kareltucek]

I have skimmed your text very briefly @mhantsch, so please let me know if I have missed anything important...

Macro sharing indeed strongly argues toward these information be stored within macro test.

Declarations within active macro text have a serious issue: they can be made conditional.

Declarations within comments have a serious issue: they are comments. They are not meant to use this way. It is an ugly solution and prone to be damaged by various tools that simply assume they should not touch comments.

I don't feel strongly about either of those.

[mhantsch]

Declarations within active macro text have a serious issue: they can be made conditional.

My brain works better with examples, do you mean something like:

ifHold macroArg myparam:int Time to wait
delayUntil $macroArg.myparam

That of course is functional nonsense, and should not be allowed.

Is there a way to make macroArg declarations only work as the very first commands in a macro? Something like:

#########################
# GENERAL FUNCTIONALITY #
#########################
MACRO = [HEADER] BODY
HEADER = COMMENT
HEADER = DECLARATION [COMMENT]
DECLARATION = <declaration command>
DECLARATION = macroArg ...
BODY = COMMENT
BODY = [LABEL:] COMMAND [COMMENT]
COMMENT = //<comment>
...

[kareltucek]

Yes, we can do something like that I guess, but it is an ugly irregularity in the language :-/.

The implementation is also troublesome as this means that we have to store them somewhere. I don't have an idea where to store them.

Parsing the body each time we encounter macroArg expansion just to find and compare the names... I don't want to do that.

[kareltucek]

I guess these would have to be local variables of a special new type, destroyed when the macro ends. This is doable I guess.