Keyboard Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com

On this page

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.

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