Using Rules

---

A rule is the basic part of a Keyman keyboard. Each rule defines what a keystroke will output, when certain characters are already displayed on the screen. A rule is also used to pre-process and post-process the characters being output to the screen.

A rule is made up of three parts:

context + keystroke > output

The context refers to what is already displayed on the screen. A rule will only be fired if the context and the keystroke both match. The output will replace the context matched on the left hand side of the rule.

In advanced groups, the keystroke section of the rule may be omitted for processing on the context and output.

Rule Order {#rule-order}

Rules have a special order. They are ordered first by length of context, with longest context first, and then by line order in the file. This slightly non-intuitive ordering makes it much simpler to group rules according to their function, rather than necessarily by their priority.

See also groups.

Statement Use {#statement-use}

The three different parts of a rule may contain Unicode characters and various statements.

Context Statement Use {#context-statement-use}

The context part of the rule may contain Unicode characters and certain statements:

nul statement : Enforces empty context.

if() statement : Tests a store or system state for a value

baselayout() statement : Determines the current system hardware keyboard layout

platform() statement : Determines the current platform keyboard is operating on

any() statement : Matches on an array of characters

context statement : Outputs the context part of a rule (single character only)

deadkey(), dk() statement : Matches and generates deadkeys

index() statement : Outputs from an array of characters

notany() statement : Matches anything not in a particular array of characters

outs() statement : Outputs an array of characters

Certain statements must appear in specific positions in the rule. The following order is enforced by the compiler:

1. nul
2. if(), baselayout() and platform()
3. All other statements and characters

Keystroke Statement Use {#keystroke-statement-use}

The keystroke part of the rule may contain a Unicode character representing the value on the key cap of the base keyboard, a virtual key, a virtual character key, or one of the following statements:

any() statement : Matches on an array of characters

outs() statement : Outputs an array of characters

Only a single character, statement, virtual character key or virtual key is allowed in the keystroke part of the rule.

• Keys, virtual keys, and virtual character Keys

Output Statement Use {#output-statement-use}

The output part of the rule may contain Unicode characters and certain statements:

beep statement : Generates a beep on the speaker (or a flash on web devices)

call() statement : Calls an Input Method Extension

context statement : Outputs the context part of a rule

deadkey(), dk() statement : Matches and generates deadkeys

index() statement : Outputs from an array of characters

layer() statement : Sets the current touch keyboard layer visible on the on screen keyboard

nul statement : Forces no output on a rule, or enforces empty context

outs() statement : Outputs an array of characters

reset() statement : Resets a store to its initial value

return statement : Stops processing of the current keystroke

save() statement : Persists a store value for next edit session

set() statement : Sets a store or system state to a specific value

use() statement : Starts processing in another group

Note: In read-only groups, only a subset of these statements may be used.

context statement {#context-statement}

One of the important statements that can be used in rules is the context statement.

The context statement will transfer the context of the rule into the output, for example:

"abc" + "d" > context "D"

will, when abc is on the screen, and d is pressed, replace abc with abcD. You can also put a single character from the context into the output using context():

"abc" + "d" > "D" context(2)

This will output Db when abcd is typed.

History

• 14.0: The compiler now enforces order of statements within the context part of the rule