How to resolve CAPS and NCAPS ambiguity in Keyman keyboards

Keyman Developer 15 has added a new warning when it detects rules which may be ambiguous around use of Caps Lock:

Warning: 20AD Other rules which reference this key include CAPS or NCAPS modifiers, so this rule must include NCAPS modifier to avoid inconsistent matches

This blog post is a walk through of when this warning is generated, and how to resolve the warning.

By default, in a Keyman keyboard, if you do not specify the Caps Lock state for a rule using either CAPS or NCAPS, then the Caps Lock state is undefined. This means that a rule such as + [K_A] would match both Caps Lock + A and A. That’s by design, because many keyboards do not care about the Caps Lock state.

However, if you then add a second rule that does match Caps Lock state, e.g. + [CAPS K_A], there is now ambiguity as to which rule has precedence. Due to the way the keyboard is compiled for KeymanWeb, one of the rules may never be fired, even if it has a distinct context.

The solution is to be consistent in your use of NCAPS and CAPS. If you use these modifiers in any rule for a given virtual key, then you must use the modifiers for all rules that reference that virtual key. This applies whether you define the rule as + 'a' or + [K_A] — the first form should not be used if you are using CAPS and NCAPS.

One final hint: you can use the &CasedKeys store to simplify this further: if you define any key which may be affected by Caps Lock in this store, then you can avoid having to specify CAPS and NCAPS again:

store(&CasedKeys) [K_A]

c this expands to two rules: + [NCAPS K_A], + [SHIFT CAPS K_A]
+ 'a' > 'The Letter a' 

c and then this rule is okay
'x' + [NCAPS K_A] > 'x and a'