introduction of macroArg command

doc-dev/reference-manual.md

@@ -41,7 +41,7 @@ $onJoin
 $onSplit
 ```
 
-i.e., if you want to customize the acceleration driver for your trackball module on keymap QWR, create a macro named `$onKeymapChange QWR`, with content e.g.:
+For example, if you want to customize the acceleration driver for your trackball module on keymap QWR, create a macro named `$onKeymapChange QWR` containing:
 
 ```
 set module.trackball.baseSpeed 0.5
@@ -195,6 +195,8 @@ COMMAND = set bluetooth.enabled BOOL
 COMMAND = set bluetooth.alwaysAdvertiseHid BOOL
 COMMAND = set modifierLayerTriggers.{shift|alt|super|ctrl} {left|right|both}
 COMMAND = &macroArg.<macro argument index (INT)>
+COMMAND = macroArg <argument name (IDENTIFIER)> [: MACROARG_TYPE] <argument description (STRING)>
+MACROARG_TYPE = { int | float | bool | string | keyid | scancode | any }
 CONDITION = <condition>
 CONDITION = if (EXPRESSION)
 CONDITION = else
@@ -233,7 +235,7 @@ KEYMAPID = <short keymap abbreviation(IDENTIFIER)>|last|current
 MACROID = last | <single char slot identifier(CHAR)> | <single number slot identifier(INT)>
 OPERATOR = + | - | * | / | % | < | > | <= | >= | == | != | && | ||
 VARIABLE_EXPANSION = $<variable name(IDENTIFIER)> | $<config value name>
-VARIABLE_EXPANSION = $currentAddress | $currentTime | $thisKeyId | $queuedKeyId.<queue index (INT)> | $keyId.KEYID_ABBREV | $uhk.name | $macroArg.<macro argument index (INT)>
+VARIABLE_EXPANSION = $currentAddress | $currentTime | $thisKeyId | $queuedKeyId.<queue index (INT)> | $keyId.KEYID_ABBREV | $uhk.name | $macroArg.<macro argument index (INT)> | $macroArg.<macro argument name (IDENTIFIER)>
 EXPRESSION = <expression> | (EXPRESSION) | INT | BOOL | FLOAT | VARIABLE_EXPANSION | EXPRESSION OPERATOR EXPRESSION | !EXPRESSION | min(EXPRESSION [, EXPRESSION]+) | max(EXPRESSION [, EXPRESSION]+)
 EXPRESSION = STRING == STRING | STRING != STRING
 PARENTHESSED_EXPRESSION = (EXPRESSION)
@@ -609,6 +611,12 @@ Key actions can be parametrized with macro arguments. These arguments can be exp
   - the argument bounds must correspond to token bounds in the fully expanded string
   - the argument cannot span multiple lines
 
+### Named Arguments
+
+Macro arguments can also be named and typed by declaring them using the `macroArg` command at the beginning of the macro.
+
+Such named arguments can also be accessed using `$macroArg.<name>`, and the value provided by Agent will be parsed according to the argument type.
+
 ### Configuration options
 
 - `set stickyModifiers {never|smart|always}` globally turns on or off sticky modifiers. This affects only standard scancode actions. Macro actions (both gui and command ones) are always nonsticky, unless `sticky` flag is included in `tapKey|holdKey|pressKey` commands. Default value is `smart`, which is the official behaviour - i.e., `<alt/ctrl/gui> + <tab/arrows>` are sticky.

doc-dev/user-guide.md

@@ -55,9 +55,9 @@ ifDoubletap tapKey capsLock
         - Provided value bounds are informational only - they denote values that seem to make sense. Sometimes default values are marked.
     - If you are still not sure about some feature or syntax, do not hesitate to ask.
 
-3) If `ERR` appears on the display, you can retrieve the description by using `printStatus` over a focused text editor. Or, using the above point, just search the [reference manual](reference-manual.md) for `ERR`.
+3) If `ERR` appears on the display (UHK60), or a triangle warning icon `⚠️` is shown on the display (UHK80), you can retrieve the error description by using `printStatus` over a focused text editor. In addition, a yellow error pane will automatically appear in Agent, showing the error description. You can also search the [reference manual](reference-manual.md) for `ERR`.
 
-4) If you encounter a bug, let me know. There are lots of features and quite few users around this codebase - if you do not report problems you find, chances are that no one else will (since most likely no one else has noticed).
+4) If you encounter a bug, let us know (ideally, by reporting a GitHub issue). There are lots of features and quite few users around this codebase - if you do not report problems you find, chances are that no one else will (since most likely no one else has noticed).
 
 ## Known software limitations and oddities
 
@@ -114,6 +114,15 @@ replaceLayer mod QTY mod
 replaceLayer mouse QTY mouse
 ```
 
+Alternatively, you can also replace all of the keymap first, and the just load the base layer of your keymap again. For this approach, your macro would be:
+
+```
+replaceKeymap QTY
+overlayKeymap current
+```
+
+This second method also allows you to only define some keys on the COL base layer that need to change from QTY. Any key mapped to "None" inherits its action from QTY, as `overlayKeymap` will not overload it.
+
 ## Examples
 
 Every nonempty line is considered as one command. Empty line, or commented line too. Empty lines are skipped. Exception is an empty command action, which counts for one command. Even `{` and `}` are treated as commands, and have to be on separate lines.

right/src/macros/command_hash.gperf

@@ -88,6 +88,7 @@ ifRegEq, CommandId_ifRegEq
 ifNotRegEq, CommandId_ifNotRegEq
 ifRegGt, CommandId_ifRegGt
 ifRegLt, CommandId_ifRegLt
+macroArg, CommandId_macroArg
 mulReg, CommandId_mulReg
 noOp, CommandId_noOp
 notify, CommandId_notify

right/src/macros/command_ids.h

@@ -107,6 +107,7 @@ typedef enum {
     CommandId_ifRegLt,      // deprecated
 
     // 'm' commands
+    CommandId_macroArg,
     CommandId_mulReg,  // deprecated
 
     // 'n' commands