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

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

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

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

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

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

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